@popoverai/dotrequirements 0.34.2 → 0.36.0

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

@@ -0,0 +1,9 @@
+import { type WhereOptions } from "./run-file.js";
+/**
+ * `dotreq solution approval complete <decision>`: the agent takes the
+ * action on the option the owner chose, exactly as the option carried it,
+ * once, and prints what came of it (DECIDE-4.1). Refused, saying why, when
+ * she hasn't chosen it, it was taken already, or another agent asked.
+ */
+export declare function approvalCompleteCommand(decisionId: string, options: WhereOptions): Promise<void>;
+//# sourceMappingURL=approval.d.ts.map

package/dist/commands/solution/approval.js

@@ -0,0 +1,19 @@
+import { api } from "../../convex.js";
+import { solutionClient } from "./client.js";
+import { requireWhere } from "./run-file.js";
+/**
+ * `dotreq solution approval complete <decision>`: the agent takes the
+ * action on the option the owner chose, exactly as the option carried it,
+ * once, and prints what came of it (DECIDE-4.1). Refused, saying why, when
+ * she hasn't chosen it, it was taken already, or another agent asked.
+ */
+export async function approvalCompleteCommand(decisionId, options) {
+    const { solutionId, agent } = requireWhere(options);
+    const result = (await solutionClient().mutation(api.solutions.mutations.completeApproval, { solutionId, agent, decisionId }));
+    // DECIDE-4.7: refused because the work moved on, kept so the brief stops
+    // offering it, and said as any refusal is.
+    if ("refused" in result)
+        throw new Error(result.refused);
+    console.log(result.said);
+}
+//# sourceMappingURL=approval.js.map

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

@@ -1,9 +1,14 @@
 import { type WhereOptions } from "./run-file.js";
+export type AskOptions = WhereOptions & {
+    /** One action as JSON, `{"tool": ..., "args": ...}`, to ask only whether it may be taken (DECIDE-3.4). */
+    approvalRequest?: string;
+};
 /**
- * `dotreq solution ask <request-file>`: the drafter puts a decision to the
- * owner, on the outcome it is drafting or the one `--outcome` names. A
- * reviewer escalates instead (`dotreq solution review escalate`), and the
- * backend refuses its question (VERB-3.5).
+ * `dotreq solution ask <request-file>`: the drafter or a reviewer puts a
+ * decision to the owner, on the outcome it is at or the one `--outcome`
+ * names (VERB-3.0). A reviewer gives its result once she has answered (3.1).
+ * `--approval-request '<action>'`, with no file, asks only whether it may
+ * take that one action (DECIDE-3.4).
  */
-export declare function askCommand(file: string, options: WhereOptions): Promise<void>;
+export declare function askCommand(file: string | undefined, options: AskOptions): Promise<void>;
 //# sourceMappingURL=ask.d.ts.map

package/dist/commands/solution/ask.js

