@popoverai/dotrequirements 0.33.0 → 0.34.0

package/dist/commands/solution/share.js

@@ -0,0 +1,346 @@
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { ConvexHttpClient } from "convex/browser";
+import { ConvexError } from "convex/values";
+import { parse } from "yaml";
+import { convexUrl, webApiUrl } from "../../cloud.js";
+import { api } from "../../convex.js";
+import { extractFrontmatterBlock, stripFrontmatterBlock, } from "../../schema/parser-core.js";
+import { refusal } from "./client.js";
+import { layOut, recordSavedIds, } from "./working-folder.js";
+/**
+ * A solution's share command, from any repository (SOLSHARE; design in
+ * docs/working/solution-branches.md, "Handing the build to the people who
+ * do it"): `dotreq solution checkout --share <token> --outcome "<name>"`
+ * lays the solution's work out and records, under the solution's folder,
+ * which solution, outcome and round it was for; `dotreq solution push` sends the
+ * changed documents to the solution's branch; `dotreq solution done` closes
+ * the round it was checked out for. The token is the only credential, and
+ * the record stays out of git.
+ */
+const RECORD = ".checkout.json";
+const SOLUTIONS = path.join(".requirements", "solutions");
+/** What stays out of git in a solution's folder: the record, which holds the token, and the rendered mockups. */
+const IGNORED = [RECORD, "mockups/"];
+/**
+ * The verbs as the share command runs them, with no install: a developer
+ * who ran `npx` has no `dotreq` on their path.
+ */
+export const SHARE_CLI = "npx @popoverai/dotrequirements@latest solution";
+/**
+ * Work from the repository's root, whichever folder the command was run
+ * in, so that a checkout from a subfolder and a push from the root see the
+ * same record. Outside a git repository, where it was run.
+ */
+function atRepositoryRoot() {
+    try {
+        const root = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        if (root)
+            process.chdir(root);
+    }
+    catch {
+        // Not a git repository: the folder it was run in is the repository.
+    }
+}
+/** Calls on the share command's token alone: no project is linked, and none is needed. */
+function shareClient() {
+    const client = new ConvexHttpClient(convexUrl());
+    const inWords = async (call) => {
+        try {
+            return await call();
+        }
+        catch (error) {
+            if (error instanceof ConvexError)
+                throw new Error(refusal(error.data));
+            throw error;
+        }
+    };
+    return {
+        query: (fn, args) => inWords(() => client.query(fn, args)),
+        mutation: (fn, args) => inWords(() => client.mutation(fn, args)),
+    };
+}
+function hashOf(file) {
+    return createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+}
+function recordPath(directory) {
+    return path.join(SOLUTIONS, directory, RECORD);
+}
+/** Every solution checked out into this repository, by its folder. */
+export function checkedOut() {
+    if (!fs.existsSync(SOLUTIONS))
+        return [];
+    return fs
+        .readdirSync(SOLUTIONS)
+        .map((directory) => recordPath(directory))
+        .filter((file) => fs.existsSync(file))
+        .map((file) => JSON.parse(fs.readFileSync(file, "utf-8")));
+}
+/** The one solution a push or done is for, or why it can't tell (SOLSHARE-3.7, 4.6, 4.7). */
+function oneCheckedOut(solution) {
+    const records = checkedOut();
+    if (records.length === 0) {
+        throw new Error("No solution is checked out here: run the share command you were given first.");
+    }
+    if (solution) {
+        const found = records.find((record) => record.solution.id === solution ||
+            record.solution.directory === solution);
+        if (!found) {
+            throw new Error(`"${solution}" isn't checked out here. Checked out: ${records.map((record) => record.solution.directory).join(", ")}.`);
+        }
+        return found;
+    }
+    if (records.length > 1) {
+        throw new Error(`More than one solution is checked out here; say which with --solution: ${records.map((record) => record.solution.directory).join(", ")}.`);
+    }
+    return records[0];
+}
+function writeRecord(record) {
+    const directory = path.join(SOLUTIONS, record.solution.directory);
+    fs.mkdirSync(directory, { recursive: true });
+    fs.writeFileSync(recordPath(record.solution.directory), `${JSON.stringify(record, null, 2)}\n`);
+    // The record holds the token, and the mockups are renders: both stay out
+    // of the repository's history. Lines the developer added are kept.
+    const ignore = path.join(directory, ".gitignore");
+    const lines = fs.existsSync(ignore)
+        ? fs.readFileSync(ignore, "utf-8").split("\n").filter(Boolean)
+        : [];
+    const missing = IGNORED.filter((line) => !lines.includes(line));
+    if (missing.length > 0) {
+        fs.writeFileSync(ignore, `${[...lines, ...missing].join("\n")}\n`);
+    }
+}
+/**
+ * Markdown files under `.requirements/`, with the document id each one's
+ * frontmatter names. A file whose frontmatter can't be read is set aside,
+ * with a warning, rather than stopping the command.
+ */
+function requirementsFiles() {
+    const found = [];
+    const walk = (directory) => {
+        if (!fs.existsSync(directory))
+            return;
+        for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+            const full = path.join(directory, entry.name);
+            if (entry.isDirectory())
+                walk(full);
+            else if (entry.name.endsWith(".md")) {
+                let id;
+                try {
+                    const yaml = extractFrontmatterBlock(fs.readFileSync(full, "utf-8"));
+                    id = (yaml ? parse(yaml) : null)?.document?.id;
+                }
+                catch {
+                    console.warn(`Left ${full} alone: its frontmatter isn't YAML the command can read.`);
+                    continue;
+                }
+                found.push({
+                    file: full,
+                    ...(typeof id === "string" ? { documentId: id } : {}),
+                });
+            }
+        }
+    };
+    walk(".requirements");
+    return found;
+}
+/** A file as a push submits it: its text without frontmatter, and what the frontmatter says of its document. */
+function submitted(file) {
+    const content = fs.readFileSync(file, "utf-8");
+    const yaml = extractFrontmatterBlock(content);
+    const document = (yaml ? parse(yaml) : null)?.document;
+    return {
+        path: file,
+        markdownContent: stripFrontmatterBlock(content),
+        ...(typeof document?.id === "string" ? { documentId: document.id } : {}),
+        ...(typeof document?.defaultPrefix === "string"
+            ? { defaultPrefix: document.defaultPrefix }
+            : {}),
+    };
+}
+/** The app the share command renders mockups through. */
+function appUrl() {
+    return webApiUrl().replace(/\/+$/, "");
+}
+/**
+ * `dotreq solution checkout --share <token> --outcome "<name>"`
+ * (SOLSHARE-2): every document of the project into `.requirements/`, the
+ * solution's branch's versions where it has them, each at the file this
+ * repository already has for it or where the project's sync would put it;
+ * the solution's mockups as pages to open; the record push and done act
+ * on; and the outcome's prompt, printed for whoever or whatever reads the
+ * output.
+ */
+export async function shareCheckout(token, 
+/** The outcome handed over: one someone outside the product creates. */
+outcome, 
+/** SOLSHARE-2.10: the branch's version replaces an edit it has a newer version than. */
+branchWins = false) {
+    if (!outcome)
+        throw new Error('Say which outcome: --outcome "<name>", as the command you were given does.');
+    atRepositoryRoot();
+    const client = shareClient();
+    const got = await client.query(api.solutions.shares.forCheckout, {
+        token,
+        outcome,
+    });
+    // SOLSHARE-2.6, 2.10, 2.11: an edit that wasn't pushed is left as it is,
+    // unless the branch has saved a newer version of its document since the
+    // checkout: then the checkout stops, or with --branch-wins takes the
+    // branch's version.
+    const earlier = checkedOut().find((record) => record.solution.id === got.solution.id);
+    const unpushed = (earlier?.files ?? []).filter((file) => fs.existsSync(file.path) && hashOf(file.path) !== file.hash);
+    const current = new Map(got.files.map((file) => [file.documentId, file]));
+    const newer = (file) => {
+        const now = current.get(file.documentId);
+        return !!now?.onBranch && (!file.onBranch || now.version > file.version);
+    };
+    const conflicting = unpushed.filter(newer);
+    const kept = unpushed.filter((file) => !newer(file));
+    if (conflicting.length > 0 && !branchWins) {
+        throw new Error(`Nothing was written: the solution's branch has saved a newer version of ${conflicting.map((file) => file.path).join(", ")} since you checked ${conflicting.length === 1 ? "it" : "them"} out, and your changes to ${conflicting.length === 1 ? "it" : "them"} weren't pushed. Push them first with \`${SHARE_CLI} push --repo-wins\` to keep yours, or run this again with --branch-wins to take the branch's.`);
+    }
+    const keptIds = new Set(kept.map((file) => file.documentId));
+    // Each document goes where this repository already keeps it, when it does.
+    const here = new Map(requirementsFiles()
+        .filter((found) => found.documentId)
+        .map((found) => [found.documentId, found.file]));
+    const files = got.files.map((file) => ({
+        ...file,
+        path: here.get(file.documentId) ?? file.path,
+    }));
+    layOut(files.filter((file) => !keptIds.has(file.documentId)));
+    const mockupDirectory = path.join(SOLUTIONS, got.solution.directory, "mockups");
+    const rendered = [];
+    const failed = [];
+    for (const mockupId of got.mockups) {
+        const response = await fetch(`${appUrl()}/api/solutions/share/mockup`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ token, mockupId }),
+        }).catch(() => null);
+        if (!response?.ok) {
+            failed.push(mockupId);
+            continue;
+        }
+        fs.mkdirSync(mockupDirectory, { recursive: true });
+        fs.writeFileSync(path.join(mockupDirectory, `${mockupId}.html`), await response.text());
+        rendered.push(mockupId);
+    }
+    writeRecord({
+        token,
+        outcome: got.outcome,
+        round: got.round,
+        solution: got.solution,
+        // An edit left as it is keeps the version it was made from, so a push
+        // still sends it.
+        files: files.map((file) => kept.find((left) => left.documentId === file.documentId) ?? {
+            documentId: file.documentId,
+            path: file.path,
+            version: file.version,
+            onBranch: file.onBranch,
+            hash: hashOf(file.path),
+        }),
+    });
+    console.log(`Checked out ${got.solution.title}: ${files.length} ${files.length === 1 ? "document" : "documents"} under .requirements/${rendered.length ? `, and ${rendered.length} ${rendered.length === 1 ? "mockup" : "mockups"} under ${mockupDirectory}/` : ""}.`);
+    if (kept.length > 0) {
+        console.log(`Left your changes to ${kept.map((file) => file.path).join(", ")} as they are: the branch hasn't changed ${kept.length === 1 ? "that document" : "those documents"} since.`);
+    }
+    if (conflicting.length > 0) {
+        console.log(`Replaced your changes to ${conflicting.map((file) => file.path).join(", ")} with the branch's newer ${conflicting.length === 1 ? "version" : "versions"}.`);
+    }
+    if (failed.length > 0) {
+        console.log(`Couldn't render ${failed.length === 1 ? "mockup" : "mockups"} ${failed.join(", ")}: run the share command again to try again.`);
+    }
+    if (got.prompt) {
+        console.log(`\n${got.prompt}`);
+    }
+    else {
+        console.log(`\n"${got.outcome}" isn't waiting on anyone right now, so there's nothing to hand back yet.`);
+    }
+}
+/**
+ * `dotreq solution push`, in a repository a solution was checked out into
+ * (SOLSHARE-3): each document changed since the checkout, and each one
+ * added under `.requirements/`, to the solution's branch. False when no
+ * solution is checked out here, for the runner's push to take over.
+ */
+export async function sharePush(solution, 
+/** SOLSHARE-3.8: the repository's version wins over a newer one on the branch. */
+repoWins = false) {
+    atRepositoryRoot();
+    if (checkedOut().length === 0)
+        return false;
+    const record = oneCheckedOut(solution);
+    const changed = record.files
+        .filter((file) => fs.existsSync(file.path) && hashOf(file.path) !== file.hash)
+        .map((file) => file.path);
+    // A new document is a requirements file, or any Markdown in a solution's
+    // folder, that names no document yet; other notes under .requirements/
+    // stay where they are.
+    const added = requirementsFiles()
+        .filter((found) => !found.documentId &&
+        (found.file.endsWith(".requirements.md") ||
+            found.file.startsWith(`${SOLUTIONS}${path.sep}`)))
+        .map((found) => found.file);
+    const files = [...changed, ...added].map(submitted);
+    if (files.length === 0) {
+        console.log("Nothing to push: no document changed since the checkout.");
+        return true;
+    }
+    const saved = await shareClient().mutation(api.solutions.shares.push, {
+        token: record.token,
+        files,
+        base: record.files.map(({ documentId, version, onBranch }) => ({
+            documentId,
+            version,
+            onBranch,
+        })),
+        ...(repoWins ? { repoWins: true } : {}),
+    });
+    recordSavedIds(files, saved);
+    const byId = new Map(record.files.map((file) => [file.documentId, file]));
+    for (const entry of saved) {
+        byId.set(entry.documentId, {
+            documentId: entry.documentId,
+            path: entry.path,
+            version: entry.version,
+            onBranch: true,
+            hash: hashOf(entry.path),
+        });
+    }
+    writeRecord({ ...record, files: [...byId.values()] });
+    for (const entry of saved) {
+        console.log(`Saved ${entry.path} on the solution's branch as version ${entry.version}.${entry.replaced ? ` It replaced version ${entry.replaced.version}, saved ${new Date(entry.replaced.savedAt).toLocaleString()}, which the branch keeps.` : ""}`);
+    }
+    return true;
+}
+/**
+ * `dotreq solution done [<where it is>...] [--comment "..."]` (SOLSHARE-4):
+ * close the round of the outcome the repository was checked out for, with
+ * nothing to paste.
+ */
+export async function doneCommand(made, options) {
+    atRepositoryRoot();
+    const record = oneCheckedOut(options.solution);
+    if (record.round === null) {
+        throw new Error(`"${record.outcome}" wasn't waiting on anyone when it was checked out: run the share command again once it is.`);
+    }
+    const said = await shareClient().mutation(api.solutions.shares.done, {
+        token: record.token,
+        outcome: record.outcome,
+        round: record.round,
+        ...(made.length ? { made } : {}),
+        ...(options.comment?.trim() ? { comment: options.comment.trim() } : {}),
+    });
+    // STEP-REVIEW-18.7.0: nothing was recorded, and the message says why.
+    if (said.recorded === false)
+        throw new Error(said.message);
+    console.log(said.message);
+}
+//# sourceMappingURL=share.js.map

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

