From 381d69b7750fdfa9caa23a89f0b2a429d4048369 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 21 Nov 2026 23:23:37 -0800 Subject: [PATCH 1/4] chore(quest): claim quest/m0/afk-and-waits.md Quest-Claim: 0623f95ac6e214cc From 073959fc9cf37037e7b712f069b52639ea9ca12c Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 21 Nov 2026 23:29:18 -0800 Subject: [PATCH 2/4] feat: afk merge and afk soon modes, PC-only waits, and pending-CI waits in /quest-run - /quest-afk: bare `afk` runs it; `afk merge` merges strongly recommended low or medium PRs with a counting review and no decisions or follow-ups, deferring high or unclassified ones; `afk soon` asks pending questions in one batch, then goes afk. - `Maintainer (PC):` marks a step only the maintainer's computers can take; `quest waiting --no-pc` drops them and --json reports `pc`; `quest check` rejects other maintainer qualifiers. - /quest-run waits on ready PRs whose required checks are still running, and skips or front-loads PC steps by its argument. Co-Authored-By: Claude Opus 5.5 --- .agents/skills/quest-afk/SKILL.md | 2 +- .claude/skills/quest-afk/SKILL.md | 2 +- README.md | 13 +++- assets/AGENTS.md | 1 + assets/skills/afk.md | 15 +++- assets/skills/run.md | 7 +- quest/m0/afk-and-waits.md | 41 ----------- quest/m1/cursor-reviewer.md | 2 +- src/cli/main.ts | 26 ++++--- src/core/claim.ts | 3 +- src/core/rules.ts | 2 +- src/core/unblocked.ts | 18 ++++- src/core/waiting.ts | 17 ++++- test/cli.test.ts | 10 ++- test/waiting.test.ts | 117 ++++++++++++++++++++++-------- 15 files changed, 168 insertions(+), 108 deletions(-) delete mode 100644 quest/m0/afk-and-waits.md diff --git a/.agents/skills/quest-afk/SKILL.md b/.agents/skills/quest-afk/SKILL.md index 2d986ae7d..af5868b4e 100644 --- a/.agents/skills/quest-afk/SKILL.md +++ b/.agents/skills/quest-afk/SKILL.md @@ -1,6 +1,6 @@ --- name: quest-afk -description: Keep this session's work going while the user is away, taking your recommendations and deferring merge picks until they return. +description: Keep this session's work going while the user is away, taking your recommendations and deferring merge picks until they return. Use when the user says afk, afk merge, or afk soon. --- Run `quest skill afk` and follow its output. diff --git a/.claude/skills/quest-afk/SKILL.md b/.claude/skills/quest-afk/SKILL.md index c07e213ac..27c88d8d6 100644 --- a/.claude/skills/quest-afk/SKILL.md +++ b/.claude/skills/quest-afk/SKILL.md @@ -1,6 +1,6 @@ --- name: quest-afk -description: Keep this session's work going while the user is away, taking your recommendations and deferring merge picks until they return. +description: Keep this session's work going while the user is away, taking your recommendations and deferring merge picks until they return. Use when the user says afk, afk merge, or afk soon. allowed-tools: Bash(quest skill afk) PowerShell(quest skill afk) --- diff --git a/README.md b/README.md index 9b21ae2ff..f75a84279 100644 --- a/README.md +++ b/README.md @@ -244,13 +244,16 @@ second name in one `## Audit`, and `## Skipped audits` outside the root. A quest waiting outside the tree says so in a `## Waiting` section, one item per condition, each opening with who acts: `Maintainer:` for a decision or -action only the maintainer can take, or the outside party, such as -`moq-dev/moq:`. `quest check` rejects an item that names nobody. +action only the maintainer can take, `Maintainer (PC):` for one they can take +only at one of their computers, such as a local login or a hardware check, or +the outside party, such as `moq-dev/moq:`. `quest check` rejects an item that +names nobody, and a maintainer qualifier other than `(PC)`. ```markdown ## Waiting - Maintainer: open a Hetzner account; `GET /server` on the Robot API answers 200 +- Maintainer (PC): plug in the capture card; `v4l2-ctl --list-devices` lists it - moq-dev/moq: a release carries the VA-API bindings ``` @@ -261,8 +264,10 @@ body. milestone and the same downstream impact `quest unblocked` counts; a draft ranks as the quest its branch carries. Each line gives the dependents, whether the quest is otherwise ready or still blocked, its path or the draft's URL, and -the item; `--maintainer` keeps only the maintainer's, and `--json` prints -`{path, pr, dependents, ready, waits}` objects. A draft's item that names no +the item; `--maintainer` keeps only the maintainer's, `--no-pc` drops the +`Maintainer (PC):` ones for a session away from your computers, and `--json` +prints `{path, pr, dependents, ready, waits}` objects, each wait's `pc` marking +those. A draft's item that names no party is the maintainer's. Drafts come from the upstream's open PRs, found as for `unblocked --unclaimed`; without the remote, off GitHub, or when GitHub cannot be read, it lists the tree's items diff --git a/assets/AGENTS.md b/assets/AGENTS.md index 849a3a9c5..6511c15e8 100644 --- a/assets/AGENTS.md +++ b/assets/AGENTS.md @@ -83,6 +83,7 @@ An epic carries no size until its last child is deleted; its README is then the A quest without it runs anywhere; `quest unblocked --json` reports the list as `hosts` so a dispatcher routes work without reading prose. `Waiting` lists what the work waits on outside the tree; each item opens with who acts, `Maintainer:` or the outside party, before a colon. +Open a step the maintainer can take only at one of their computers, such as a password-manager unlock, a hardware check, or a local login, with `Maintainer (PC):` instead, so a session away from them skips it; a decision or a step on a website stays `Maintainer:`. A decision item gives its options and a recommendation. Remove an item once its condition clears, and the heading with its last item. diff --git a/assets/skills/afk.md b/assets/skills/afk.md index c065eb54d..a067b9003 100644 --- a/assets/skills/afk.md +++ b/assets/skills/afk.md @@ -1,13 +1,20 @@ --- -description: Keep this session's work going while the user is away, taking your recommendations and deferring merge picks until they return. +description: Keep this session's work going while the user is away, taking your recommendations and deferring merge picks until they return. Use when the user says afk, afk merge, or afk soon. guide: Summaries --- -The user has stepped away and will not answer. +The user has stepped away and will not answer; a message of just `afk`, or `afk` and a mode below, runs this skill. Keep this session's work going within its scope: the skill it is running, such as `/quest-run`, or else the task at hand. In a session with no work under way, run `/quest-run`. Ask nothing: wherever you or an agent would ask the user, take your recommendation instead, unless the decision is deferred below. A deferred question counts as asked, so a skill's loop goes on past it and finishes as that skill describes. -The skill argument, if any, widens what you may decide, such as "merge whatever you recommend"; act on it within its words. + +The argument picks a mode, and modes combine, such as `soon merge`: + +- None: every merge pick below waits for the user. +- `merge`: also run `/quest-merge` on each PR you strongly recommend merging that `quest status` shows low or medium for its head, with a review that counts for that head, no open decision, no follow-ups, and no quest deleted or deprioritized beyond the one it finishes. Defer every other PR, a high or unclassified one included. +- `soon`: the user is about to leave. Ask every question the session has pending now, in one batch, as `/quest-run`'s "decisions" does, and act on the answers; once the prompt returns, go on as afk, taking or deferring each question it left unanswered as below. + +Other words widen what you may decide, such as "close superseded PRs"; act on them within their words. A grant of merges that names no risk tier is `merge`. Take every decision a later PR review can still undo: @@ -15,7 +22,7 @@ Take every decision a later PR review can still undo: - Tell each agent you dispatch that the user is away, so it does the same. - As a coordinator, dispatch `/quest-iterate` on a PR with open decisions, with your recommended answers in its brief. -Unless the argument allows it, defer as blockers what no review can undo and what only the user can do: +Unless the mode or argument allows it, defer as blockers what no review can undo and what only the user can do: - Merge picks beyond a standing `/quest-merge` pick, deleting or deprioritizing a quest, closing a PR, and taking over a stale claim or hold. - A follow-up's decisions, which wait for its PR's pick. diff --git a/assets/skills/run.md b/assets/skills/run.md index c57671ca2..813af4c6c 100644 --- a/assets/skills/run.md +++ b/assets/skills/run.md @@ -67,6 +67,7 @@ Rewrite a quest that waits in prose into a `## Waiting` section. Check each condition yourself, in parallel sub-agents. An outside party's item that holds stays, asked about only when the user can advance it, such as by requesting an upstream release. Ask each maintainer item left among the round's questions, in that order, saying what it unblocks; a skip stands for the session. +A `Maintainer (PC):` item needs the user at one of their computers: when the argument says they are away from one, such as `remote` or `on my phone`, read the waits with `--no-pc` and leave those items for a later session; when it says they are at one, such as `at my PC`, ask those first. For an action only the user can take, give the exact steps and the check you will run once they report it done; take any secret through the host's secret prompt. Settle a draft's items with its PR, naming cleared ones in its `/quest-iterate` brief. @@ -76,11 +77,11 @@ Make these edits in one draft PR on a `quest-run/` branch, run `quest chec ## Loop Each round, rerun `quest unblocked --unclaimed --json` and refresh the open PRs, since merges and released claims make more work ready. -When no agent is running and every question has been asked, block with `quest wait` on the queued PRs whose merge would make a quest ready, and run a round once one lands or leaves the queue. -Never wait on any other PR, and read none between rounds: list each PR left for a later round in the summary, with its pick. +When no agent is running and every question has been asked, block with `quest wait` on the queued PRs whose merge would make a quest ready, and on each PR ready for review whose required checks are still running and which a round would then pick or ask about; run a round once one lands, leaves the queue, or its checks finish. +Wait on no other PR, such as a draft or a skipped one, and read none between rounds: list each PR left for a later round in the summary, with its pick. A usage or rate limit is waited out until its reset; it never ends the run. -Finish once nothing is running, no queued merge would make a quest ready, every PR left needs the user or a later round, and every wait in scope is decided, skipped, or left to an outside party. +Finish once nothing is running, no queued merge would make a quest ready, no PR waited on above still has checks running, every PR left needs the user or a later round, and every wait in scope is decided, skipped, or left to an outside party. Then run `/quest-plan` on the run's follow-ups, each in a checkout of the repository whose quest tree owns it: problems it surfaced that no quest or open PR owns, such as a blocker agents hit, and the follow-ups kept in each of this run's own merge picks for another repository's quest tree, landed or not, unless the user withdrew the pick. Write the final summary, naming those plan PRs and listing the waits settled, cleared, or deleted and each still held with who acts and its check's result, so a fresh session can act on it, with each open decision's options beside your recommendation. diff --git a/quest/m0/afk-and-waits.md b/quest/m0/afk-and-waits.md deleted file mode 100644 index 953c548c1..000000000 --- a/quest/m0/afk-and-waits.md +++ /dev/null @@ -1,41 +0,0 @@ -# [M] Streamline /quest-afk modes, PC-local waits, and pending-CI waits - -## Goal - -Reduce repeated manual prompts during interactive, mobile/travel, and AFK sessions across three coordinated improvements: - -1. **`/quest-afk` modes (`assets/skills/afk.md`):** Keep bare `afk` conservative (standing picks only, deferring other merges until classes in [`RISK.md`](/RISK.md)'s `## Automatic` list earn wider auto-merge), and add two explicit modes: `afk merge` (merge any non-high-risk PR the agent strongly recommends with a clean review and no open decisions, still deferring high-risk or uncertain PRs and quest deletions) and `afk soon` (flush pending decisions in one batch, then automatically enter `afk`). -2. **PC-local vs tap-anywhere waits (`src/core/waiting.ts`, `quest waiting`, `quest check`, `assets/AGENTS.md`, `assets/skills/run.md`):** Distinguish local/PC maintainer actions (such as password-manager unlocks, hardware checks, or local logins) from decisions answerable from any device, with filtering on `quest waiting` so remote/travel sessions skip PC-local waits and `"at my PC"` sessions batch them. -3. **Pending-CI waiting in `/quest-run` (`assets/skills/run.md`):** When no sub-agent is running and every current question is asked, also block with `quest wait` on open PRs whose required checks are still pending (in addition to queued PRs whose merge unblocks a quest) so those PRs get picked in the same session instead of ending early. - -Non-goal: changing risk-tier definitions or automatic low-risk merge classes on bare `afk` (set by [`RISK.md`](/RISK.md) and the README's Risk tiers section since [moq-dev/quest#802](https://github.com/moq-dev/quest/pull/802)). - -## Plan - -Decided 2026-11-21 (maintainer, `/quest-plan`, from a 22-day transcript audit across three of the maintainer's hosts): - -- How should `/quest-afk` handle merge authority and pre-AFK decision flushes? - - ✅ Keep bare `afk` safe; add explicit `afk merge` (non-high-risk, strongly recommended PRs) and `afk soon` (flush decisions then enter `afk`) (recommended) - - Rejected: make bare `afk` auto-merge high-confidence non-high-risk PRs by default; keep bare `afk` strictly standing-picks-only with no new shorthand -- Should we add PC-vs-decision waits and pending-CI waits in `/quest-run`? - - ✅ Yes, include both alongside the hook changes (recommended) - - Rejected: skip pending-CI waits; skip PC-vs-decision waits - -Evidence from the 2026-11-21 audit: - -- Bare `afk` was typed 115 times (vs `/quest-afk` 5 times), and the maintainer explicitly spelled out variations of "afk merge anything you strongly/confidently recommend" 23 times (16 since 2026-11-14) plus pre-flight decision flushes ("about to board, any decisions needed?") repeatedly while traveling. -- After returning home, the maintainer pasted "anything that needs me, at my PC" across 6 repositories in a row (13 times total since 2026-11-14) because `## Waiting` mixes phone-answerable decisions with PC-only local actions. -- The maintainer typed "any new PRs?" or "any new quests" 41 times (7 since 2026-11-14) because `/quest-run` exited whenever no sub-agent was running and no queued PR unblocked a quest, leaving PRs with 2-minute pending required checks unpicked. - -This quest edits `assets/AGENTS.md` and `assets/skills/`, which the maintainer asked for by planning it. - -Agent's choices, for the implementer to revisit: - -- For PC-local waits in `src/core/waiting.ts`: recognize `Maintainer (PC):` (or `Maintainer (local):`, treating it as `onMaintainer` with a boolean `local` / `pc` field in `quest waiting --json`, plus `--pc` and `--decisions` filter flags on `quest waiting`). Update `quest check` and `assets/AGENTS.md`'s `Format` section to document the syntax, and make `/quest-run`'s `## Waits` instructions respect a `"at my PC"` vs `"remote / away from PC"` argument. -- In `assets/skills/afk.md`: note that bare `afk` (not only `/quest-afk`) activates the skill, define `afk merge` against the PR's recorded risk tier (deferring `high` risk, unreviewed heads, open decisions, follow-up drops, and quest deletions), and define `afk soon` as running `"decisions"` once and then continuing in `afk` without a second prompt. -- In `assets/skills/run.md`: bound pending-CI waits to open, ready-for-review PRs whose required checks are pending and that still need a merge pick (not drafts waiting on outside parties, not skipped PRs, and not optional reviewers), so `/quest-run` still finishes cleanly when nothing actionable is in flight. -- Verify with unit tests for `src/core/waiting.ts` and `quest waiting` filters, plus `just check` and `just test`. - -## Related - -- [`RISK.md`](/RISK.md) and the README's Risk tiers section, since [moq-dev/quest#802](https://github.com/moq-dev/quest/pull/802) - risk tiers define the `high` boundary `afk merge` defers and will widen standing auto-merge separately diff --git a/quest/m1/cursor-reviewer.md b/quest/m1/cursor-reviewer.md index 13a4f0310..22edf188c 100644 --- a/quest/m1/cursor-reviewer.md +++ b/quest/m1/cursor-reviewer.md @@ -61,5 +61,5 @@ Guidance: ## Waiting -- Maintainer: log Cursor's CLI in on a macOS host of the maintainer's, at a version no older than `2026.11.13-eacade1`, so an agent can run the isolation test on macOS before this quest's PR merges. Check with `cursor-agent status`, which prints `Logged in as ` when done. An agent cannot finish Cursor's browser login on the maintainer's account; it can drive the maintainer's agent browser through `NO_OPEN_BROWSER=1 cursor-agent login`'s URL once the maintainer picks the account, as it did on Linux. The maintainer's Linux workstation that runs agent sessions was logged in on 2026-11-21 (CLI `2026.11.19-f005e9d`, from nixpkgs' unfree `cursor-cli` through `nix shell`, not installed); until kixel-ai/dotfiles installs it on the hosts, the implementer gets it with `NIXPKGS_ALLOW_UNFREE=1 nix shell --impure nixpkgs#cursor-cli`. +- Maintainer (PC): log Cursor's CLI in on a macOS host of the maintainer's, at a version no older than `2026.11.13-eacade1`, so an agent can run the isolation test on macOS before this quest's PR merges. Check with `cursor-agent status`, which prints `Logged in as ` when done. An agent cannot finish Cursor's browser login on the maintainer's account; it can drive the maintainer's agent browser through `NO_OPEN_BROWSER=1 cursor-agent login`'s URL once the maintainer picks the account, as it did on Linux. The maintainer's Linux workstation that runs agent sessions was logged in on 2026-11-21 (CLI `2026.11.19-f005e9d`, from nixpkgs' unfree `cursor-cli` through `nix shell`, not installed); until kixel-ai/dotfiles installs it on the hosts, the implementer gets it with `NIXPKGS_ALLOW_UNFREE=1 nix shell --impure nixpkgs#cursor-cli`. - kixel-ai/token-max: `token-max sessions` prices Cursor CLI sessions, so `quest eval run` reports Cursor reviewers' real cost instead of a lower-bound `$0.00`. Check that a Cursor review session's line in `token-max sessions` shows a nonzero cost. Advance it with `/quest-plan` in that repository; its tree had no such quest on 2026-11-17. If that stalls, the Plan's fallback prices Cursor seats in `quest eval` from the usage its stream reports. diff --git a/src/cli/main.ts b/src/cli/main.ts index ce38c0690..35a3eeea3 100644 --- a/src/cli/main.ts +++ b/src/cli/main.ts @@ -29,7 +29,6 @@ import { SIZES, type Size, unblocked, - onMaintainer, waiting, InputError, Refusal, @@ -489,13 +488,16 @@ export function main(argv: string[], out: Output): number | Promise { "transitive dependents as quest unblocked counts them, ready before blocked, then path order, with " + "drafts after quests by PR number. A draft ranks as the quest its branch carries, or last when it " + "carries none. Each item opens with who acts, Maintainer: or an outside party such as moq-dev/moq:, " + - "followed by the condition and how to check or advance it. A draft's item without a party is the " + + "followed by the condition and how to check or advance it; Maintainer (PC): marks a step the maintainer " + + "can take only at one of their computers, such as a local login or a hardware check. A draft's item without a party is the " + "maintainer's; a draft's section without items is one maintainer item " + "holding its prose.\n\n" + "Prints one line per item: dependents, ready or blocked (whether Required entries or a future " + "Scheduled date remain), the quest's path or the draft's URL, and the item. --json prints an ordered array of {path, pr, dependents, " + - "ready, waits: [{line, party, text}]} objects, where pr is the draft's URL or null and path is the " + - "quest, the quest a draft carries, or null. --maintainer keeps only the items the maintainer settles. " + + "ready, waits: [{line, party, pc, text}]} objects, where pr is the draft's URL or null, path is the " + + "quest, the quest a draft carries, or null, and pc is whether the item opened Maintainer (PC):. " + + "--maintainer keeps only the items the maintainer settles, and --no-pc drops the Maintainer (PC): ones, " + + "for a session away from the maintainer's computers. " + "Invalid trees fail before printing. Outside conditions are never checked, nor whether another " + "session holds a draft.\n\n" + "Drafts are read from the open PRs of the remote's upstream, found as for quest unblocked " + @@ -506,18 +508,18 @@ export function main(argv: string[], out: Output): number | Promise { ) .option("--json", "Print a deterministic JSON array") .option("--maintainer", "Only items waiting on the maintainer") + .option("--no-pc", "Skip the steps only the maintainer's computers can take, Maintainer (PC): items") .option("--limit ", "Maximum number of entries to print", positiveInteger("limit")) .option("--remote ", "Remote whose upstream holds the draft PRs", "origin") - .action((options: { json?: boolean; maintainer?: boolean; limit?: number; remote: string }) => { + .action((options: { json?: boolean; maintainer?: boolean; pc: boolean; limit?: number; remote: string }) => { const tree = checkout(root(), warn); if (!valid(tree)) return; settle(openDrafts(root(), options.remote, claimDependencies()), (drafts) => { - const found = waiting(tree.docs, today(), drafts) - .map((quest) => - options.maintainer ? { ...quest, waits: quest.waits.filter(onMaintainer) } : quest, - ) - .filter((quest) => quest.waits.length > 0) - .slice(0, options.limit); + const found = waiting(tree.docs, today(), { + drafts, + maintainer: options.maintainer, + pc: options.pc, + }).slice(0, options.limit); if (options.json) { print(JSON.stringify(found)); return; @@ -527,7 +529,7 @@ export function main(argv: string[], out: Output): number | Promise { for (const quest of found) { for (const wait of quest.waits) { print( - `${quest.dependents}\t${quest.ready ? "ready" : "blocked"}\t${quest.pr ?? quest.path}\t${wait.party}: ${wait.text}`, + `${quest.dependents}\t${quest.ready ? "ready" : "blocked"}\t${quest.pr ?? quest.path}\t${wait.party}${wait.pc ? " (PC)" : ""}: ${wait.text}`, ); } } diff --git a/src/core/claim.ts b/src/core/claim.ts index 3ac2216fd..58e2536df 100644 --- a/src/core/claim.ts +++ b/src/core/claim.ts @@ -94,12 +94,13 @@ export function handBackWaits(body: string): Wait[] { .map((item): Wait => { // GitHub renders a leading `[ ]` or `[x]` as a task-list checkbox, so the item's text follows it. const entry = { line: item.position?.start.line ?? 1, text: collapse(text(item)).replace(TASK, "") }; - return parseWait(entry) ?? { ...entry, party: MAINTAINER }; + return parseWait(entry) ?? { ...entry, party: MAINTAINER, pc: false }; }); if (items.length === 0) items.push({ line: body.slice(0, start).split("\n").length, party: MAINTAINER, + pc: false, text: collapse(nodes.map(text).join(" ")) || "the draft hands back without saying what it waits on", }); found.push(...items); diff --git a/src/core/rules.ts b/src/core/rules.ts index 248cce1f1..c66f77a00 100644 --- a/src/core/rules.ts +++ b/src/core/rules.ts @@ -256,7 +256,7 @@ function headings(found: Finding[], docs: Doc[], doc: Doc) { found.push({ path: doc.path, line: entry.line, - message: `'## ${WAITING}' item must open with who acts, as '${MAINTAINER}: ...' or ': ...'`, + message: `'## ${WAITING}' item must open with who acts, as '${MAINTAINER}: ...', '${MAINTAINER} (PC): ...' for a step only at their computer, or ': ...'`, }); } } diff --git a/src/core/unblocked.ts b/src/core/unblocked.ts index 59655e520..02c848fdf 100644 --- a/src/core/unblocked.ts +++ b/src/core/unblocked.ts @@ -108,15 +108,27 @@ export interface WaitingQuest { waits: Wait[]; } +/** What `waiting` reads beyond the tree, and which items it keeps. */ +export interface WaitingOptions { + /** The open drafts to read hand-backs from. */ + drafts?: Draft[]; + /** Keep only the maintainer's items. */ + maintainer?: boolean; + /** `false` drops `Maintainer (PC):` items, for a session away from the maintainer's computers. */ + pc?: boolean; +} + /** * Every quest with a `## Waiting` section and every draft in `drafts` handed - * back with one: those waiting on the maintainer first, then milestone order, + * back with one, holding the items `options` keeps: those waiting on the maintainer first, then milestone order, * descending downstream impact, ready before blocked, then tree order, with * drafts after quests in the order given. A draft ranks as the quest its branch * carries, or last when it carries none. Readiness is as of `today`, a * `YYYY-MM-DD` date. Validates the tree first, as `unblocked` does. */ -export function waiting(docs: Doc[], today: string, drafts: Draft[] = []): WaitingQuest[] { +export function waiting(docs: Doc[], today: string, options: WaitingOptions = {}): WaitingQuest[] { + const { drafts = [], maintainer: only = false, pc = true } = options; + const kept = (wait: Wait) => (!only || onMaintainer(wait)) && (pc || !wait.pc); const rank = ranking(docs); const startable = new Set(ready(docs, today)); const maintainer = (quest: WaitingQuest) => (quest.waits.some(onMaintainer) ? 0 : 1); @@ -127,7 +139,7 @@ export function waiting(docs: Doc[], today: string, drafts: Draft[] = []): Waiti pr, dependents: path === null ? 0 : rank.impact(path), ready: path === null || startable.has(path), - waits: found, + waits: found.filter(kept), }); const quests = treeOrder(docs).map((path) => entry(path, null, waits(byPath.get(path)!))); const pulls = drafts.map((draft) => { diff --git a/src/core/waiting.ts b/src/core/waiting.ts index 41cbb22bf..6e5a5b500 100644 --- a/src/core/waiting.ts +++ b/src/core/waiting.ts @@ -1,6 +1,7 @@ // What a quest waits on outside its own work: the `## Waiting` section, where -// each top-level item opens with who acts, `Maintainer:` or an outside party -// such as `moq-dev/moq:`. The same heading hands a draft PR back (claim.ts). +// each top-level item opens with who acts, `Maintainer:`, `Maintainer (PC):`, or +// an outside party such as `moq-dev/moq:`. The same heading hands a draft PR back +// (claim.ts). import { type Doc, type Entry, entries } from "./doc"; @@ -16,6 +17,8 @@ export interface Wait { line: number; /** Who acts, as the item opens: `Maintainer`, or an outside party. */ party: string; + /** A step the maintainer can take only at one of their computers, opened as `Maintainer (PC):`. */ + pc: boolean; /** The condition, and how to check or advance it. */ text: string; } @@ -24,11 +27,19 @@ export interface Wait { // `Akamai sales`. A longer run reads as a sentence that happens to hold a colon. const PARTY = /^([^:\s][^:]{0,39}):\s+(\S[\s\S]*)$/; +// The maintainer with a qualifier; only `(PC)` is one, so a typo such as `(local)` fails +// `quest check` instead of reading as an outside party. +const QUALIFIED = /^maintainer\s*\((.*)\)$/i; + /** Parse one `## Waiting` item, or `null` when it does not open with its party. */ export function parseWait(entry: Pick): Wait | null { const match = PARTY.exec(entry.text.replace(/\s+/g, " ").trim()); if (!match) return null; - return { line: entry.line, party: match[1].trim(), text: match[2] }; + const party = match[1].trim(); + const qualified = QUALIFIED.exec(party); + if (!qualified) return { line: entry.line, party, pc: false, text: match[2] }; + if (qualified[1].trim().toLowerCase() !== "pc") return null; + return { line: entry.line, party: MAINTAINER, pc: true, text: match[2] }; } /** `doc`'s waits, in source order; an item without a party is left to `quest check`. */ diff --git a/test/cli.test.ts b/test/cli.test.ts index a6490c392..685f82438 100644 --- a/test/cli.test.ts +++ b/test/cli.test.ts @@ -39,15 +39,16 @@ test("unblocked accepts a filesystem path", () => { test("waiting lists the maintainer's items first, one per line, and says drafts were skipped offline", async () => { const tree = Tree.baseline() .append("quest/m0/epic/one.md", "\n## Waiting\n\n- moq-dev/moq: a release carries the fix.\n") - .append("quest/m0/epic/two.md", "\n## Waiting\n\n- Maintainer: pick a name.\n"); + .append("quest/m0/epic/two.md", "\n## Waiting\n\n- Maintainer: pick a name.\n- Maintainer (PC): log in.\n"); expect(await tree.exec("waiting")).toEqual({ code: 0, stdout: "0\tblocked\tquest/m0/epic/two.md\tMaintainer: pick a name.\n" + + "0\tblocked\tquest/m0/epic/two.md\tMaintainer (PC): log in.\n" + "1\tready\tquest/m0/epic/one.md\tmoq-dev/moq: a release carries the fix.\n", stderr: "quest: no origin remote, so draft PRs were skipped\n", }); - expect((await tree.exec("waiting", "--maintainer")).stdout).toBe( + expect((await tree.exec("waiting", "--maintainer", "--no-pc")).stdout).toBe( "0\tblocked\tquest/m0/epic/two.md\tMaintainer: pick a name.\n", ); expect(JSON.parse((await tree.exec("waiting", "--json", "--limit", "1")).stdout)).toEqual([ @@ -56,7 +57,10 @@ test("waiting lists the maintainer's items first, one per line, and says drafts pr: null, dependents: 0, ready: false, - waits: [{ line: expect.any(Number), party: "Maintainer", text: "pick a name." }], + waits: [ + { line: expect.any(Number), party: "Maintainer", pc: false, text: "pick a name." }, + { line: expect.any(Number), party: "Maintainer", pc: true, text: "log in." }, + ], }, ]); }); diff --git a/test/waiting.test.ts b/test/waiting.test.ts index 2b8b519a0..374bbc4a6 100644 --- a/test/waiting.test.ts +++ b/test/waiting.test.ts @@ -5,6 +5,7 @@ import { check, handBackWaits, handedBack, + onMaintainer, parse, parseWait, unblocked, @@ -30,12 +31,62 @@ test("a wait opens with its party", () => { "# [S] A\n\n## Goal\n\nA.\n\n## Waiting\n\n- Maintainer: open the account,\n then check `GET /server`.\n- moq-dev/moq: a release carries the fix.\n- No party is named here\n- This sentence runs on far too long before it reaches a colon: so it is prose\n", ); const [account, release, none, prose] = doc.entries.map(parseWait); - expect(account).toEqual({ line: 9, party: "Maintainer", text: "open the account, then check GET /server." }); - expect(release).toMatchObject({ party: "moq-dev/moq", text: "a release carries the fix." }); + expect(account).toEqual({ + line: 9, + party: "Maintainer", + pc: false, + text: "open the account, then check GET /server.", + }); + expect(release).toMatchObject({ party: "moq-dev/moq", pc: false, text: "a release carries the fix." }); expect(none).toBeNull(); expect(prose).toBeNull(); }); +test("Maintainer (PC) is the maintainer's step at their computer, and no other qualifier parses", () => { + const doc = parse( + "quest/m0/a.md", + "# [S] A\n\n## Waiting\n\n- Maintainer (PC): unlock the vault.\n- maintainer(pc): plug in the camera.\n" + + "- Maintainer (local): log in.\n- Maintainers: agree.\n", + ); + const [vault, camera, local, plural] = doc.entries.map(parseWait); + expect(vault).toEqual({ line: 5, party: "Maintainer", pc: true, text: "unlock the vault." }); + expect(camera).toMatchObject({ party: "Maintainer", pc: true }); + expect(local).toBeNull(); + expect(plural).toMatchObject({ party: "Maintainers", pc: false }); + expect(onMaintainer(vault!)).toBe(true); + expect(onMaintainer(plural!)).toBe(false); + expect(handBackWaits("## Waiting\n\n- Maintainer (PC): unlock.\n- Maintainer (home): log in.\n")).toEqual([ + { line: 3, party: "Maintainer", pc: true, text: "unlock." }, + { line: 4, party: "Maintainer", pc: false, text: "Maintainer (home): log in." }, + ]); +}); + +test("waiting drops PC steps on request, and ranks by the items it keeps", () => { + const docs = tree({ + "a.md": "\n## Waiting\n\n- Maintainer (PC): unlock the vault.\n- moq-dev/moq: a release.\n", + "b.md": "\n## Waiting\n\n- Maintainer: pick a name.\n- Maintainer (PC): log in.\n", + "c.md": "\n## Waiting\n\n- moq-dev/moq: another release.\n", + }); + const shown = (options: Parameters[2]) => + waiting(docs, TODAY, options).map((quest) => [quest.path, quest.waits.map((wait) => wait.text)]); + expect(shown({})).toEqual([ + ["quest/m0/a.md", ["unlock the vault.", "a release."]], + ["quest/m0/b.md", ["pick a name.", "log in."]], + ["quest/m0/c.md", ["another release."]], + ]); + // Without its PC step, a.md waits only on an outside party, so it ranks after b.md. + expect(shown({ pc: false })).toEqual([ + ["quest/m0/b.md", ["pick a name."]], + ["quest/m0/a.md", ["a release."]], + ["quest/m0/c.md", ["another release."]], + ]); + expect(shown({ maintainer: true, pc: false })).toEqual([["quest/m0/b.md", ["pick a name."]]]); + expect(shown({ maintainer: true })).toEqual([ + ["quest/m0/a.md", ["unlock the vault."]], + ["quest/m0/b.md", ["pick a name.", "log in."]], + ]); +}); + test("check rejects an unknown host and an empty hosts section", () => { const docs = tree({ "a.md": "\n## Hosts\n\n- linux\n- macos - the camera.\n- freebsd\n", "b.md": "\n## Hosts\n" }); expect(check(docs, () => true).map((f) => `${f.path}:${f.line}: ${f.message}`)).toEqual([ @@ -45,9 +96,13 @@ test("check rejects an unknown host and an empty hosts section", () => { }); test("check rejects a wait without a party and an empty section", () => { - const docs = tree({ "a.md": "\n## Waiting\n\n- pick a name\n", "b.md": "\n## Waiting\n" }); + const docs = tree({ + "a.md": "\n## Waiting\n\n- pick a name\n- Maintainer (local): log in.\n", + "b.md": "\n## Waiting\n", + }); expect(check(docs, () => true).map((f) => `${f.path}:${f.line}: ${f.message}`)).toEqual([ - "quest/m0/a.md:9: '## Waiting' item must open with who acts, as 'Maintainer: ...' or ': ...'", + "quest/m0/a.md:9: '## Waiting' item must open with who acts, as 'Maintainer: ...', 'Maintainer (PC): ...' for a step only at their computer, or ': ...'", + "quest/m0/a.md:10: '## Waiting' item must open with who acts, as 'Maintainer: ...', 'Maintainer (PC): ...' for a step only at their computer, or ': ...'", "quest/m0/b.md:7: '## Waiting' is empty; remove the heading with its last entry", ]); }); @@ -68,8 +123,8 @@ test("lists the maintainer's waits first, then by milestone and impact", () => { dependents: 0, ready: true, waits: [ - { line: 9, party: "Maintainer", text: "pick a provider." }, - { line: 10, party: "Hetzner", text: "verify the account." }, + { line: 9, party: "Maintainer", pc: false, text: "pick a provider." }, + { line: 10, party: "Hetzner", pc: false, text: "verify the account." }, ], }, { @@ -77,7 +132,7 @@ test("lists the maintainer's waits first, then by milestone and impact", () => { pr: null, dependents: 1, ready: true, - waits: [{ line: 9, party: "moq-dev/moq", text: "a release." }], + waits: [{ line: 9, party: "moq-dev/moq", pc: false, text: "a release." }], }, ]); }); @@ -120,11 +175,11 @@ test("a draft's hand-back items are the maintainer's unless a Waiting item names "## Validation\n\n- Passes.\n\n## Waiting\n\n1. Pick foo or bar.\n", ), ).toEqual([ - { line: 5, party: "Codex", text: "out of quota until 15:00 UTC." }, - { line: 6, party: "Maintainer", text: "pick a name, either one." }, - { line: 8, party: "Maintainer", text: "approve the account." }, - { line: 9, party: "moq-dev/moq", text: "a release." }, - { line: 17, party: "Maintainer", text: "Pick foo or bar." }, + { line: 5, party: "Codex", pc: false, text: "out of quota until 15:00 UTC." }, + { line: 6, party: "Maintainer", pc: false, text: "pick a name, either one." }, + { line: 8, party: "Maintainer", pc: false, text: "approve the account." }, + { line: 9, party: "moq-dev/moq", pc: false, text: "a release." }, + { line: 17, party: "Maintainer", pc: false, text: "Pick foo or bar." }, ]); }); @@ -136,35 +191,35 @@ test("a draft's hand-back item keeps nested headings and the body's reference de '- Maintainer: approve.\n', ), ).toEqual([ - { line: 5, party: "Maintainer", text: "choose a provider. Options Hetzner or OVH." }, - { line: 10, party: "Maintainer", text: "approve the account." }, - { line: 11, party: "Codex", text: "out of quota." }, - { line: 12, party: "Maintainer", text: "approve." }, + { line: 5, party: "Maintainer", pc: false, text: "choose a provider. Options Hetzner or OVH." }, + { line: 10, party: "Maintainer", pc: false, text: "approve the account." }, + { line: 11, party: "Codex", pc: false, text: "out of quota." }, + { line: 12, party: "Maintainer", pc: false, text: "approve." }, ]); }); test("a draft's hand-back renders strikethrough and tables as GitHub does", () => { expect(handBackWaits("## Waiting\n\n- ~~Maintainer~~: pick.\n- Codex: ~~soon~~ later.\n")).toEqual([ - { line: 3, party: "Maintainer", text: "pick." }, - { line: 4, party: "Codex", text: "soon later." }, + { line: 3, party: "Maintainer", pc: false, text: "pick." }, + { line: 4, party: "Codex", pc: false, text: "soon later." }, ]); expect(handBackWaits("## Waiting\n\n| when | check |\n| --- | --- |\n| 15:00 | quota |\n")).toEqual([ - { line: 1, party: "Maintainer", text: "when check 15:00 quota" }, + { line: 1, party: "Maintainer", pc: false, text: "when check 15:00 quota" }, ]); }); test("a draft's hand-back without items is one maintainer item holding its prose", () => { expect(handBackWaits("Work.\r\n\r\nWaiting\r\n-------\r\n\r\nPick a name\r\nfor it.\r\n")).toEqual([ - { line: 3, party: "Maintainer", text: "Pick a name for it." }, + { line: 3, party: "Maintainer", pc: false, text: "Pick a name for it." }, ]); expect(handBackWaits("## Waiting\n\n
\nWhy\nPick one.\n
\n")).toEqual([ - { line: 1, party: "Maintainer", text: "the draft hands back without saying what it waits on" }, + { line: 1, party: "Maintainer", pc: false, text: "the draft hands back without saying what it waits on" }, ]); expect(handBackWaits("## Waiting\n\n
\nWhy\n
\n\nThen merge.\n")).toEqual([ - { line: 1, party: "Maintainer", text: "Then merge." }, + { line: 1, party: "Maintainer", pc: false, text: "Then merge." }, ]); expect(handBackWaits("## Waiting\n")).toEqual([ - { line: 1, party: "Maintainer", text: "the draft hands back without saying what it waits on" }, + { line: 1, party: "Maintainer", pc: false, text: "the draft hands back without saying what it waits on" }, ]); expect(handBackWaits("Work.\n\n```\n## Waiting\n\n- Maintainer: pick.\n```\n")).toEqual([]); }); @@ -175,13 +230,15 @@ test("drafts rank as the quest they carry, after quests on a tie, and last when { "c.md": "\n## Required\n\n- [B](/quest/m0/b.md)\n" }, ); const draft = (url: string, branch: string, body: string) => ({ url, branch, body }); - const found = waiting(docs, TODAY, [ - draft("https://example.com/pull/1", "quest-plan/x", "## Waiting\n\n- Maintainer: plan it.\n"), - draft("https://example.com/pull/2", "quest/m0/b", "## Waiting\n\n- Maintainer: pick b.\n"), - draft("https://example.com/pull/3", "quest/m0/a", "## Waiting\n\n- moq-dev/moq: a release.\n"), - draft("https://example.com/pull/4", "quest/m0/a", "Ready soon.\n"), - draft("https://example.com/pull/5", "quest/m9/gone", "## Waiting\n\n- Keep it?\n"), - ]); + const found = waiting(docs, TODAY, { + drafts: [ + draft("https://example.com/pull/1", "quest-plan/x", "## Waiting\n\n- Maintainer: plan it.\n"), + draft("https://example.com/pull/2", "quest/m0/b", "## Waiting\n\n- Maintainer: pick b.\n"), + draft("https://example.com/pull/3", "quest/m0/a", "## Waiting\n\n- moq-dev/moq: a release.\n"), + draft("https://example.com/pull/4", "quest/m0/a", "Ready soon.\n"), + draft("https://example.com/pull/5", "quest/m9/gone", "## Waiting\n\n- Keep it?\n"), + ], + }); expect(found.map((quest) => [quest.pr ?? quest.path, quest.path, quest.dependents, quest.ready])).toEqual([ ["https://example.com/pull/2", "quest/m0/b.md", 1, true], ["quest/m0/a.md", "quest/m0/a.md", 0, true], From 5ca819333bb8c420dd8def8cc44a4689ca3a0414 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 21 Nov 2026 23:34:41 -0800 Subject: [PATCH 3/4] Address review: wake on all checks, list PC blockers apart, document normalized party Co-Authored-By: Claude Opus 5.5 --- assets/skills/afk.md | 2 +- assets/skills/run.md | 2 +- src/cli/main.ts | 3 ++- 3 files changed, 4 insertions(+), 3 deletions(-) diff --git a/assets/skills/afk.md b/assets/skills/afk.md index a067b9003..2c81cd1d0 100644 --- a/assets/skills/afk.md +++ b/assets/skills/afk.md @@ -29,7 +29,7 @@ Unless the mode or argument allows it, defer as blockers what no review can undo - `/quest-plan` sessions, and actions only the user can take, such as granting access or providing a secret. Carry on each pick the user already made until it lands or needs them again. -When the work finishes, end with a final summary holding only the blockers, each linked, with its options and your recommendation, so a fresh session can act on it; the choices you took live in the PRs' bodies. +When the work finishes, end with a final summary holding only the blockers, each linked, with its options and your recommendation, so a fresh session can act on it; list the `Maintainer (PC):` steps, which need the user at a computer, apart from the rest. The choices you took live in the PRs' bodies. A message that adds to these instructions, such as a newly granted merge or more work, amends them, and afk continues. Any other message is the user's return: afk ends. Answer it, then resume the session's skill, or `/quest-run` on the blockers when it ran none, which asks the questions it deferred. diff --git a/assets/skills/run.md b/assets/skills/run.md index 813af4c6c..8659e5196 100644 --- a/assets/skills/run.md +++ b/assets/skills/run.md @@ -77,7 +77,7 @@ Make these edits in one draft PR on a `quest-run/` branch, run `quest chec ## Loop Each round, rerun `quest unblocked --unclaimed --json` and refresh the open PRs, since merges and released claims make more work ready. -When no agent is running and every question has been asked, block with `quest wait` on the queued PRs whose merge would make a quest ready, and on each PR ready for review whose required checks are still running and which a round would then pick or ask about; run a round once one lands, leaves the queue, or its checks finish. +When no agent is running and every question has been asked, block with `quest wait` on the queued PRs whose merge would make a quest ready, and on each PR ready for review whose checks are still running and which a round would then pick or ask about; run a round once one lands or leaves the queue, or its checks pass or fail. Wait on no other PR, such as a draft or a skipped one, and read none between rounds: list each PR left for a later round in the summary, with its pick. A usage or rate limit is waited out until its reset; it never ends the run. diff --git a/src/cli/main.ts b/src/cli/main.ts index 35a3eeea3..d1ab2c163 100644 --- a/src/cli/main.ts +++ b/src/cli/main.ts @@ -495,7 +495,8 @@ export function main(argv: string[], out: Output): number | Promise { "Prints one line per item: dependents, ready or blocked (whether Required entries or a future " + "Scheduled date remain), the quest's path or the draft's URL, and the item. --json prints an ordered array of {path, pr, dependents, " + "ready, waits: [{line, party, pc, text}]} objects, where pr is the draft's URL or null, path is the " + - "quest, the quest a draft carries, or null, and pc is whether the item opened Maintainer (PC):. " + + "quest, the quest a draft carries, or null; an item opened Maintainer (PC): has party Maintainer and pc " + + "true. " + "--maintainer keeps only the items the maintainer settles, and --no-pc drops the Maintainer (PC): ones, " + "for a session away from the maintainer's computers. " + "Invalid trees fail before printing. Outside conditions are never checked, nor whether another " + From 3c255ac8ef020f8314df330fa2fd9d118e390431 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 21 Nov 2026 23:43:23 -0800 Subject: [PATCH 4/4] Document afk modes in the README skills table and --no-pc ranking in waiting help Co-Authored-By: Claude Opus 5.5 --- README.md | 2 +- src/cli/main.ts | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index f75a84279..564aa984b 100644 --- a/README.md +++ b/README.md @@ -2470,7 +2470,7 @@ arrives with the guide sections and other skills it builds on, in one call: | `quest-review` | Review a PR's branch locally with a model other than its latest writer, then mark it ready for review. | | `quest-merge` | Queue a PR to land, running `quest-iterate` first when it needs work. | | `quest-run` | Orchestrate a project from one session: start ready quests, take PRs to merge, and settle what quests and drafts wait on you, in a loop until only your decisions remain, then plan the follow-ups no quest owns yet. Pass a filter such as `prs` to start no quests. | -| `quest-afk` | Keep a session such as `quest-run` going while you are away: it acts on its recommendations, defers merges, and walks you through the rest when you return. | +| `quest-afk` | Keep a session such as `quest-run` going while you are away: it acts on its recommendations, defers merges, and walks you through the rest when you return. `afk merge` also merges low- and medium-risk PRs it strongly recommends, and `afk soon` asks pending questions in one batch before you leave. | Use `/quest-plan` in Claude Code or `$quest-plan` in Codex. Skills coordinate within your agent session. A started quest stops at a pull request; merging is diff --git a/src/cli/main.ts b/src/cli/main.ts index d1ab2c163..642b7c153 100644 --- a/src/cli/main.ts +++ b/src/cli/main.ts @@ -498,7 +498,7 @@ export function main(argv: string[], out: Output): number | Promise { "quest, the quest a draft carries, or null; an item opened Maintainer (PC): has party Maintainer and pc " + "true. " + "--maintainer keeps only the items the maintainer settles, and --no-pc drops the Maintainer (PC): ones, " + - "for a session away from the maintainer's computers. " + + "for a session away from the maintainer's computers; both filter before ranking, so order follows the items kept. " + "Invalid trees fail before printing. Outside conditions are never checked, nor whether another " + "session holds a draft.\n\n" + "Drafts are read from the open PRs of the remote's upstream, found as for quest unblocked " +