@@ -4,24 +4,39 @@ import { pushBeforeRecord } from "./pushing.js";
 import { readRequest } from "./request.js";
 import { onOutcome, requireWhere } from "./run-file.js";
 /**
- * `dotreq solution ask <request-file>`: the drafter puts a decision to the
- * owner, on the outcome it is drafting or the one `--outcome` names. A
- * reviewer escalates instead (`dotreq solution review escalate`), and the
- * backend refuses its question (VERB-3.5).
+ * `dotreq solution ask <request-file>`: the drafter or a reviewer puts a
+ * decision to the owner, on the outcome it is at or the one `--outcome`
+ * names (VERB-3.0). A reviewer gives its result once she has answered (3.1).
+ * `--approval-request '<action>'`, with no file, asks only whether it may
+ * take that one action (DECIDE-3.4).
  */
 export async function askCommand(file, options) {
-    const request = readRequest(file);
+    if ((file === undefined) === (options.approvalRequest === undefined)) {
+        throw new Error("Ask with a request file, or with --approval-request '<action>' alone: one of them.");
+    }
+    const asking = file !== undefined
+        ? { request: readRequest(file) }
+        : { approvalRequest: actionFrom(options.approvalRequest ?? "") };
     const where = requireWhere(options);
     const { solutionId, agent } = where;
     const client = solutionClient();
     // SOLBRANCH-3.0: the drafter's commits reach the branch before Quinn is asked.
     await pushBeforeRecord(client, where);
-    await client.mutation(api.solutions.mutations.ask, {
+    const decision = await client.mutation(api.solutions.mutations.ask, {
         solutionId,
         agent,
         ...(where.outcome ? { outcome: where.outcome } : {}),
-        request,
+        ...asking,
     });
-    console.log(`Asked${onOutcome(where.outcome)}. It waits on the owner's decision.`);
+    console.log(`Asked${onOutcome(where.outcome)}. It waits on the owner's decision${decision ? ` (${decision})` : ""}.`);
+}
+/** The action `--approval-request` names, as JSON. The backend checks it. */
+function actionFrom(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        throw new Error(`--approval-request takes the action as JSON, {"tool": ..., "args": ...}: ${error instanceof Error ? error.message : String(error)}`);
+    }
 }
 //# sourceMappingURL=ask.js.map

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

@@ -54,6 +54,8 @@ export type PanelOutcome = {
         agent: string;
         part: "draft" | "review";
     }>;
+    /** The reviewers waiting on its pull request, their sessions ended (PULL-5). */
+    waiting?: string[];
 };
 /** A checkpoint on the plan panel, as far as the CLI reads it. */
 export type PanelCheckpoint = {

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

@@ -5,5 +5,5 @@
  * request is validated against; the CLI can't import the backend, so this
  * is that text, and a test keeps the two the same.
  */
-export declare const REQUEST_CONTRACT = "Ask the person to decide something about the outcome you are drafting. A choice presents options with a recommendation. One decision per request: if two things need deciding, ask twice.\n\nA request is JSON with a \"kind\" and the fields of that kind:\n\nchoice:\n  question (text, up to 200 characters): The question, phrased as a question in the words the person will read it, not as a topic.\n  options (list, at least 2): The live alternatives. More than four makes deciding harder; give more only when each is a genuine choice. Leave out anything you have already ruled out.\n    name (text, up to 200 characters): The option as you would say it to the person: a noun phrase they can repeat back, not a label.\n    benefits (list of text, each up to 200 characters): What is better if this option is taken. One line each, in your own words.\n    costs (list of text, each up to 200 characters): What is worse if this option is taken: what it would take to build, and what the person lives with afterwards. Effort is a cost like any other.\n    note (text, up to 600 characters, optional): Anything you learned or checked about this option that is not a benefit or a cost. Leave it out when there is nothing to add.\n  recommendation (object): Which option you would take, and the one reason why.\n    option (text, up to 200 characters): The name of the option you recommend, exactly as it appears in options.\n    because (text, up to 200 characters): The one reason that carries it, in one line. The full reasoning belongs in background.\n  background (text, up to 4000 characters): What the person needs to know to decide well that the options do not already say. Include only context that would substantially change the quality of the decision. The person reads this after the options, so do not reiterate them.";
+export declare const REQUEST_CONTRACT = "Ask the person to decide something about the outcome you are drafting or reviewing. A choice presents options with a recommendation. One decision per request: if two things need deciding, ask twice.\n\nA request is JSON with a \"kind\" and the fields of that kind:\n\nchoice:\n  question (text, up to 200 characters): The question, phrased as a question in the words the person will read it, not as a topic.\n  options (list, at least 2): The live alternatives. More than four makes deciding harder; give more only when each is a genuine choice. Leave out anything you have already ruled out.\n    name (text, up to 200 characters): The option as you would say it to the person: a noun phrase they can repeat back, not a label.\n    benefits (list of text, each up to 200 characters): What is better if this option is taken. One line each, in your own words.\n    costs (list of text, each up to 200 characters): What is worse if this option is taken: what it would take to build, and what the person lives with afterwards. Effort is a cost like any other.\n    note (text, up to 600 characters, optional): Anything you learned or checked about this option that is not a benefit or a cost. Leave it out when there is nothing to add.\n    action (object, optional): An action you may take only with the person's permission, which choosing this option gives. Once they choose it, take it with `dotreq solution approval complete <decision>`. Leave it out for anything you may do yourself.\n      tool (text, up to 200 characters): The action, by name. The one that needs the person's permission is \"fix\", starting a fix.\n      args (object): The action's arguments, as it takes them: a fix's are below.\n  recommendation (object): Which option you would take, and the one reason why.\n    option (text, up to 200 characters): The name of the option you recommend, exactly as it appears in options.\n    because (text, up to 200 characters): The one reason that carries it, in one line. The full reasoning belongs in background.\n  background (text, up to 4000 characters): What the person needs to know to decide well that the options do not already say. Include only context that would substantially change the quality of the decision. The person reads this after the options, so do not reiterate them.\n\nThe args of a \"fix\" action:\n  name (text, up to 120 characters): A short name for the fix, from what it puts right, as \"dice below the controls\".\n  words (text, up to 2000 characters): What you found, in your own words.\n  plan (text, up to 2000 characters): The fix as you would put it to the person, in a sentence or two.\n  redo (list, at least 1): The outcomes the fix redoes, and what would change in each.\n    outcome (text, up to 200 characters): An outcome to redo, by its name.\n    change (text, up to 2000 characters): What would change in it.\n  rerun (list of text, each up to 200 characters): The outcomes that await the ones redone and should run again from them. Empty when none should.";
 //# sourceMappingURL=contract.d.ts.map

package/dist/commands/solution/contract.js

@@ -5,7 +5,7 @@
  * request is validated against; the CLI can't import the backend, so this
  * is that text, and a test keeps the two the same.
  */
-export const REQUEST_CONTRACT = `Ask the person to decide something about the outcome you are drafting. A choice presents options with a recommendation. One decision per request: if two things need deciding, ask twice.
+export const REQUEST_CONTRACT = `Ask the person to decide something about the outcome you are drafting or reviewing. A choice presents options with a recommendation. One decision per request: if two things need deciding, ask twice.
 
 A request is JSON with a "kind" and the fields of that kind:
 
@@ -16,8 +16,20 @@ choice:
     benefits (list of text, each up to 200 characters): What is better if this option is taken. One line each, in your own words.
     costs (list of text, each up to 200 characters): What is worse if this option is taken: what it would take to build, and what the person lives with afterwards. Effort is a cost like any other.
     note (text, up to 600 characters, optional): Anything you learned or checked about this option that is not a benefit or a cost. Leave it out when there is nothing to add.
+    action (object, optional): An action you may take only with the person's permission, which choosing this option gives. Once they choose it, take it with \`dotreq solution approval complete <decision>\`. Leave it out for anything you may do yourself.
+      tool (text, up to 200 characters): The action, by name. The one that needs the person's permission is "fix", starting a fix.
+      args (object): The action's arguments, as it takes them: a fix's are below.
   recommendation (object): Which option you would take, and the one reason why.
     option (text, up to 200 characters): The name of the option you recommend, exactly as it appears in options.
     because (text, up to 200 characters): The one reason that carries it, in one line. The full reasoning belongs in background.
-  background (text, up to 4000 characters): What the person needs to know to decide well that the options do not already say. Include only context that would substantially change the quality of the decision. The person reads this after the options, so do not reiterate them.`;
+  background (text, up to 4000 characters): What the person needs to know to decide well that the options do not already say. Include only context that would substantially change the quality of the decision. The person reads this after the options, so do not reiterate them.
+
+The args of a "fix" action:
+  name (text, up to 120 characters): A short name for the fix, from what it puts right, as "dice below the controls".
+  words (text, up to 2000 characters): What you found, in your own words.
+  plan (text, up to 2000 characters): The fix as you would put it to the person, in a sentence or two.
+  redo (list, at least 1): The outcomes the fix redoes, and what would change in each.
+    outcome (text, up to 200 characters): An outcome to redo, by its name.
+    change (text, up to 2000 characters): What would change in it.
+  rerun (list of text, each up to 200 characters): The outcomes that await the ones redone and should run again from them. Empty when none should.`;
 //# sourceMappingURL=contract.js.map

package/dist/commands/solution/index.js

@@ -1,4 +1,5 @@
 import { Option } from "commander";
+import { approvalCompleteCommand } from "./approval.js";
 import { askCommand } from "./ask.js";
 import { authorCommand } from "./author.js";
 import { checkoutCommand, pushCommand } from "./checkout.js";
@@ -6,7 +7,7 @@ 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 { prStatusCommand, prWaitCommand, pullRequestCommand, } from "./pull-request.js";
 import { rehearseCommand } from "./rehearse.js";
 import { reviewCommand } from "./review.js";
 import { doneCommand } from "./share.js";
@@ -41,7 +42,7 @@ Where what you made is, one or more:
   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
+                           dotreq solution pr open. 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
@@ -91,11 +92,27 @@ Examples:
   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). */