@@ -0,0 +1,14 @@
+import { type WhereOptions } from "./run-file.js";
+/**
+ * `dotreq solution stall "<what has to change>"`: the agent cannot go on
+ * with the outcome it is at, or the one `--outcome` names, and no decision
+ * would fix that. The reason is what has to change before it can be
+ * started again (VERB-3.2).
+ */
+export declare function stallCommand(reason: string, options: WhereOptions & {
+    /** False from the runner, which pushed already and says why it couldn't in the reason. */
+    push?: boolean;
+}): Promise<void>;
+/** A stall's reason, and that the work could not be pushed, and why (SOLBRANCH-3.4, 4.1). */
+export declare function withUnpushed(reason: string, why: string): string;
+//# sourceMappingURL=stall.d.ts.map

package/dist/commands/solution/stall.js

@@ -0,0 +1,41 @@
+import { api } from "../../convex.js";
+import { solutionClient } from "./client.js";
+import { pushWork } from "./pushing.js";
+import { onOutcome, requireWhere } from "./run-file.js";
+/**
+ * `dotreq solution stall "<what has to change>"`: the agent cannot go on
+ * with the outcome it is at, or the one `--outcome` names, and no decision
+ * would fix that. The reason is what has to change before it can be
+ * started again (VERB-3.2).
+ */
+export async function stallCommand(reason, options) {
+    if (!reason.trim()) {
+        throw new Error("Say what has to change before your work can be started again.");
+    }
+    const where = requireWhere(options);
+    const { solutionId, agent } = where;
+    const client = solutionClient();
+    // SOLBRANCH-3.4: a stall is recorded whether or not the work can be
+    // pushed; when it can't, the reason Quinn reads says so, and why.
+    let said = reason.trim();
+    if (where.branch && options.push !== false) {
+        const pushed = await pushWork(client, {
+            solutionId,
+            branch: where.branch,
+        });
+        if (!pushed.ok)
+            said = withUnpushed(said, pushed.why);
+    }
+    await client.mutation(api.solutions.mutations.stall, {
+        solutionId,
+        agent,
+        ...(where.outcome ? { outcome: where.outcome } : {}),
+        reason: said,
+    });
+    console.log(`Stalled${onOutcome(where.outcome)}. It can be started again once that is fixed.`);
+}
+/** A stall's reason, and that the work could not be pushed, and why (SOLBRANCH-3.4, 4.1). */
+export function withUnpushed(reason, why) {
+    return `${reason.replace(/\s+$/, "")}${/[.!?]$/.test(reason.trim()) ? "" : "."} The work could not be pushed: ${why.replace(/[.\s]+$/, "")}.`;
+}
+//# sourceMappingURL=stall.js.map

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

