@popoverai/dotrequirements 0.35.0 → 0.36.1

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/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";
@@ -101,11 +102,17 @@ 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.
+For a reviewer, while the pull request's checks run or GitHub works out whether it
+can merge. Records where it stands now; then end your session without a result.
+You are started again, in this session, once GitHub reports it clean, once it is
+merged or closed, or when the wait is up: ten minutes unless you say, up to an
+hour. A conflict, a failed check or a branch behind doesn't change by waiting:
+judge it now. A new submission ends the wait too, and you review that as you
+would any other.
+
+Examples:
+  dotreq solution pr wait
+  dotreq solution pr wait 30m
 `;
 /** What `pr open` does, on its `--help`, where `author --help` sends the agent (PULL-2). */
 const PULL_REQUEST_HELP = `
@@ -139,8 +146,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
@@ -151,8 +165,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
@@ -173,7 +189,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."
 `;
@@ -247,14 +262,14 @@ export function registerSolution(program) {
         .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"))
+        .command("wait [duration]")
+        .description("Wait on the pull request with your session ended, for ten minutes unless you say (as 5m or 1h, up to an hour): you start again once it is clean, merged or closed, or when the time is up"))
         .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)
@@ -265,14 +280,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

@@ -25,10 +25,7 @@ export type PullRequestState = {
     }>;
     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.
- */
+/** Where the pull request stood, in words, as a wait records it beside what the line shows (PULL-5.1.0). */
 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;
@@ -39,14 +36,17 @@ export declare function describeState(state: PullRequestState): string;
 export declare function prStatusCommand(options: WhereOptions & {
     json?: boolean;
 }): Promise<void>;
+/** A wait's length as an agent types it, `90s`, `5m` or `1h`, in milliseconds; refused past an hour or at none (PULL-5.8 to 5.10). */
+export declare function waitFor(duration: string | undefined): number;
 /**
- * `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).
+ * `dotreq solution pr wait [duration]`: the reviewer waits on the pull
+ * request with no session running (PULL-5), ten minutes unless it says, up
+ * to an hour: it records what it saw, and its session can end without a
+ * result. It starts again, in the same session, once the pull request is
+ * `clean`, once it is merged or closed, or when the wait is up (PULL-6). A
+ * pull request already `clean` needs no wait (5.11).
  */
-export declare function prWaitCommand(options: WhereOptions): Promise<void>;
+export declare function prWaitCommand(duration: string | undefined, options: WhereOptions): Promise<void>;
 /**
  * `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

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

@@ -7,10 +7,7 @@ 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 pr open";
-/**
- * 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.
- */
+/** Where the pull request stood, in words, as a wait records it beside what the line shows (PULL-5.1.0). */
 export function seenOf(state) {
     return [
         state.head,
@@ -72,26 +69,63 @@ export async function prStatusCommand(options) {
     const state = await stateFor(requireWhere(options));
     console.log(options.json ? JSON.stringify(state) : describeState(state));
 }
+/** What a reviewer is told when it asks for a wait it can't have (PULL-5.10), in the backend's words. */
+const WAIT_REFUSED = "Nothing is waiting: a wait is up to an hour, ten minutes unless you say, as `dotreq solution pr wait 5m` or `pr wait 1h`.";
+/** A wait's length as an agent types it, `90s`, `5m` or `1h`, in milliseconds; refused past an hour or at none (PULL-5.8 to 5.10). */
+export function waitFor(duration) {
+    if (duration === undefined)
+        return 10 * 60 * 1000;
+    const found = /^(\d+)(s|m|h)$/.exec(duration.trim());
+    const unit = { s: 1000, m: 60 * 1000, h: 60 * 60 * 1000 };
+    const ms = found ? Number(found[1]) * unit[found[2]] : 0;
+    if (!(ms > 0 && ms <= 60 * 60 * 1000))
+        throw new Error(WAIT_REFUSED);
+    return ms;
+}
+/** In words, how long a wait is. */
+function forHowLong(ms) {
+    if (ms === 3_600_000)
+        return "an hour";
+    if (ms % 60_000 !== 0) {
+        const seconds = Math.round(ms / 1000);
+        return `${seconds} second${seconds === 1 ? "" : "s"}`;
+    }
+    const minutes = ms / 60_000;
+    return `${minutes} minute${minutes === 1 ? "" : "s"}`;
+}
 /**
- * `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).
+ * `dotreq solution pr wait [duration]`: the reviewer waits on the pull
+ * request with no session running (PULL-5), ten minutes unless it says, up
+ * to an hour: it records what it saw, and its session can end without a
+ * result. It starts again, in the same session, once the pull request is
+ * `clean`, once it is merged or closed, or when the wait is up (PULL-6). A
+ * pull request already `clean` needs no wait (5.11).
  */
-export async function prWaitCommand(options) {
+export async function prWaitCommand(duration, options) {
+    const forMs = waitFor(duration);
     const where = requireWhere(options);
     const state = await stateFor(where);
+    if (state.mergeState === "clean") {
+        throw new Error(`Nothing is waiting: the pull request is already \`clean\`.\n\n${describeState(state)}`);
+    }
     await solutionClient().mutation(api.solutions.waits.waitOnPullRequest, {
         solutionId: where.solutionId,
         agent: where.agent,
         ...(where.outcome ? { outcome: where.outcome } : {}),
         seen: seenOf(state),
+        saw: {
+            number: state.number,
+            url: state.url,
+            conflicting: state.mergeable === "conflicting",
+            failed: state.failed.length,
+            running: state.running.length,
+        },
+        forMs,
     });
     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.",
+        `Waiting on it. End your session now: you'll be started again, here, once it is \`clean\`, once it is merged or closed, or in ${forHowLong(forMs)}, whichever comes first.`,
     ].join("\n"));
 }
 /**

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

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>;

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).

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.35.0",
+  "version": "0.36.1",
   "description": "Requirements as testable, human-readable data — CLI and test harness for spec-driven development with AI coding agents",
   "type": "module",
   "bin": {