+/** What `pr status` says, on its `--help` (PULL-4). */
+const PR_STATUS_HELP = `
+Reads the pull request of the outcome you are at, or of the outcome it awaits that
+is kept on one, as GitHub reports it. The merge state is GitHub's word for whether
+it can merge: clean means it can, with every required check passing and no
+conflict. Failed checks come with a link to them; checks still running are named.
+Reading it changes nothing.
+`;
+/** What `pr wait` does, on its `--help` (PULL-5, PULL-6). */
+const PR_WAIT_HELP = `
+For a reviewer, when the pull request has to change before you can give a result,
+as while its checks run. Records where it stands now; then end your session
+without a result. You are started again, in this session, when GitHub reports it
+changed and nothing on it is still running, or once it is merged or closed. A new
+submission ends the wait too, and you review that as you would any other.
+`;
+/** What `pr open` 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:
+into the branch it was made from, as a draft, or finds the one already open. The
+plan says when it becomes ready for review. Prints its reference and its address:
 
   The solution's pull request is pr:12: https://github.com/<owner>/<repository>/pull/12
 
@@ -123,8 +140,15 @@ The outcome waits until that is fixed and you are started again.
 const ASK_EXAMPLES = `
 Examples:
   dotreq solution ask question.json
+  dotreq solution ask --approval-request '{"tool": "fix", "args": {"name": "Receipt email required", "words": "...", "plan": "...", "redo": [{"outcome": "Code", "change": "..."}], "rerun": []}}'
+
+A reviewer asks the same way, then gives its result once the owner has answered: it is
+sent for again then.
 
-A reviewer doesn't ask: it escalates, with dotreq solution review escalate --comment "...".
+An option may carry an action you may take only with the owner's permission: starting a
+fix, as "fix". Choosing that option gives it; nothing is done until you take it, with
+dotreq solution approval complete <decision>. --approval-request asks only whether you may
+take one action.
 `;
 /**
  * What each result does, on `review --help` (STEP-REVIEW-1, 2), and the
@@ -135,8 +159,10 @@ 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.
+  needs-revision           The drafter revises and you read it again. From the twelfth round, give it only once the owner has chosen it.
+
+When whether to approve turns on the owner's own judgement, put a decision to them first
+with dotreq solution ask, and give your result once they have answered.
 
 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
@@ -157,7 +183,6 @@ 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."
 `;
@@ -216,15 +241,29 @@ export function registerSolution(program) {
         .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)
+    const pr = solution
+        .command("pr", HIDDEN)
+        .description("The solution's pull request: open it, read it, wait on it");
+    whereOptions(pr
+        .command("open")
         .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(pr
+        .command("status")
+        .description("Where the pull request of the outcome you are at stands, in GitHub's words: its merge state, conflicts, review decision and checks"))
+        .option("--json", "Print as JSON")
+        .addHelpText("after", PR_STATUS_HELP)
+        .action(wrap(prStatusCommand));
+    whereOptions(pr
+        .command("wait")
+        .description("Wait on the pull request with your session ended: you start again when it changes and nothing on it is still running"))
+        .addHelpText("after", PR_WAIT_HELP)
+        .action(wrap(prWaitCommand));
     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")
+        .description("Record the review's result: approved, approved-with-revisions or needs-revision"))
+        .option("--comment <text>", "What should change, or what you checked: 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)
@@ -235,14 +274,24 @@ export function registerSolution(program) {
         .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"))
+        .command("ask [request-file]", HIDDEN)
+        .description("Put a decision to the owner, as JSON in the named file, drafting or reviewing"))
+        .option("--approval-request <action>", 'Ask only whether you may take one action, given as JSON: {"tool": "fix", "args": {...}}. No request file then')
         .addHelpText("after", `\n${REQUEST_CONTRACT}\n${ASK_EXAMPLES}`)
         .action(wrap(askCommand));
+    const approval = solution
+        .command("approval", HIDDEN)
+        .description("An action the owner allowed by choosing the option that carries it");
+    approval
+        .command("complete <decision>")
+        .description("Take the action on the option the owner chose, exactly as offered, once, and print what came of it")
+        .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)")
+        .action(wrap(approvalCompleteCommand));
     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")
+        .option("--latest [n]", "Only the newest n submission notes, review results 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)

package/dist/commands/solution/pull-request.d.ts

@@ -5,9 +5,50 @@ export type PullRequest = {
     number: number;
 };
 /** The command that opens the solution's pull request and prints its reference. */