@@ -0,0 +1,11 @@
+/**
+ * `dotreq solution start <solution-id> <agent>`: begin an agent's work by
+ * hand. A stalled agent is started again, and it takes the part of an
+ * outcome's work it has due: the one `--outcome` names, or its first in the
+ * plan's order.
+ */
+export declare function startCommand(solutionId: string, agent: string, options: {
+    outcome?: string;
+    step?: string;
+}): Promise<void>;
+//# sourceMappingURL=start.d.ts.map

package/dist/commands/solution/start.js

@@ -0,0 +1,20 @@
+import { api } from "../../convex.js";
+import { solutionClient } from "./client.js";
+import { onOutcome } from "./run-file.js";
+/**
+ * `dotreq solution start <solution-id> <agent>`: begin an agent's work by
+ * hand. A stalled agent is started again, and it takes the part of an
+ * outcome's work it has due: the one `--outcome` names, or its first in the
+ * plan's order.
+ */
+export async function startCommand(solutionId, agent, options) {
+    const outcome = (options.outcome ?? options.step)?.trim() || undefined;
+    const client = solutionClient();
+    await client.mutation(api.solutions.mutations.start, {
+        solutionId,
+        agent,
+        ...(outcome ? { outcome } : {}),
+    });
+    console.log(`Started ${agent}${onOutcome(outcome)}.`);
+}
+//# sourceMappingURL=start.js.map

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

