Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -581,6 +581,7 @@ comes last, and a missing value prints as `-`:
| `signal` | `finding` or `decision`, its URL, who posted it, and its text, for each [signal](#signals-that-hold-a-head) holding the head. |
| `hold` | Label, acquisition token, acquisition time, verified GitHub event API URL, and age; `hold -` when no label holds it. Unknown acquisition facts print as `-` and `unknown age`. |
| `starter-hold` | A draft its starter owns: last activity time, PR URL, and `last active` age. Last activity is not when ownership began. |
| `duplicate` | For an open PR, each quest it adds that another open PR also adds, at the same path or under the same title compared without its size, case, or spacing: the quest's path, the other PR's URL, and the other quest's path. A follow-up another PR already owns is dropped, or moved into that PR's quest, before a pick asks about it. |

The node ID is what GraphQL's `addPullRequestReviewThreadReply` and
`resolveReviewThread` take. Neutral and skipped checks pass. Only each check's
Expand All @@ -602,7 +603,7 @@ requirement names one, its app, as GitHub and `quest land` do, and leaves out
same facts as one object with the fields `url`, `state`, `draft`, `head`,
`mergeable`, `mergeState`, `reviewDecision`, `autoMerge`, `mergeQueue`,
`landingStopped`, `checks` (`state`, `passed`, `failing`, `pending`), `reviews`, `checkpoints` (`reviewer`, `round`, `url`), `reactions`,
`threads`, `signals` (`kind`, `url`, `author`, `text`), `holds` (`label`, `token`, `takenAt`, `age`, `eventUrl`), and `starterHold` (`lastActive`, `age`, `url`, or null). Ownership uses the state commands' shared reader without changing labels, and event links match the opaque acquisition token against GitHub's event listing. Long lists are paged; reactions are the newest 100 per PR or review,
`threads`, `signals` (`kind`, `url`, `author`, `text`), `holds` (`label`, `token`, `takenAt`, `age`, `eventUrl`), `starterHold` (`lastActive`, `age`, `url`, or null), and `duplicates` (`path`, `url`, `other`). Ownership uses the state commands' shared reader without changing labels, and event links match the opaque acquisition token against GitHub's event listing. Long lists are paged; reactions are the newest 100 per PR or review,
as in `quest wait`. Any PR state exits 0, invalid arguments exit 2, and other
failures exit 1.

Expand Down
4 changes: 3 additions & 1 deletion assets/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -107,12 +107,14 @@ End every quest skill with a final summary in sections, such as the PRs and thei
## Creation

Quests are created in PRs and reviewed.
Search the tree and git history before making a new quest.
Before making a new quest, search the tree, git history, and the quest files each open PR adds or changes, which `gh pr list --limit 1000 --json number,url,files` lists, up to 100 files a PR (`gh api --paginate 'repos/{owner}/{repo}/pulls/<number>/files'` lists the rest); a search of PR titles and bodies misses a PR that never names the subject.

Split independently completable work into separate quests.
Group related quests in an epic; its README holds the work no child owns.

Work found along the way that is worth a quest is a follow-up: add it to the PR that found it, as a new quest placed and sized by these rules and the repository's, or an edit to the quest that owns the work; never as an agent-session task or a GitHub issue.
When another open PR's quest owns the work, add nothing: name that PR and quest in the PR body instead.
`quest status <pr>` prints a `duplicate` line for each quest the PR adds that another open PR also adds, by path or title; resolve each before marking the PR ready or picking it, unless both PRs need the quest.
Drop one you would call optional or worth doing only if it matters.
Answer each of its decisions you can with your recommendation in its Plan, and list each you cannot as a `Maintainer:` decision item under its `Waiting`.
The PR body's `## Follow-ups` section links each one with its open decisions, which neither keep the PR a draft nor stop its pick.
Expand Down
2 changes: 1 addition & 1 deletion assets/skills/review.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ A reviewer out of quota or logged out is an outage, not a skip: stop reviewing,
Its `## Waiting` item names the reviewer, its error, and the check, such as `Codex: out of quota until 2026-11-03 15:00 UTC; check that quest review runs`, with the reset time `quest review` prints when it exits 3 on a usage limit; a logged-out reviewer waits on `Maintainer:`, with the login command `quest review` prints.
Once the reset passes or the login is restored, the item has cleared: whoever finds it runs `/quest-review` on the PR.

Push, then mark the PR ready for review: with `quest ready <pr> <token>`, which also drops its `## Waiting` section, or with `gh pr ready <pr>` for a draft you reviewed without a hold.
Push, resolve each `duplicate` line `quest status <pr>` then prints as the guide's Creation describes, then mark the PR ready for review: with `quest ready <pr> <token>`, which also drops its `## Waiting` section, or with `gh pr ready <pr>` for a draft you reviewed without a hold.

Summarize the review, with its last round's score and rationale, and CI from `quest status <pr>`.
Name any decisions the review raised without answering them, then ask the user with your recommended action:
Expand Down
14 changes: 0 additions & 14 deletions quest/m0/follow-up-duplicates.md

This file was deleted.

6 changes: 4 additions & 2 deletions src/cli/main.ts
Original file line number Diff line number Diff line change
Expand Up @@ -654,8 +654,10 @@ export function main(argv: string[], out: Output): number | Promise<number> {
"reviewer that approves or requests changes, its round, and its review, when that review is of the " +
"head, while its latest verdict on the head is neither an approval nor a dismissal, and ends its third, sixth, ... round (one commit it reviewed), as " +
"/quest-review's design checkpoint; a reacted:<content> line per " +
"reaction on the PR or a review; a thread line per unresolved review thread, led by its node ID; and a " +
"signal line per finding or decision that holds the head from landing (see the README). " +
"reaction on the PR or a review; a thread line per unresolved review thread, led by its node ID; a " +
"signal line per finding or decision that holds the head from landing (see the README); and last, " +
"for an open PR, a duplicate line per quest it adds that another open PR also adds, at the same path or under the same title " +
"compared without its size, case, or spacing, giving the quest's path, the other PR's URL, and the other quest's path last. " +
"A missing value prints as -. --json prints the same facts as one deterministic object.\n\n" +
"Uses GH_TOKEN, GITHUB_TOKEN, or gh auth token. " +
FORGE_READS.replace("these reads", "the read") +
Expand Down
1 change: 1 addition & 0 deletions src/cli/status.ts
Original file line number Diff line number Diff line change
Expand Up @@ -53,5 +53,6 @@ export function statusLines(status: Status): string[] {
`starter-hold ${status.starterHold.lastActive} ${status.starterHold.url} last active ${status.starterHold.age}`,
]
: []),
...status.duplicates.map((d) => `duplicate ${d.path} ${d.url} ${d.other}`),
];
}
13 changes: 13 additions & 0 deletions src/core/forge.ts
Original file line number Diff line number Diff line change
Expand Up @@ -99,6 +99,16 @@ export interface StarterHold {
url: string;
}