-export declare const OPEN_IT = "dotreq solution pull-request";
+export declare const OPEN_IT = "dotreq solution pr open";
+/** Where a pull request stands, in GitHub's words (web: lib/runner/github.ts). */
+export type PullRequestState = {
+    number: number;
+    url: string;
+    mergeState: string;
+    mergeable: string;
+    reviewDecision: string | null;
+    checks: string | null;
+    failed: Array<{
+        name: string;
+        result: string;
+        link: string | null;
+    }>;
+    running: Array<{
+        name: string;
+        link: string | null;
+    }>;
+    head: string;
+};
+/**
+ * Where the pull request stood, as a wait records it (PULL-6.4): what a
+ * reviewer judges by, so a later read that differs is a change.
+ */
+export declare function seenOf(state: PullRequestState): string;
+/** Where the pull request stands, as a reviewer reads it (PULL-4). */
+export declare function describeState(state: PullRequestState): string;
+/**
+ * `dotreq solution pr status`: where the pull request of the outcome the
+ * agent is at stands, in GitHub's words (PULL-4). Changes nothing (4.6).
+ */
+export declare function prStatusCommand(options: WhereOptions & {
+    json?: boolean;
+}): Promise<void>;
+/**
+ * `dotreq solution pr wait`: the reviewer waits on the pull request with
+ * no session running (PULL-5): it records where the pull request stands,
+ * and its session can end without a result. It starts again, in the same
+ * session, when the pull request changes and nothing on it is still running
+ * (PULL-6).
+ */
+export declare function prWaitCommand(options: WhereOptions): Promise<void>;
 /**
- * `dotreq solution pull-request`: the solution's pull request, opened or
+ * `dotreq solution pr open`: the solution's pull request, opened or
  * found (PULL-2). Inside a runner the branch is pushed first, as a submission
  * pushes it (2.0, SOLBRANCH-3); then the app opens a pull request from it
  * into the branch it was made from, or finds the one already open (2.3,

package/dist/commands/solution/pull-request.js

@@ -1,13 +1,101 @@
 import { webApiUrl } from "../../cloud.js";
+import { api } from "../../convex.js";
 import { getProjectCredentials } from "../../utils/project-settings.js";
 import { solutionClient } from "./client.js";
 import { pushWork } from "./pushing.js";
 import { requireWhere } from "./run-file.js";
 import { outcomeFor } from "./status.js";
 /** The command that opens the solution's pull request and prints its reference. */