@@ -0,0 +1,39 @@
+import { type Panel, type PanelOutcome } from "./brief.js";
+import { solutionClient } from "./client.js";
+import { type WhereOptions } from "./run-file.js";
+/** What an agent is at: an outcome, and whether it drafts or reviews it there. */
+export type AgentAt = {
+    outcome: PanelOutcome;
+    part: "draft" | "review";
+};
+/**
+ * The outcome an agent is at, read off the plan panel: the one named, when
+ * `--outcome` names it; otherwise the one it is drafting, else one it
+ * reviews that stands reviewing, else one it stalled or asked on, else one
+ * ready for it to draft. Undefined when it is at none, as after it recorded
+ * its work; refused when it is at more than one and nothing says which.
+ */
+export declare function agentAt(panel: Pick<Panel, "phases">, agent: string, named?: string): AgentAt | undefined;
+/** The plan panel, or a refusal when the solution isn't there. */
+export declare function panelOf(client: ReturnType<typeof solutionClient>, solutionId: string): Promise<Panel>;
+/**
+ * The outcome a verb is about: the one named, else the one the agent is at
+ * on the panel. Refused, saying how to name it, when it is at none.
+ */
+export declare function outcomeFor(client: ReturnType<typeof solutionClient>, where: {
+    solutionId: string;
+    agent: string;
+    outcome?: string;
+}, what: string): Promise<string>;
+/**
+ * `dotreq solution status`: where the outcome the agent is at stands, as
+ * recorded — its one word, with the reason when stalled. With `--json`,
+ * also which outcome that is, whether the agent drafts or reviews it there,
+ * and whether it still owes its part: what the Stop hook and the runner's
+ * read-back judge an agent's session by (STEP-REVIEW-9). An agent at no
+ * outcome, as after it recorded its work, owes nothing.
+ */
+export declare function statusCommand(options: WhereOptions & {
+    json?: boolean;
+}): Promise<void>;
+//# sourceMappingURL=status.d.ts.map