/** A quest the PR adds that another open PR also adds, at the same path or under the same title. */
export interface Duplicate {
/** The quest file the PR adds. */
path: string;
/** The other open PR. */
url: string;
/** The quest file the other PR adds: `path` itself, or another path with the same title. */
other: string;
}

/** Everything `quest status` reports about a PR. */
export interface Status {
url: string;
Expand Down Expand Up @@ -136,6 +146,8 @@ export interface Status {
signals: Signal[];
holds: HoldFact[];
starterHold: StarterHold | null;
/** Quests an open PR adds that another open PR also adds; none for a PR no longer open. */
duplicates: Duplicate[];
}

/** An open PR, from any head repository, as the claim checks read it. */
Expand Down Expand Up @@ -422,6 +434,7 @@ const status = shape<Status>({
}),
),
starterHold: nullable(shape<StarterHold>({ lastActive: time, age: string, url: string })),
duplicates: list(shape<Duplicate>({ path: string, url: string, other: string })),
});

const openPull = shape<OpenPull>({
Expand Down
1 change: 1 addition & 0 deletions src/core/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -128,6 +128,7 @@ export {
type Claim,
type ClaimSource,
type ClaimSources,
type Duplicate,
FORGE_CALLS,
type Forge,
type ForgeCall,
Expand Down
122 changes: 122 additions & 0 deletions src/github/duplicates.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,122 @@
// Quests a PR adds that another open PR also adds, so a follow-up some other PR already owns is
// caught before a pick round asks about it.
import { type Duplicate, type PullRequest, isQuest, parse } from "../core";
import { type GitHub, array, object, repositoryPath, string } from "./client";

/** An open PR's added quest files, each with its title, or null when it has none. */
export interface Added {
number: number;
url: string;
quests: { path: string; title: string | null }[];
}

const OPEN = `query OpenQuests($owner: String!, $repo: String!, $after: String) {
repository(owner: $owner, name: $repo) {
pullRequests(states: OPEN, first: 50, after: $after) {
pageInfo { hasNextPage endCursor }
nodes { number url headRefOid files(first: 100) { pageInfo { hasNextPage } nodes { path changeType } } }
}
}
}`;

/** Blobs read per title query. */
const BATCH = 100;

/** A file under a `quest/` directory, at the root or in a subdirectory holding a tree, that is a quest document. */
const questFile = (path: string) => /(?:^|\/)quest\/./.test(path) && isQuest(path);

/** A title compared without its size, case, or spacing, which agents vary for the same work. */
export function titleKey(title: string): string {
return title
.replace(/^\[[^\]]*\]\s*/, "")
.replace(/\s+/g, " ")
.trim()
.toLowerCase();
}

/** Each quest `self` adds that another of `pulls` adds at the same path or with the same title. */
export function duplicates(self: number, pulls: Added[]): Duplicate[] {
const own = pulls.find((pull) => pull.number === self);
if (own === undefined) return [];
const found: Duplicate[] = [];
for (const quest of own.quests) {
const key = quest.title === null ? null : titleKey(quest.title);
for (const pull of pulls) {
if (pull.number === self) continue;
for (const other of pull.quests)
if (
other.path === quest.path ||
(key !== "" && key !== null && other.title !== null && titleKey(other.title) === key)
)
found.push({ path: quest.path, url: pull.url, other: other.path });
}
}
return found;
}

/**
* The quests `pr` adds that another open PR in its repository also adds. Reads every open PR's added
* files, then the titles of their quests at each PR's head, only when `pr` adds a quest.
*/
export async function duplicateQuests(github: GitHub, pr: PullRequest): Promise<Duplicate[]> {
const pulls: { number: number; url: string; head: string; paths: string[] }[] = [];
for (let after: string | null = null, more = true; more;) {
const data = await github.graphql(OPEN, { owner: pr.owner, repo: pr.repo, after });
if (data.repository === null)
throw new Error(`cannot read ${pr.owner}/${pr.repo}; check the repository and token`);
const list = object(object(data.repository).pullRequests);
for (const node of array(list.nodes)) {
const files = object(node.files);
const number = Number(node.number);
// GraphQL lists at most 100 files; REST lists up to 3,000, enough for any PR adding quests.
const added =
object(files.pageInfo).hasNextPage === true
? (await github.all(`${repositoryPath(pr)}/pulls/${number}/files?per_page=100`))
.filter((row) => row.status === "added")
.map((row) => string(row.filename))
: array(files.nodes)
.filter((file) => file.changeType === "ADDED")
.map((file) => string(file.path));
pulls.push({
number,
url: string(node.url),
head: string(node.headRefOid),
paths: added.filter(questFile),
});
}
const info = object(list.pageInfo);
more = info.hasNextPage === true;
after = more ? string(info.endCursor) : null;
}
const own = pulls.find((pull) => pull.number === pr.number);
if (own === undefined || own.paths.length === 0) return [];
const blobs = pulls.flatMap((pull) => pull.paths.map((path) => `${pull.head}:${path}`));
const titles = new Map<string, string | null>();
for (let start = 0; start < blobs.length; start += BATCH) {
const batch = blobs.slice(start, start + BATCH);
const query =
`query($owner: String!, $repo: String!, ${batch.map((_, i) => `$e${i}: String!`).join(", ")}) { repository(owner: $owner, name: $repo) { ` +
batch.map((_, i) => `f${i}: object(expression: $e${i}) { ... on Blob { text } }`).join(" ") +
" } }";
const data = await github.graphql(query, {
owner: pr.owner,
repo: pr.repo,
...Object.fromEntries(batch.map((blob, i) => [`e${i}`, blob])),
});
const repository = object(data.repository);
batch.forEach((blob, i) => {
const node = repository[`f${i}`];
const text = node === null || node === undefined ? null : object(node).text;
const path = blob.slice(blob.indexOf(":") + 1);
titles.set(blob, typeof text === "string" ? (parse(path, text).title?.text ?? null) : null);
});
}
return duplicates(
pr.number,
pulls.map((pull) => ({
number: pull.number,
url: pull.url,
quests: pull.paths.map((path) => ({ path, title: titles.get(`${pull.head}:${path}`) ?? null })),
})),
);
}
5 changes: 4 additions & 1 deletion src/github/status.ts
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@ import {
} from "../core";
import { readHoldStatus } from "./hold";
import { readSignals } from "./signals";
import { duplicateQuests } from "./duplicates";

/**
* One query covers the PR; each connection pages by its own cursor, and a
Expand Down Expand Up @@ -168,7 +169,8 @@ export async function pullRequestStatus(pr: PullRequest, deps: GitHubDependencie
if (signaled.head !== first!.headRefOid)
throw new Error("the PR head changed while reading its signals; rerun quest status");
status.signals = signaled.signals;
return { ...status, holds: ownership.holds, starterHold: ownership.starter };
const duplicates = first!.state === "OPEN" ? await duplicateQuests(github, pr) : [];
return { ...status, holds: ownership.holds, starterHold: ownership.starter, duplicates };
}

/** The risk the PR body records, judged against the head as {@link Status.risk} describes. */
Expand Down Expand Up @@ -467,6 +469,7 @@ function summarize(
signals: [],
holds: [],
starterHold: null,
duplicates: [],
};
}

Expand Down
21 changes: 21 additions & 0 deletions test/status-fakes.ts
Original file line number Diff line number Diff line change
Expand Up @@ -125,6 +125,8 @@ export function setup(
noBase?: boolean;
/** The head's workflow runs, as `GET /actions/runs` lists them. */
runs?: Node[];
/** The open PRs as the duplicate read lists them, and each `<head>:<path>` blob's text. */
open?: { pulls: Node[]; blobs?: Record<string, string>; files?: Record<number, Node[]> };
} = {},
) {
const queries: Record<string, unknown>[] = [];
Expand Down Expand Up @@ -160,6 +162,8 @@ export function setup(
: Response.json({ protection: { enabled: false } });
if (path.pathname === "/repos/example/project/rules/branches/main")
return Response.json(options.rules ?? []);
const changed = /^\/repos\/example\/project\/pulls\/(\d+)\/files$/.exec(path.pathname);
if (changed) return Response.json(options.open?.files?.[Number(changed[1])] ?? []);
if (path.pathname === "/repos/example/project/actions/runs") {
if (!options.runs) throw new Error("unexpected workflow run request");
return Response.json({ total_count: options.runs.length, workflow_runs: options.runs });
Expand All @@ -181,6 +185,23 @@ export function setup(
return Response.json(page.rows, { headers: page.next ? { Link: `<${page.next}>; rel="next"` } : {} });
}
const request = JSON.parse(String(init?.body));
if (request.query.includes("query OpenQuests(")) {
const nodes = options.open?.pulls ?? [];
return Response.json({
data: {
repository: { pullRequests: { pageInfo: { hasNextPage: false, endCursor: null }, nodes } },
},
});
}
if (request.query.includes("object(expression:")) {
const repository: Node = {};
for (const [key, value] of Object.entries(request.variables as Record<string, string>))
if (key.startsWith("e")) {
const text = options.open?.blobs?.[value];
repository[`f${key.slice(1)}`] = text === undefined ? null : { text };
}
return Response.json({ data: { repository } });
}
if (request.query.includes("p1: pullRequest(number: 1)")) {
if (!last) throw new Error("signals read before PR state");
const head = last.data.repository.pullRequest.headRefOid;
Expand Down
Loading
Loading