-export const OPEN_IT = "dotreq solution pull-request";
+export const OPEN_IT = "dotreq solution pr open";
 /**
- * `dotreq solution pull-request`: the solution's pull request, opened or
+ * Where the pull request stood, as a wait records it (PULL-6.4): what a
+ * reviewer judges by, so a later read that differs is a change.
+ */
+export function seenOf(state) {
+    return [
+        state.head,
+        state.mergeState,
+        state.mergeable,
+        state.reviewDecision ?? "",
+        state.checks ?? "",
+    ].join(" ");
+}
+/** The pull request the outcome the agent is at reads, as the app finds it (PULL-4.0, 4.0.0). */
+async function stateFor(where) {
+    const said = await ask({
+        solutionId: where.solutionId,
+        agent: where.agent,
+        ...(where.outcome ? { outcome: where.outcome } : {}),
+        op: "status",
+    });
+    if (said.noRepository) {
+        // PULL-4.5.
+        throw new Error("There's no pull request: a pull request needs a repository, and this project has none connected.");
+    }
+    if (said.noBranch || said.none) {
+        // PULL-4.4.
+        throw new Error(`There's no pull request open for it. Its drafter opens one with \`${OPEN_IT}\`.`);
+    }
+    if (said.refused) {
+        throw new Error(`Couldn't read the pull request from the repository: ${said.refused}`);
+    }
+    if (!said.state)
+        throw new Error("The app gave no pull request.");
+    return said.state;
+}
+/** Where the pull request stands, as a reviewer reads it (PULL-4). */
+export function describeState(state) {
+    const lines = [
+        `pr:${state.number} (${state.url}), at ${state.head.slice(0, 7)}`,
+        `Merge state: ${state.mergeState}`,
+        `Conflicts with the branch it merges into: ${state.mergeable === "conflicting" ? "yes" : state.mergeable === "mergeable" ? "no" : "not worked out yet"}`,
+        `Review decision: ${state.reviewDecision ?? "none required"}`,
+        `Checks: ${state.checks ?? "none"}`,
+    ];
+    for (const check of state.failed) {
+        lines.push(`  failed: ${check.name} (${check.result})${check.link ? ` ${check.link}` : ""}`);
+    }
+    for (const check of state.running) {
+        lines.push(`  still running: ${check.name}${check.link ? ` ${check.link}` : ""}`);
+    }
+    if (state.mergeable === "unknown") {
+        // PULL-4.3.
+        lines.push("GitHub hasn't yet worked out whether it can merge: read it again shortly, or wait on it.");
+    }
+    return lines.join("\n");
+}
+/**
+ * `dotreq solution pr status`: where the pull request of the outcome the
+ * agent is at stands, in GitHub's words (PULL-4). Changes nothing (4.6).
+ */
+export async function prStatusCommand(options) {
+    const state = await stateFor(requireWhere(options));
+    console.log(options.json ? JSON.stringify(state) : describeState(state));
+}
+/**
+ * `dotreq solution pr wait`: the reviewer waits on the pull request with
+ * no session running (PULL-5): it records where the pull request stands,
+ * and its session can end without a result. It starts again, in the same
+ * session, when the pull request changes and nothing on it is still running
+ * (PULL-6).
+ */
+export async function prWaitCommand(options) {
+    const where = requireWhere(options);
+    const state = await stateFor(where);
+    await solutionClient().mutation(api.solutions.waits.waitOnPullRequest, {
+        solutionId: where.solutionId,
+        agent: where.agent,
+        ...(where.outcome ? { outcome: where.outcome } : {}),
+        seen: seenOf(state),
+    });
+    console.log([
+        describeState(state),
+        "",
+        "Waiting on it. End your session now: you'll be started again, here, when it changes and nothing on it is still running.",
+    ].join("\n"));
+}
+/**
+ * `dotreq solution pr open`: the solution's pull request, opened or
  * found (PULL-2). Inside a runner the branch is pushed first, as a submission
  * pushes it (2.0, SOLBRANCH-3); then the app opens a pull request from it
  * into the branch it was made from, or finds the one already open (2.3,
@@ -98,7 +186,8 @@ function pullRequestIn(said) {
 /**
  * Ask the app's pull-request route, on the project's credentials: with the
  * outcome, to open the pull request it is kept on; with a number, to check
- * that one is the solution's open pull request, which needs no outcome.
+ * that one is the solution's open pull request, which needs no outcome;
+ * with `op: "status"`, for where the open one stands.
  */
 async function ask(body) {
     const { projectId, projectSecret } = getProjectCredentials();

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

@@ -1,7 +1,7 @@
 import { type WhereOptions } from "./run-file.js";
 import { type SummaryOptions } from "./summary.js";
 export type ReviewOptions = WhereOptions & SummaryOptions & {
-    /** What should change, what was checked, or what the owner is to decide: required for every result (VERB-2.0, 2.1, 2.4). */
+    /** What should change, or what was checked: required for every result (VERB-2.0, 2.1). */
     comment?: string;
     /**
      * With an approval of a demo's script: the video recorded from it and
@@ -14,9 +14,10 @@ export type ReviewOptions = WhereOptions & SummaryOptions & {
  * `dotreq solution review <result> --comment "..."`: the reviewer's
  * result on the outcome it is reviewing, or on the one `--outcome` names.
  * The comment is what the next reader of the thread sees first — the
- * drafter works from it, and on an escalation it is the note the owner
- * reads — so every result is refused without one before anything is
- * recorded (VERB-2.0, 2.1, 2.4). An approval also carries an executive
+ * drafter works from it — so every result is refused without one before
+ * anything is recorded (VERB-2.0, 2.1). When the reviewer needs the
+ * owner's judgement it asks first (`dotreq solution ask`), and gives its
+ * result once she has answered; escalate is refused, saying so (2.4). An approval also carries an executive
  * summary, `--executive-summary "..."`, which is what the owner reads with
  * the work (VERB-2.5); the outcome's own rules decide what follows. An
  * approval of a demo's script carries the video the reviewer recorded from

package/dist/commands/solution/review.js

@@ -10,15 +10,17 @@ const RESULTS = {
     approved: "approved",
     "approved-with-revisions": "approved with revisions",
     "needs-revision": "needs revision",
-    escalate: "escalate",
 };
+/** What a reviewer is told when it gives escalate, which is no longer a result (VERB-2.4): in the backend's words. */
+const NO_ESCALATING = "Nothing was recorded: escalate is no longer a result. When you need the owner's judgement, put a decision to them with `dotreq solution ask` (`dotreq solution ask --help` shows the form), and give your result once they have answered.";
 /**
  * `dotreq solution review <result> --comment "..."`: the reviewer's
  * result on the outcome it is reviewing, or on the one `--outcome` names.
  * The comment is what the next reader of the thread sees first — the
- * drafter works from it, and on an escalation it is the note the owner
- * reads — so every result is refused without one before anything is
- * recorded (VERB-2.0, 2.1, 2.4). An approval also carries an executive
+ * drafter works from it — so every result is refused without one before
+ * anything is recorded (VERB-2.0, 2.1). When the reviewer needs the
+ * owner's judgement it asks first (`dotreq solution ask`), and gives its
+ * result once she has answered; escalate is refused, saying so (2.4). An approval also carries an executive
  * summary, `--executive-summary "..."`, which is what the owner reads with
  * the work (VERB-2.5); the outcome's own rules decide what follows. An
  * approval of a demo's script carries the video the reviewer recorded from
@@ -26,17 +28,17 @@ const RESULTS = {
  * (SIGHT-13.2); no other result carries one (13.4.0).
  */
 export async function reviewCommand(result, options) {
+    if (result === "escalate")
+        throw new Error(NO_ESCALATING);
     const outcome = RESULTS[result];
     if (!outcome) {
-        throw new Error(`A review result is approved, approved-with-revisions, needs-revision or escalate, not "${result}".`);
+        throw new Error(`A review result is approved, approved-with-revisions or needs-revision, not "${result}".`);
     }
     const comment = options.comment?.trim();
     if (!comment) {
         throw new Error(outcome === "approved"
             ? "Say what you checked: your comment is what the next reader sees first."
-            : outcome === "escalate"
-                ? "Say what the owner is to decide: your comment is the note they read with the work."
-                : "Say what should change: the drafter works from your comment.");
+            : "Say what should change: the drafter works from your comment.");
     }
     // VERB-2.5, 2.5.0: an approval carries an executive summary for the
     // owner, and nothing else does; refused before anything is recorded, in
@@ -47,7 +49,7 @@ export async function reviewCommand(result, options) {
         throw new Error("Write an executive summary for the owner with --executive-summary: it's what they read first. Say what this is and what most needs their eye, as the work will stand once any fixes you asked for are made.");
     }
     if (!approving && summary) {
-        throw new Error(`Only an approval carries an executive summary, so nothing was recorded. Leave --executive-summary off: ${outcome === "escalate" ? "your comment is the note the owner reads." : "the drafter works from your comment."}`);
+        throw new Error("Only an approval carries an executive summary, so nothing was recorded. Leave --executive-summary off: the drafter works from your comment.");
     }
     // SIGHT-13.2, 13.4.0: a video goes only with a plain approval, and is
     // read before anything is pushed, uploaded or recorded.
@@ -55,7 +57,7 @@ export async function reviewCommand(result, options) {
     if (recordings.length > 0 && outcome !== "approved") {
         throw new Error(outcome === "approved with revisions"
             ? "Nothing was recorded: a demo's script isn't approved with revisions, because its drafter can't change the script without the video going out of step. Fix anything small yourself, record the video, and approve with it, saying in your comment what you changed; or give needs-revision."
-            : `Nothing was recorded: only an approval carries a video. Give your result without it: ${outcome === "escalate" ? "your comment is the note the owner reads" : "the drafter works from your comment"}, and no video is kept.`);
+            : "Nothing was recorded: only an approval carries a video. Give your result without it: the drafter works from your comment, and no video is kept.");
     }
     const where = requireWhere(options);
     const { solutionId, agent } = where;
@@ -83,9 +85,7 @@ export async function reviewCommand(result, options) {
     // again once the reviewer has looked.
     if (said?.refused)
         throw new Error(said.refused);
-    console.log(outcome === "escalate"
-        ? `Escalated${onOutcome(where.outcome)}. It waits on the owner's decision.`
-        : `Recorded your review${onOutcome(where.outcome)}: ${outcome}.`);
+    console.log(`Recorded your review${onOutcome(where.outcome)}: ${outcome}.`);
 }
 /**
  * The videos a review carries (SIGHT-13.2): each recorded from a demo's

package/dist/commands/solution/status.js

@@ -104,10 +104,11 @@ async function reviewerOwes(client, solutionId, outcome, agent) {
         if (entry.kind === "submission")
             since = at + 1;
     });
+    // Only a review is a result: a question it put to the owner, or an
+    // escalation withdrawn when escalating went, leaves it still owing one.
     return !thread
         .slice(since)
-        .some((entry) => entry.agent === agent &&
-        (entry.kind === "review" || entry.kind === "escalation"));
+        .some((entry) => entry.agent === agent && entry.kind === "review");
 }
 /**
  * `dotreq solution status`: where the outcome the agent is at stands, as
@@ -139,10 +140,14 @@ export async function statusCommand(options) {
     // other reviewer stalled. Asking, stalling and recording all take the
     // agent off it.
     const atIt = outcome.atWork?.some((each) => each.agent === where.agent && each.part === part) === true;
+    // PULL-5.2: a reviewer waiting on the pull request owes nothing until it
+    // starts again.
+    const waiting = part === "review" && outcome.waiting?.includes(where.agent) === true;
     const owes = part === "draft"
         ? !setAside &&
             (atIt || outcome.status === "drafting" || outcome.status === "ready")
-        : (atIt || outcome.status === "reviewing") &&
+        : !waiting &&
+            (atIt || 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`);

package/dist/commands/solution/things.js

@@ -22,10 +22,10 @@ export function parseThing(reference) {
             return { kind, scoresId: rest };
         case "pr": {
             // PULL-3: the solution's pull request, by the reference
-            // `dotreq solution pull-request` printed.
+            // `dotreq solution pr open` printed.
             const number = Number(rest.replace(/^#/, ""));
             if (!Number.isInteger(number) || number <= 0) {
-                throw new Error(`"${reference}" isn't a pull request's reference. It is pr: and the pull request's number, as \`dotreq solution pull-request\` prints it, e.g. pr:42.`);
+                throw new Error(`"${reference}" isn't a pull request's reference. It is pr: and the pull request's number, as \`dotreq solution pr open\` prints it, e.g. pr:42.`);
             }
             return { kind: "pull request", number };
         }

package/dist/commands/solution/thread.js

@@ -4,7 +4,7 @@ import { requireWhere } from "./run-file.js";
 import { outcomeFor } from "./status.js";
 /**
  * What `--latest` counts: what someone wrote — a submission note, a review
- * result, an escalation or a decision. A stall, a restart and a redraft
+ * result, a decision put to the person or their answer. A stall, a restart and a redraft
  * because the outcome it is on was redrafted are on the thread but not
  * counted, so a drafter revising after a restart reads the review it is
  * answering, not the restart (VERB-6.4, 6.5).

package/dist/convex.d.ts

@@ -99,6 +99,7 @@ export declare const api: {
             next: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
             complete: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
             ask: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
+            completeApproval: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
             stall: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
             answer: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
             approveCheckpoint: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
@@ -121,6 +122,9 @@ export declare const api: {
             recordPush: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
             removal: import("convex/server").FunctionReference<"query", "public", any, any, string | undefined>;
         };
+        waits: {
+            waitOnPullRequest: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
+        };
     };
     lib: {
         authActions: {

package/dist/convex.js

@@ -112,6 +112,8 @@ export const api = {
             next: mutation("solutions/mutations:next"),
             complete: mutation("solutions/mutations:complete"),
             ask: mutation("solutions/mutations:ask"),
+            // DECIDE-4: the action on the option the owner chose, taken once.
+            completeApproval: mutation("solutions/mutations:completeApproval"),
             stall: mutation("solutions/mutations:stall"),
             answer: mutation("solutions/mutations:answer"),
             // A rehearsal's scripted approval of a checkpoint (CHECKPOINT-1.1).
@@ -141,6 +143,9 @@ export const api = {
             recordPush: mutation("solutions/branches:recordPush"),
             removal: query("solutions/branches:removal"),
         },
+        waits: {
+            waitOnPullRequest: mutation("solutions/waits:waitOnPullRequest"),
+        },
     },
     lib: {
         authActions: {

package/dist/rehearsal/types.d.ts

@@ -142,16 +142,15 @@ export type Script = {
     /**
      * Give this review result (reviewing), with the comment every result
      * carries. An approval, with or without revisions, carries an executive
-     * summary (VERB-2.5), and needs revision and escalate carry none; a
-     * script that breaks either is refused, as the agent would be
-     * (REHEARSE-1.1).
+     * summary (VERB-2.5), and needs revision carries none; a script that
+     * breaks either is refused, as the agent would be (REHEARSE-1.1).
      */
     review?: {
-        outcome: "approved" | "approved with revisions" | "needs revision" | "escalate";
+        outcome: "approved" | "approved with revisions" | "needs revision";
         comment: string;
         summary?: string;
     };
-    /** Put a decision to the person instead (drafting). */
+    /** Put a decision to the person instead, drafting or reviewing; a reviewer gives its result once she answers. */
     ask?: unknown;
     /** Stall instead. */
     stall?: string;
@@ -160,7 +159,7 @@ export type Script = {
 export type Party = "real" | Script | Script[];
 /**
  * What the person answers, in order asked: by an outcome's name, her answer
- * to a question or an escalation on it; by a checkpoint's name, her
+ * to a decision its drafter or a reviewer put to her; by a checkpoint's name, her
  * decision there, which a rehearsal gives only as an approval.
  */
 export type PersonScript = Record<string, Array<{
@@ -296,7 +295,7 @@ export type RehearsalClient = {
         /** With `made`: the drafter's executive summary (VERB-1.6). */
         summary?: string;
         review?: {
-            outcome: "approved" | "approved with revisions" | "needs revision" | "escalate";
+            outcome: "approved" | "approved with revisions" | "needs revision";
             comment: string;
             /** With an approval: the executive summary (VERB-2.5). */
             summary?: string;
@@ -314,7 +313,7 @@ export type RehearsalClient = {
         outcome: string;
         reason: string;
     }): Promise<void>;
-    /** The decision open on an outcome — a question or an escalation — or null. Absent when the client can't answer for the person. */
+    /** The decision open on an outcome, its drafter's or a reviewer's, or null. Absent when the client can't answer for the person. */
     openDecision?(solutionId: string, outcome: string): Promise<{
         id: string;
     } | null>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@popoverai/dotrequirements",
-  "version": "0.34.2",
+  "version": "0.36.0",
   "description": "Requirements as testable, human-readable data — CLI and test harness for spec-driven development with AI coding agents",
   "type": "module",
   "bin": {