@popoverai/dotrequirements 0.34.1 → 0.35.0

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

@@ -49,6 +49,13 @@ export type PanelOutcome = {
     waitingFor?: string[];
     /** Its drafter's work was set aside and its new draft isn't taken yet: a session at it owes nothing more (CHECKPOINT-6.3.2.3). */
     setAside?: boolean;
+    /** The agents at it now, each drafting it or reviewing it; absent from a backend from before it said. */
+    atWork?: Array<{
+        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/index.js

@@ -6,7 +6,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 +41,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 +91,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
 
@@ -216,11 +232,25 @@ 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"))

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/status.js

@@ -23,6 +23,11 @@ export function agentAt(panel, agent, named) {
         if (!drafting && !reviewing) {
             throw new Error(`${agent} neither drafts nor reviews "${named}".`);
         }
+        // At it now: the part it is at, as for an agent that both drafts and
+        // reviews the outcome, whatever word the outcome stands in.
+        const at = outcome.atWork?.find((each) => each.agent === agent);
+        if (at)
+            return { outcome, part: at.part };
         return {
             outcome,
             part: reviewing && (!drafting || outcome.status === "reviewing")
@@ -129,10 +134,19 @@ export async function statusCommand(options) {
     // 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;
+    // STEP-REVIEW-9.8: an agent still at its part owes it, whatever word the
+    // outcome stands in because of its other agents, as stalled when the
+    // 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 &&
-            (outcome.status === "drafting" || outcome.status === "ready")
-        : outcome.status === "reviewing" &&
+            (atIt || outcome.status === "drafting" || outcome.status === "ready")
+        : !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/convex.d.ts

@@ -121,6 +121,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

@@ -141,6 +141,9 @@ export const api = {
             recordPush: mutation("solutions/branches:recordPush"),
             removal: query("solutions/branches:removal"),
         },
+        waits: {
+            waitOnPullRequest: mutation("solutions/waits:waitOnPullRequest"),
+        },
     },
     lib: {
         authActions: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@popoverai/dotrequirements",
-  "version": "0.34.1",
+  "version": "0.35.0",
   "description": "Requirements as testable, human-readable data — CLI and test harness for spec-driven development with AI coding agents",
   "type": "module",
   "bin": {
@@ -26,9 +26,9 @@
     "test": "vitest",
     "test:run": "vitest run",
     "test:coverage": "vitest run --coverage",
-    "publish:patch": "echo 'ERROR: publish:patch is decommissioned. CLI npm publishes now happen via the cli-publish GitHub Action when a production PR with a CLI version bump merges. Use the /release Claude Code skill to queue a bump and open the production PR. See docs/working/cli-publish-workflow.md for details.' && exit 1",
-    "publish:minor": "echo 'ERROR: publish:minor is decommissioned. CLI npm publishes now happen via the cli-publish GitHub Action when a production PR with a CLI version bump merges. Use the /release Claude Code skill to queue a bump and open the production PR. See docs/working/cli-publish-workflow.md for details.' && exit 1",
-    "publish:major": "echo 'ERROR: publish:major is decommissioned. CLI npm publishes now happen via the cli-publish GitHub Action when a production PR with a CLI version bump merges. Use the /release Claude Code skill to queue a bump and open the production PR. See docs/working/cli-publish-workflow.md for details.' && exit 1"
+    "publish:patch": "echo 'ERROR: publish:patch is decommissioned. CLI npm publishes now happen via the cli-publish GitHub Action when a PR that bumps the CLI version merges to main. See docs/working/cli-publish-workflow.md for details.' && exit 1",
+    "publish:minor": "echo 'ERROR: publish:minor is decommissioned. CLI npm publishes now happen via the cli-publish GitHub Action when a PR that bumps the CLI version merges to main. See docs/working/cli-publish-workflow.md for details.' && exit 1",
+    "publish:major": "echo 'ERROR: publish:major is decommissioned. CLI npm publishes now happen via the cli-publish GitHub Action when a PR that bumps the CLI version merges to main. See docs/working/cli-publish-workflow.md for details.' && exit 1"
   },
   "keywords": [
     "requirements",