package/dist/commands/solution/status.js

@@ -0,0 +1,145 @@
+import { api } from "../../convex.js";
+import { outcomesOf } from "./brief.js";
+import { solutionClient } from "./client.js";
+import { requireWhere } from "./run-file.js";
+const drafts = (outcome, agent) => outcome.drafter === agent;
+const reviews = (outcome, agent) => (outcome.reviewers ?? []).includes(agent);
+/**
+ * The outcome an agent is at, read off the plan panel: the one named, when
+ * `--outcome` names it; otherwise the one it is drafting, else one it
+ * reviews that stands reviewing, else one it stalled or asked on, else one
+ * ready for it to draft. Undefined when it is at none, as after it recorded
+ * its work; refused when it is at more than one and nothing says which.
+ */
+export function agentAt(panel, agent, named) {
+    const outcomes = outcomesOf(panel);
+    if (named) {
+        const outcome = outcomes.find((each) => each.name === named);
+        if (!outcome) {
+            throw new Error(`The plan has no outcome called "${named}". Its outcomes: ${outcomes.map((each) => each.name).join(", ")}.`);
+        }
+        const drafting = drafts(outcome, agent);
+        const reviewing = reviews(outcome, agent);
+        if (!drafting && !reviewing) {
+            throw new Error(`${agent} neither drafts nor reviews "${named}".`);
+        }
+        return {
+            outcome,
+            part: reviewing && (!drafting || outcome.status === "reviewing")
+                ? "review"
+                : "draft",
+        };
+    }
+    const tiers = [
+        (outcome) => drafts(outcome, agent) && outcome.status === "drafting"
+            ? { outcome, part: "draft" }
+            : undefined,
+        (outcome) => reviews(outcome, agent) && outcome.status === "reviewing"
+            ? { outcome, part: "review" }
+            : undefined,
+        (outcome) => outcome.status === "stalled" || outcome.status === "awaiting decision"
+            ? drafts(outcome, agent)
+                ? { outcome, part: "draft" }
+                : reviews(outcome, agent)
+                    ? { outcome, part: "review" }
+                    : undefined
+            : undefined,
+        (outcome) => drafts(outcome, agent) && outcome.status === "ready"
+            ? { outcome, part: "draft" }
+            : undefined,
+    ];
+    for (const tier of tiers) {
+        const found = outcomes.flatMap((outcome) => {
+            const at = tier(outcome);
+            return at ? [at] : [];
+        });
+        if (found.length === 1)
+            return found[0];
+        if (found.length > 1) {
+            throw new Error(`${agent} is at more than one outcome: ${found.map((at) => `"${at.outcome.name}"`).join(", ")}. Name one with --outcome "<name>".`);
+        }
+    }
+    return undefined;
+}
+/** The plan panel, or a refusal when the solution isn't there. */
+export async function panelOf(client, solutionId) {
+    const panel = await client.query(api.solutions.queries.getPlan, {
+        solutionId,
+    });
+    if (!panel)
+        throw new Error("Solution not found.");
+    return panel;
+}
+/**
+ * The outcome a verb is about: the one named, else the one the agent is at
+ * on the panel. Refused, saying how to name it, when it is at none.
+ */
+export async function outcomeFor(client, where, what) {
+    if (where.outcome)
+        return where.outcome;
+    const at = agentAt(await panelOf(client, where.solutionId), where.agent);
+    if (!at) {
+        throw new Error(`${where.agent} is at no outcome now, so nothing says which ${what}. Name it with --outcome "<name>".`);
+    }
+    return at.outcome.name;
+}
+/**
+ * Whether a reviewer still owes its result on an outcome standing
+ * reviewing: an outcome with several reviewers stands reviewing until the
+ * last gives its result, so one that gave its own since the latest
+ * submission owes nothing more.
+ */
+async function reviewerOwes(client, solutionId, outcome, agent) {
+    const thread = (await client.query(api.solutions.queries.getThread, {
+        solutionId,
+        outcome,
+    })) ?? [];
+    let since = 0;
+    thread.forEach((entry, at) => {
+        if (entry.kind === "submission")
+            since = at + 1;
+    });
+    return !thread
+        .slice(since)
+        .some((entry) => entry.agent === agent &&
+        (entry.kind === "review" || entry.kind === "escalation"));
+}
+/**
+ * `dotreq solution status`: where the outcome the agent is at stands, as
+ * recorded — its one word, with the reason when stalled. With `--json`,
+ * also which outcome that is, whether the agent drafts or reviews it there,
+ * and whether it still owes its part: what the Stop hook and the runner's
+ * read-back judge an agent's session by (STEP-REVIEW-9). An agent at no
+ * outcome, as after it recorded its work, owes nothing.
+ */
+export async function statusCommand(options) {
+    const where = requireWhere(options);
+    const client = solutionClient();
+    const panel = await panelOf(client, where.solutionId);
+    const at = agentAt(panel, where.agent, where.outcome);
+    if (!at) {
+        if (options.json) {
+            process.stdout.write(`${JSON.stringify({ agent: where.agent, outcome: null, part: null, status: null, reason: null, reviews: false, owes: false })}\n`);
+            return;
+        }
+        process.stdout.write(`${where.agent} is at no outcome now.\n`);
+        return;
+    }
+    const { outcome, part } = at;
+    // CHECKPOINT-6.3.2.3: a drafter whose work was set aside owes nothing
+    // more there; the new draft is another session's.
+    const setAside = part === "draft" && outcome.setAside === true;
+    const owes = part === "draft"
+        ? !setAside &&
+            (outcome.status === "drafting" || outcome.status === "ready")
+        : outcome.status === "reviewing" &&
+            (await reviewerOwes(client, where.solutionId, outcome.name, where.agent));
+    if (options.json) {
+        process.stdout.write(`${JSON.stringify({ agent: where.agent, outcome: outcome.name, part, status: outcome.status, reason: outcome.reason ?? null, reviews: part === "review", ...(setAside ? { setAside } : {}), owes })}\n`);
+        return;
+    }
+    process.stdout.write(outcome.reason
+        ? `${outcome.name}: ${outcome.status} — ${outcome.reason}\n`
+        : `${outcome.name}: ${outcome.status}\n`);
+}
+//# sourceMappingURL=status.js.map

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

@@ -0,0 +1,13 @@
+/**
+ * The executive summary a verb carries (STEP-REVIEW-20): for the owner,
+ * what the work is and what most needs their eye, where the comment is for
+ * the thread. `--executive-summary` is its name; `--summary` is short for
+ * it, for a person typing it by hand (VERB-1.6, 2.5).
+ */
+export type SummaryOptions = {
+    executiveSummary?: string;
+    summary?: string;
+};
+/** The summary given, by either name; undefined when none, or only blanks. */
+export declare function summaryGiven(options: SummaryOptions): string | undefined;
+//# sourceMappingURL=summary.d.ts.map

package/dist/commands/solution/summary.js

@@ -0,0 +1,5 @@
+/** The summary given, by either name; undefined when none, or only blanks. */
+export function summaryGiven(options) {
+    return (options.executiveSummary?.trim() || options.summary?.trim() || undefined);
+}
+//# sourceMappingURL=summary.js.map