From cc88f3d67b8239544b5de01fd23a92ead0cb17c7 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 5 Nov 2026 14:33:33 -0800 Subject: [PATCH 1/6] chore(quest): claim quest/m0/token-waste/child-lists.md Quest-Claim: 548a99dcabdca6a5 From a5eaf3308d70385a0eaa6be365675d1944d3701c Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 5 Nov 2026 14:54:26 -0800 Subject: [PATCH 2/6] feat!: epics list no children; a directory is the epic's child list An epic's children are the quests in its directory, in path order, and an epic README's `Required` lists only what blocks it. Finishing a quest deletes its file and edits no README, so sibling PRs stop conflicting on milestone and epic READMEs. `quest check` flags an epic's `Required` link to a quest it holds and a quest in a directory without a README; `quest check --fix`, `quest rm`, and the land daemon's base merges strip those links, which migrates a tree whose epics still list their children. Path order replaces list order: a directory's README first, then names, with numbers by value so `m10` follows `m9`. Co-Authored-By: Claude Opus 5.5 --- README.md | 32 +++-- assets/AGENTS.md | 18 +-- assets/land-fix.md | 5 +- assets/skills/audit.md | 6 +- assets/skills/plan.md | 2 +- assets/skills/recurring.md | 6 +- assets/skills/spawn.md | 2 +- cloudflare/dev/seed.ts | 27 +--- cloudflare/src/board/model.ts | 53 +++---- cloudflare/src/board/pages.tsx | 9 +- cloudflare/src/home.tsx | 4 +- cloudflare/src/map.tsx | 13 +- cloudflare/test/board.test.ts | 14 +- cloudflare/test/core.test.ts | 7 +- cloudflare/test/jobs.test.ts | 14 +- cloudflare/test/links.test.ts | 6 +- cloudflare/test/map.test.ts | 24 ++-- cloudflare/test/project-fixtures.ts | 5 +- cloudflare/test/projects.test.ts | 14 +- examples/export/quest/README.md | 4 - examples/export/quest/m0/README.md | 5 - quest/README.md | 6 - quest/m0/README.md | 21 +-- quest/m0/kix/README.md | 8 -- quest/m0/kix/sandbox/README.md | 5 - quest/m0/model-check.md | 3 +- quest/m0/model-routing/README.md | 6 - quest/m0/queue-watcher/README.md | 8 -- quest/m0/token-waste/README.md | 11 -- quest/m0/token-waste/base-merges.md | 5 +- quest/m0/token-waste/child-lists.md | 44 ------ quest/m0/user-dev-shell/README.md | 5 - quest/m1/README.md | 13 -- quest/m1/kix/README.md | 5 - quest/m1/kix/sandbox/README.md | 5 - quest/m1/model-check.md | 6 +- quest/m1/theme/README.md | 7 +- quest/m2/README.md | 14 -- quest/m2/automation/README.md | 6 - quest/m2/cloud/README.md | 7 - scripts/lifecycle-check.mjs | 12 +- src/cli/main.ts | 24 ++-- src/cli/move.ts | 45 +++--- src/core/doc.ts | 49 ++++--- src/core/edit.ts | 24 +++- src/core/index.ts | 2 + src/core/path.ts | 17 ++- src/core/ready.ts | 64 ++++----- src/core/rules.ts | 75 +++++----- src/core/unblocked.ts | 22 +-- test/fixture.ts | 13 -- test/land-watch.test.ts | 16 ++- test/land.test.ts | 64 +++++---- test/landed.test.ts | 9 +- test/links.test.ts | 5 +- test/move.test.ts | 128 ++++++++++------- test/theme.test.ts | 6 +- test/tree.test.ts | 214 +++++++++++++--------------- test/unblocked.test.ts | 46 +++--- test/waiting.test.ts | 25 +--- 60 files changed, 536 insertions(+), 779 deletions(-) delete mode 100644 quest/m0/token-waste/child-lists.md diff --git a/README.md b/README.md index e417c563..849a944b 100644 --- a/README.md +++ b/README.md @@ -42,21 +42,24 @@ That file sits in your quest log, a tree under `quest/`: quest/ README.md # The roadmap m0/ - README.md # First milestone, in priority order + README.md # The first milestone export.md # Ready download.md # Required: export.md ``` -Folders are **epics**. A README's `Required` lists its children in -priority order, beside any other dependencies. The README is the epic's +Folders are **epics**, and the quests in a folder are its children; its +README lists only what blocks it, never its children. The README is the epic's own quest, and it becomes ready once its children have merged. The top folders (`m0`, `m1`, ...) are **milestones** that give the work a delivery horizon. +Finishing a quest deletes its file and edits no README, so PRs that finish +sibling quests do not conflict. When a quest is complete, its PR removes the plan and the links that depended on it, so the quests that required it can become ready. A PR that leaves work rewrites the plan to what remains. Milestones are never -deleted, so a PR that finishes one (its README has no `Required` left) removes -the links to that milestone too; `quest check` flags any it misses. The +deleted, so a PR that finishes one (its folder holds no other quest and its +README has no `Required` left) removes the links to that milestone too; +`quest check` flags any it misses. The finished plan stays in Git history, beside the code that completed it. Work is taken through a live runner lock or an open change on the forge. @@ -119,7 +122,8 @@ nonzero exit means the command failed. ## Prioritize ready work `quest unblocked` ranks ready quests by milestone priority, descending number -of distinct transitive dependents, then existing tree order. Counts include +of distinct transitive dependents, then path order, which compares numbers by +value so `m10` follows `m9`. Counts include later milestones without moving their candidates ahead of earlier milestones. Structural root, milestone, and epic membership does not add to the count; real dependencies on an epic still reach its remaining work. Other prerequisites @@ -280,11 +284,12 @@ quest rm -r quest/m1/drain under a moved epic. `rm` drops each `Required`, `Related`, or `Closes` entry that links to what it deleted, and the heading if that was the last entry. It also drops every `Required` link to a finished milestone, including one it -just finished, but keeps the root's listing of the milestone. +just finished, and every epic's `Required` link to a quest in its own folder. Both stage the change, print one line per file (`R from -> to`, `D path`, or `M path`), and report on stderr any other mention of the path, such as prose or files outside `quest/`, without editing it. They run `quest check` on the -result and exit 1 if it fails, for example when a quest moved out of its epic. +result and exit 1 if it fails, for example when a quest moved into a folder +with no README. An epic is its directory or README; removing one that holds other quests needs `-r`. The root and milestones are never moved or removed. `mv` refuses a @@ -295,8 +300,8 @@ Neither command touches branches or PRs. ## Merge quest lists -Concurrent PRs edit the same link lists: the base branch deletes finished -quests' lines while a branch inserts a new quest beside them. `quest init` +Concurrent PRs can edit the same link list: the base branch deletes a finished +blocker's line while a branch adds another blocker beside it. `quest init` routes `quest/**` through a merge driver in `.gitattributes` and registers it in the clone's git config, so a local `git merge` resolves those conflicts. @@ -326,7 +331,10 @@ A clean merge can still leave this branch's list links to quests the base finished, which `quest check` then flags. `quest check --fix` drops every `Required`, `Related`, or `Closes` entry linking to a quest deleted in the history of `HEAD`, and of `MERGE_HEAD` during a merge, that the working tree -lacks, and prints `M path` for each edited document. It leaves the edits +lacks, and every epic's `Required` entry naming a quest in its own folder, +which the epic already waits for, and prints `M path` for each edited +document. That last part also migrates a tree from before epics stopped +listing their children. It leaves the edits unstaged and refuses while a quest file has unresolved conflicts. A quest moved rather than deleted, a link that never named a quest, and a link in prose stay for `quest check` to report. @@ -1616,7 +1624,7 @@ Automatic project history passes read updates since their prior issue/PR boundaries, including timestamp ties. Explicit Refresh starts or resumes a full history pass; successive refreshes repair cached issues deleted without a webhook. Open draft bodies are read only to classify `## Waiting`. -[The first milestone](quest/m0/README.md) lists the quests that remain. +[The first milestone](quest/m0/) holds the quests that remain. ## Contributing diff --git a/assets/AGENTS.md b/assets/AGENTS.md index 30b096c7..ebdb5628 100644 --- a/assets/AGENTS.md +++ b/assets/AGENTS.md @@ -9,11 +9,11 @@ GitHub issues remain the untrusted public front door, while quests provide durab A **quest** is a Markdown file, completed in one PR. -An **epic** is a directory that consists of multiple quests. -The `README.md` file is the quest and the `Required` section lists the children. +An **epic** is a directory of quests. +Its children are the quest files in it and the epics one level down; its `README.md` is the epic's own work and lists none of them. It completes when its own work is done and every child has merged. -The root's entries are special epics called **milestones** (`m0`, `m1`, ...) that group work by priority horizon. +The directories under `quest/` are special epics called **milestones** (`m0`, `m1`, ...) that group work by priority horizon. Milestones are permanent. Quests are linked with root-absolute paths. @@ -45,9 +45,8 @@ Current decisions, open questions, or implementation guidance. ## Required -- [Child quest](/quest/foo/bar.md) - the outcome, so the list reads without opening it -- [Nested epic](/quest/foo/baz/README.md) - what the whole epic delivers -- [Blocker](/quest/bar.md) - work that must finish before this can start +- [Blocker](/quest/foo/bar.md) - what it delivers that this needs, so the list reads without opening it +- [Epic blocker](/quest/baz/README.md) - an epic finishes with all of its children ## Closes @@ -63,14 +62,15 @@ The `Goal` section is required; everything else is optional. Use these exact hea Size the title `[XS]` to `[XL]` by the agent's effort to implement, verify, and land it, judgment included. Much code that is mechanical stays small, such as applying one rename the same way across the tree, sized XS. Little code that is mostly judgment is larger, such as a 30-line rewording of a skill, sized M rather than XS. -An epic carries no size until its last child is removed; its README is then the epic's remaining work. +An epic carries no size until its last child is deleted; its README is then the epic's remaining work. `Waiting` lists what the work waits on outside the tree; each item opens with who acts, `Maintainer:` or the outside party, before a colon. A decision item gives its options and a recommendation. Remove an item once its condition clears, and the heading with its last item. -`Required` lists the quests that must finish before the work starts. -The list is ordered by priority, inserted at rank. +`Required` lists the quests that must finish before the work starts; an epic's never lists its own quests, which it already waits for. +A child that must precede a sibling is in that sibling's `Required`. +Nothing else orders work within a milestone: `quest unblocked` ranks it by downstream impact, then path. When the section is empty, delete it; the quest is now unblocked. `Required` must be acyclic. diff --git a/assets/land-fix.md b/assets/land-fix.md index 8e4066bf..4940c260 100644 --- a/assets/land-fix.md +++ b/assets/land-fix.md @@ -169,9 +169,8 @@ commit on it only - that follow-up quest, `quest/m0/flaky/.md`, with `` the test's name in lowercase kebab-case, whose Goal says to fix the test or delete it and links each listed job and this failure's, which the failure log names; -- its link in the `Required` list of `quest/m0/flaky/README.md`, the epic - holding one quest per disabled test, created with a link in - `quest/m0/README.md`'s `Required` if it is missing. +- `quest/m0/flaky/README.md`, the epic holding one quest per disabled test, + if it is missing. Follow the repository's quest format, and run `quest check` when the repository has it. A disabled test that is another quest's acceptance test diff --git a/assets/skills/audit.md b/assets/skills/audit.md index 3567c40d..4e946d37 100644 --- a/assets/skills/audit.md +++ b/assets/skills/audit.md @@ -4,18 +4,18 @@ description: Audit and fix outstanding quests for disagreements, conflicts, misa Before you begin, run `quest guide` and `quest skill plan`, and read their output completely. -The goal is a quest tree that agrees with itself and the code, ordered by priority. +The goal is a quest tree that agrees with itself and the code, with each quest in the milestone its priority calls for. The scope is every outstanding quest; the argument (if provided) filters it to specific quests or epics. Look for: - Disagreements: quests whose goals or plans contradict each other, the code, or the repository's docs. - Conflicts: quests that would change the same code or interface incompatibly, or that must land in order without a `Required` link. -- Misaligned priorities: a quest ranked or placed in a milestone ahead of work it depends on, or behind work it blocks. +- Misaligned priorities: a quest placed in a milestone ahead of work it depends on, or behind work it blocks. - Stale plans: work already done, blockers that have cleared, or references to code that no longer exists. - Obsolete quests: a problem that is no longer real, or a plan a later change or decision has made the wrong solution. Split the reading across parallel sub-agents, each given a slice of the scope and returning its findings with evidence (a path, line, or commit). -Apply factual corrections and changes the user has already decided. Moving a quest between milestones or changing its rank is always the user's decision, never a factual correction. Use `/quest-plan` only for unresolved scope, priority, API, or other consequential choices; recommendations are not decisions. Once those choices are settled, apply them without another approval round. +Apply factual corrections and changes the user has already decided. Moving a quest between milestones is always the user's decision, never a factual correction. Use `/quest-plan` only for unresolved scope, priority, API, or other consequential choices; recommendations are not decisions. Once those choices are settled, apply them without another approval round. Move and delete quests with `quest mv` and `quest rm`, which update the links to them; edit any mentions they report, run `quest check`, and follow the repository's PR workflow within the user's authorized scope. Report the changes with their evidence and any decisions still open. An explicit read-only audit request leaves the tree unchanged. diff --git a/assets/skills/plan.md b/assets/skills/plan.md index 7b9c994b..43d36f26 100644 --- a/assets/skills/plan.md +++ b/assets/skills/plan.md @@ -28,7 +28,7 @@ Once complete, create, update, or delete the relevant quests and epics. Record each settled decision and its reason in the quest's Plan, so later sessions don't ask it again, and the decision prompts in the PR. A fix quest's Plan names the PR that caused the problem when it is known, so its implementer lists it under `## Caused by` without searching again. When the PR deletes the quest, record its decisions in the PR body's `## Decisions` section instead, since the deletion takes the Plan with it. -New work joins the milestone the user picked, at its rank; an epic groups related quests, and its README holds the work no child owns (the end-to-end test, the docs page). +New work joins the milestone the user picked, in its directory or an epic's there; an epic groups related quests, and its README holds the work no child owns (the end-to-end test, the docs page). When done, commit, open the PR as a draft, and run `/quest-review` on it, which reviews the branch, records the `## Review` section, and marks the PR ready. Quests planned as follow-ups of an open PR may be committed to that PR instead, whose next push is reviewed as `quest context`'s Reviews section describes. diff --git a/assets/skills/recurring.md b/assets/skills/recurring.md index 9552f5e9..00e99b0a 100644 --- a/assets/skills/recurring.md +++ b/assets/skills/recurring.md @@ -7,14 +7,14 @@ Before you begin, run `quest guide` and `quest skill plan`, and read their outpu Run the plan interview for a quest that recurs: the PR that finishes one run creates the next. The argument (if provided) is the work to repeat, or an existing quest to make recurring. -Agents working the quest never load this skill, so its Plan says, in its own words, where the next run goes, what gates it, and that it's linked from its parent's `Required`. +Agents working the quest never load this skill, so its Plan says, in its own words, where the next run goes and what gates it. The next run keeps the Goal and recurrence, and its Plan carries forward what this run learned (baselines, results, what to check first). Also settle in the interview: - Where the next run goes. If milestones only grow, it's the same path in the next milestone (`m1/perf/audit.md` to `m2/perf/audit.md`), created with any missing milestone or epic. If they shift up after a release, it's wherever the next run belongs after the shift. -- What gates it. Rank doesn't delay a quest: one with no `Required` is ready at once. Gate it on another recurring quest (such as a release cut) or a condition quest. A quest can't require its own milestone, so to run at the end of mN, the gate requires mN and the next run requires the gate. -- What each run delivers, where it ranks, and whether anything ends the recurrence. +- What gates it. Placement doesn't delay a quest: one with no `Required` is ready at once. Gate it on another recurring quest (such as a release cut) or a condition quest. A quest can't require its own milestone, so to run at the end of mN, the gate requires mN and the next run requires the gate. +- What each run delivers, and whether anything ends the recurrence. A recurring gate's Plan also says to remove its path from every `Required` before re-creating it, or its dependents never clear. Findings that need their own work are follow-ups for `/quest-plan`. diff --git a/assets/skills/spawn.md b/assets/skills/spawn.md index 366da4bd..eefdc8dd 100644 --- a/assets/skills/spawn.md +++ b/assets/skills/spawn.md @@ -6,7 +6,7 @@ Before you begin, run `quest guide` and read its output completely. Your goal is to execute many quests in parallel. The scope consists of all ready quests that are not claimed. -Run `quest unblocked --unclaimed --json` for unclaimed ready candidates in milestone priority, descending downstream impact, then tree order. +Run `quest unblocked --unclaimed --json` for unclaimed ready candidates in milestone priority, descending downstream impact, then path order. The count is distinct transitive dependents; other prerequisites may still remain. Use that order when dispatching. As each agent reports, rerun `quest unblocked --unclaimed --json`, which reads the upstream tree afresh, and start the newly ready quests you would recommend, within the harness's agent limit: merges elsewhere and released claims make more work ready while the spawn runs. diff --git a/cloudflare/dev/seed.ts b/cloudflare/dev/seed.ts index a91c3a3c..a3fdf8de 100644 --- a/cloudflare/dev/seed.ts +++ b/cloudflare/dev/seed.ts @@ -34,21 +34,11 @@ export function world(): World { { path: "flake.nix", content: "{ outputs = _: { }; }\n" }, { path: "quest/README.md", - content: quest("Quests", "Plan the rocket app.", [ - "- [M0: Beta](/quest/m0/README.md) - the first public beta", - "- [M1: Later](/quest/m1/README.md) - after the beta", - ]), + content: quest("Quests", "Plan the rocket app."), }, { path: "quest/m0/README.md", - content: quest("Beta", "Ship the first public beta.", [ - "- [Landing page](/quest/m0/landing.md) - explain the app", - "- [Passkey sign-in](/quest/m0/sign-in.md) - sign in without a password", - "- [Getting started](/quest/m0/docs.md) - a first-run guide", - "- [Crash telemetry](/quest/m0/telemetry.md) - learn about crashes", - "- [ZIP export](/quest/m0/export.md) - take your data with you", - "- [ZIP import](/quest/m0/import.md) - bring your data back", - ]), + content: quest("Beta", "Ship the first public beta."), }, { path: "quest/m0/import.md", content: quest("[S] Import a project from a ZIP archive", "Restore it.") }, { path: "quest/m0/landing.md", content: quest("[S] Build the landing page", "Explain the app.") }, @@ -63,12 +53,7 @@ export function world(): World { { path: "quest/m0/export.md", content: quest("[S] Export a project as a ZIP archive", "Take your data.") }, { path: "quest/m1/README.md", - content: quest("Later", "Work after the beta.", [ - "- [Offline mode](/quest/m1/offline.md) - keep working without a network", - "- [Themes](/quest/m1/themes.md) - custom colors", - "- [Search](/quest/m1/search.md) - find anything", - "- [Fonts](/quest/m1/fonts.md) - choose the editor font", - ]), + content: quest("Later", "Work after the beta."), }, { path: "quest/m1/fonts.md", content: quest("[S] Choose the editor font", "Read comfortably.") }, { path: "quest/m1/search.md", content: quest("[S] Search across projects", "Find anything.") }, @@ -201,13 +186,11 @@ export function world(): World { files: [ { path: "quest/README.md", - content: quest("Quests", "Retire the old site.", ["- [M0: Retire](/quest/m0/README.md) - retire it"]), + content: quest("Quests", "Retire the old site."), }, { path: "quest/m0/README.md", - content: quest("Retire", "Retire the old site.", [ - "- [Clean up](/quest/m0/cleanup.md) - remove old pages", - ]), + content: quest("Retire", "Retire the old site."), }, { path: "quest/m0/cleanup.md", content: quest("[S] Remove the old pages", "Nothing links to them.") }, ], diff --git a/cloudflare/src/board/model.ts b/cloudflare/src/board/model.ts index fd0c2da2..d2b99765 100644 --- a/cloudflare/src/board/model.ts +++ b/cloudflare/src/board/model.ts @@ -9,7 +9,6 @@ import { branchQuest, children, comparePaths, - entries, isEpic, parse, permanent, @@ -45,7 +44,7 @@ export type Quest = { /** Finished work out of all work, by count and weighted by difficulty. */ export type Progress = { done: number; total: number; weight: number; totalWeight: number }; -/** A milestone or epic: a directory of quests, listed in priority order. */ +/** A milestone or epic: a directory of quests, listed in path order. */ export type Group = { path: string; href: string; @@ -171,7 +170,7 @@ export function readBoard(project: Project, jobs: ReadonlyMap = const progress = (path: string): Progress => { const under = (p: string) => p.startsWith(`${dir(path)}/`); - const remaining = parsed.filter((doc) => under(doc.path) && !isEpic(doc)); + const remaining = parsed.filter((doc) => under(doc.path) && !isEpic(parsed, doc)); const done = finishedUnder(path); const weigh = (titles: string[]) => titles.reduce((sum, text) => sum + WEIGHTS[title(text).size ?? "XS"], 0); const weight = weigh(done.map((c) => c.title)); @@ -183,21 +182,17 @@ export function readBoard(project: Project, jobs: ReadonlyMap = }; }; - // A group's items are its children in priority order, then anything under - // it that no README lists, so nothing in the tree goes unseen. + // A group's items are its children: the quests in its directory, in path order. const seen = new Set([ROOT]); const group = (doc: Doc): Group => { seen.add(doc.path); - const listed = children(doc).filter((path) => docs.has(path) && !seen.has(path)); - const base = dir(doc.path); - const loose = parsed - .map((d) => d.path) - .filter((path) => !listed.includes(path) && !seen.has(path) && direct(base, path)); - const items = [...listed, ...loose].flatMap((path): Item[] => { + const items = children(parsed, doc).flatMap((path): Item[] => { if (seen.has(path)) return []; seen.add(path); const child = docs.get(path)!; - return isEpic(child) ? [{ kind: "epic", epic: group(child) }] : [{ kind: "quest", quest: quest(child) }]; + return isEpic(parsed, child) + ? [{ kind: "epic", epic: group(child) }] + : [{ kind: "quest", quest: quest(child) }]; }); return { path: doc.path, @@ -208,28 +203,26 @@ export function readBoard(project: Project, jobs: ReadonlyMap = }; }; - const root = docs.get(ROOT); - const milestonePaths = [...(root ? children(root) : []), ...parsed.map((doc) => doc.path)].filter( - (path, i, all) => path !== ROOT && permanent(path) && docs.has(path) && all.indexOf(path) === i, - ); - const milestones = milestonePaths.map((path): Milestone => { - const segment = path.split("/")[1]; - return { - ...group(docs.get(path)!), - number: /^[a-z](\d+)$/.exec(segment)?.[1] ?? segment, - summary: lead(contents.get(path) ?? "", "Goal"), - }; - }); + const milestones = parsed + .filter((doc) => doc.path !== ROOT && permanent(doc.path)) + .map((doc): Milestone => { + const segment = doc.path.split("/")[1]; + return { + ...group(doc), + number: /^[a-z](\d+)$/.exec(segment)?.[1] ?? segment, + summary: lead(contents.get(doc.path) ?? "", "Goal"), + }; + }); // Quests outside every milestone still show, in a group of their own. - const rest = parsed.filter((doc) => !seen.has(doc.path) && !isEpic(doc)).map(quest); + const rest = parsed.filter((doc) => !seen.has(doc.path) && !isEpic(parsed, doc)).map(quest); if (rest.length > 0) { milestones.push({ path: "quest", href: questHref(project, ROOT), title: "Unsorted", number: "", - summary: "Quests that no milestone lists.", + summary: "Quests outside every milestone.", progress: { done: 0, total: rest.length, weight: 0, totalWeight: 0 }, items: rest.map((quest) => ({ kind: "quest", quest })), }); @@ -263,14 +256,6 @@ export function readBoard(project: Project, jobs: ReadonlyMap = }; } -/** Whether `path` sits directly in `dir`: a quest file, or an epic's README one level down. */ -function direct(dir: string, path: string): boolean { - const rest = path.slice(dir.length + 1); - if (!path.startsWith(`${dir}/`)) return false; - const parts = rest.split("/"); - return parts.length === 1 ? parts[0] !== "README.md" : parts.length === 2 && parts[1] === "README.md"; -} - /** Only the quests with this status, dropping epics left empty. */ export function only(items: Item[], kind: Status["kind"]): Item[] { return items.flatMap((item): Item[] => { diff --git a/cloudflare/src/board/pages.tsx b/cloudflare/src/board/pages.tsx index 283e21f5..4c526959 100644 --- a/cloudflare/src/board/pages.tsx +++ b/cloudflare/src/board/pages.tsx @@ -431,11 +431,6 @@ export function QuestPage(props: { board: Board; doc: Doc; content: string; user const heading = title(doc.title?.text ?? doc.path); const markdown = blobHref(project, doc.path); const required = entries(doc, "Required"); - const childPaths = new Set(group?.items.map((item) => (item.kind === "quest" ? item.quest.path : item.epic.path))); - const external = required.filter((entry) => { - const path = entry.target === null ? null : rooted(entry.target); - return path === null || !childPaths.has(path); - }); return (
@@ -457,11 +452,11 @@ export function QuestPage(props: { board: Board; doc: Doc; content: string; user if (section.heading === "Required") { return ( <> - {external.length > 0 && ( + {required.length > 0 && ( <>

Requires

    - {external.map((entry) => ( + {required.map((entry) => ( ))}
diff --git a/cloudflare/src/home.tsx b/cloudflare/src/home.tsx index eff3631e..f79226ef 100644 --- a/cloudflare/src/home.tsx +++ b/cloudflare/src/home.tsx @@ -37,7 +37,7 @@ people retry a failed download. const tree = `quest/ README.md # The roadmap m0/ - README.md # First milestone, in priority order + README.md # The first milestone export.md # Available download.md # Requires: export.md`; @@ -204,7 +204,7 @@ export function Home(props: { setup: string; board: Board }) {

Plan with your agent

/quest-plan asks the questions that turn an idea into scoped quests, with - dependencies, in priority order. + dependencies, in milestones by priority.

  • diff --git a/cloudflare/src/map.tsx b/cloudflare/src/map.tsx index 1bdeac48..afb8288d 100644 --- a/cloudflare/src/map.tsx +++ b/cloudflare/src/map.tsx @@ -1,4 +1,4 @@ -import { type Doc, entries, rooted } from "quest/core"; +import { type Doc, requires } from "quest/core"; import { type Milestone, type Board, @@ -30,15 +30,14 @@ export type Region = { milestone: Milestone; href: string; paths: Path[] }; * as everything it still holds. */ function steps(docs: Map): (path: string) => number { + const all = [...docs.values()]; const memo = new Map(); const step = (path: string): number => { const known = memo.get(path); if (known !== undefined) return known; // A cycle is a `quest check` failure; it must not hang the page. memo.set(path, 0); - const required = entries(docs.get(path)!, "Required") - .map((entry) => (entry.target === null ? null : rooted(entry.target))) - .filter((target): target is string => target !== null && docs.has(target)); + const required = requires(all, docs.get(path)!).filter((target) => docs.has(target)); const value = required.length === 0 ? 0 : 1 + Math.max(...required.map(step)); memo.set(path, value); return value; @@ -46,7 +45,7 @@ function steps(docs: Map): (path: string) => number { return step; } -/** The board's milestones as map regions, each path ordered by step, then priority. */ +/** The board's milestones as map regions, each path ordered by step, then path order. */ export function chart(board: Board): Region[] { const step = steps(board.docs); const ordered = (quests: Quest[]): Quest[] => @@ -56,8 +55,8 @@ export function chart(board: Board): Region[] { .map(({ quest }) => quest); return board.milestones.map((milestone) => { - // Paths keep the milestone's priority order. The quests it lists directly share - // one main path, placed where the first of them is listed. + // Paths keep the milestone's path order. The quests directly in it share one + // main path, placed where the first of them sorts. const loose = milestone.items.flatMap((item) => (item.kind === "quest" ? [item.quest] : [])); const main: Path = { title: "Main path", href: null, progress: null, waypoints: ordered(loose) }; const paths = milestone.items.flatMap((item): Path[] => { diff --git a/cloudflare/test/board.test.ts b/cloudflare/test/board.test.ts index b5e3f1d4..cc541f5d 100644 --- a/cloudflare/test/board.test.ts +++ b/cloudflare/test/board.test.ts @@ -5,11 +5,9 @@ import { type Board, blobHref, findDoc, findGroup, only, questHref, readBoard, t import type { Project } from "../src/board/project"; const docs: Record = { - "quest/README.md": "# Quests\n\n## Goal\n\nShip it.\n\n## Required\n\n- [M0](/quest/m0/README.md) - first\n", - "quest/m0/README.md": - "# First release\n\n## Goal\n\nThe *first* release.\n\n## Required\n\n- [Epic](/quest/m0/epic/README.md) - grouped\n- [Solo](/quest/m0/solo.md) - alone\n", - "quest/m0/epic/README.md": - "# An epic\n\n## Goal\n\nGrouped work.\n\n## Required\n\n- [Ready](/quest/m0/epic/ready.md) - first\n- [Blocked](/quest/m0/epic/blocked.md) - second\n- [Taken](/quest/m0/epic/taken.md) - third\n- [Turned](/quest/m0/epic/turned.md) - fourth\n", + "quest/README.md": "# Quests\n\n## Goal\n\nShip it.\n", + "quest/m0/README.md": "# First release\n\n## Goal\n\nThe *first* release.\n", + "quest/m0/epic/README.md": "# An epic\n\n## Goal\n\nGrouped work.\n", "quest/m0/epic/ready.md": "# [S] Ready quest\n\n## Goal\n\nDo it.\n", "quest/m0/epic/blocked.md": "# [M] Blocked quest\n\n## Goal\n\nLater.\n\n## Required\n\n- [Ready](/quest/m0/epic/ready.md) - needs it\n", @@ -17,7 +15,7 @@ const docs: Record = { "# [XL] Taken quest\n\n## Goal\n\nMine.\n\n## Claim\n\n- Jane Doe (github:jdoe) on https://example.com/jdoe/repo since 2026-10-02\n", "quest/m0/epic/turned.md": "# [XS] Turned-in quest\n\n## Goal\n\nDone soon.\n", "quest/m0/solo.md": "# [L] Solo quest\n\n## Goal\n\nAlone.\n", - "quest/m0/loose.md": "# [S] Loose quest\n\n## Goal\n\nListed nowhere.\n", + "quest/m0/loose.md": "# [S] Loose quest\n\n## Goal\n\nNo blockers either.\n", }; function project(overrides: Partial = {}): Project { @@ -53,13 +51,13 @@ describe("board model", () => { expect(board.counts).toEqual({ available: 4, pending: 0, blocked: 1, "turn-in": 1, accepted: 0 }); }); - it("groups milestones and epics in priority order, then unlisted quests", () => { + it("groups milestones and epics by their directories, in path order", () => { const [milestone] = board.milestones; expect(milestone).toMatchObject({ number: "0", title: "First release", summary: "The first release." }); expect(milestone.items.map((item) => (item.kind === "quest" ? item.quest.path : item.epic.path))).toEqual([ "quest/m0/epic/README.md", - "quest/m0/solo.md", "quest/m0/loose.md", + "quest/m0/solo.md", ]); expect(trail(board, "quest/m0/epic/ready.md").map((group) => group.title)).toEqual([ "First release", diff --git a/cloudflare/test/core.test.ts b/cloudflare/test/core.test.ts index 2e384cd2..f5c1da72 100644 --- a/cloudflare/test/core.test.ts +++ b/cloudflare/test/core.test.ts @@ -6,7 +6,7 @@ import { describe, expect, it } from "vitest"; describe("quest/core", () => { it("checks a tree and finds ready work", () => { const docs = [ - parse("quest/README.md", "# Quests\n\n## Goal\n\nShip it.\n\n## Required\n\n- [One](/quest/one.md)\n"), + parse("quest/README.md", "# Quests\n\n## Goal\n\nShip it.\n"), parse("quest/one.md", "# [S] One\n\n## Goal\n\nThe first quest.\n"), ]; const paths = new Set(docs.map((doc) => doc.path)); @@ -16,10 +16,7 @@ describe("quest/core", () => { it("reports a quest and an epic that share a path", () => { const docs = [ - parse( - "quest/README.md", - "# Quests\n\n## Goal\n\nShip it.\n\n## Required\n\n- [Quest](/quest/one.md)\n- [Epic](/quest/one/README.md)\n", - ), + parse("quest/README.md", "# Quests\n\n## Goal\n\nShip it.\n"), parse("quest/one.md", "# [S] One\n\n## Goal\n\nA quest.\n"), parse("quest/one/README.md", "# [S] Epic\n\n## Goal\n\nAn epic's remaining work.\n"), ]; diff --git a/cloudflare/test/jobs.test.ts b/cloudflare/test/jobs.test.ts index 64b3c535..ed9aea6c 100644 --- a/cloudflare/test/jobs.test.ts +++ b/cloudflare/test/jobs.test.ts @@ -1113,18 +1113,11 @@ describe("job routes", () => { }); it("starts an epic on its README branch while a child's branch is claimed", async () => { - // The epic's last listed child merged, leaving its own work; another quest under it is claimed. + // The epic's last child merged, leaving its own work, and that child's branch still holds a claim. const documents = [ - { - path: "quest/README.md", - content: "# Project\n\n## Goal\n\nBuild it.\n\n## Required\n\n- [M0](/quest/m0/README.md)\n", - }, - { - path: "quest/m0/README.md", - content: "# First\n\n## Goal\n\nShip.\n\n## Required\n\n- [Epic](/quest/m0/epic/README.md)\n", - }, + { path: "quest/README.md", content: "# Project\n\n## Goal\n\nBuild it.\n" }, + { path: "quest/m0/README.md", content: "# First\n\n## Goal\n\nShip.\n" }, { path: "quest/m0/epic/README.md", content: "# [S] Epic\n\n## Goal\n\nThe epic's own work.\n" }, - { path: "quest/m0/epic/child.md", content: "# [S] Child\n\n## Goal\n\nClaimed.\n" }, ]; await db .prepare( @@ -1132,7 +1125,6 @@ describe("job routes", () => { ) .bind(JSON.stringify(documents), JSON.stringify(["quest/m0/epic/child"])) .run(); - expect((await post("", { workflow: "start", target: "quest/m0/epic/child.md" })).status).toBe(409); expect((await post("", { workflow: "start", target: "quest/m0/epic/README.md" })).status).toBe(201); const [job] = await store.listJobs(db, 10); expect(job).toMatchObject({ diff --git a/cloudflare/test/links.test.ts b/cloudflare/test/links.test.ts index d1621592..3491a90a 100644 --- a/cloudflare/test/links.test.ts +++ b/cloudflare/test/links.test.ts @@ -10,11 +10,7 @@ const project: Project = { commit: "a".repeat(40), date: "2026-10-07", documents: [ - { - path: "quest/README.md", - content: - "# Quests\n\n## Goal\n\nShip it.\n\n## Required\n\n- [One](/quest/x%23y.md)\n- [Two](/quest/two.md)\n", - }, + { path: "quest/README.md", content: "# Quests\n\n## Goal\n\nShip it.\n" }, { path: "quest/x#y.md", content: "# [S] One\n\n## Goal\n\nFirst.\n" }, { path: "quest/two.md", diff --git a/cloudflare/test/map.test.ts b/cloudflare/test/map.test.ts index 7514c203..77d98486 100644 --- a/cloudflare/test/map.test.ts +++ b/cloudflare/test/map.test.ts @@ -4,15 +4,13 @@ import type { Project } from "../src/board/project"; import { QuestMap, chart } from "../src/map"; const docs: Record = { - "quest/README.md": "# Quests\n\n## Goal\n\nShip it.\n\n## Required\n\n- [M0](/quest/m0/README.md) - first\n", - "quest/m0/README.md": - "# First release\n\n## Goal\n\nShip.\n\n## Required\n\n- [Epic](/quest/m0/epic/README.md) - grouped\n- [Finale](/quest/m0/finale.md) - last\n- [Solo](/quest/m0/solo.md) - alone\n", - // The epic lists its blocked quest first; the map still puts it after its blocker. - "quest/m0/epic/README.md": - "# An epic\n\n## Goal\n\nGrouped.\n\n## Required\n\n- [Later](/quest/m0/epic/later.md) - second\n- [First](/quest/m0/epic/first.md) - first\n- [Other](/quest/m0/epic/other.md) - third\n", + "quest/README.md": "# Quests\n\n## Goal\n\nShip it.\n", + "quest/m0/README.md": "# First release\n\n## Goal\n\nShip.\n", + "quest/m0/epic/README.md": "# An epic\n\n## Goal\n\nGrouped.\n", + // The blocked quest sorts first by path; the map still puts it after its blocker. "quest/m0/epic/later.md": - "# [M] Later\n\n## Goal\n\nLater.\n\n## Required\n\n- [First](/quest/m0/epic/first.md) - needs it\n", - "quest/m0/epic/first.md": "# [S] First\n\n## Goal\n\nFirst.\n", + "# [M] Later\n\n## Goal\n\nLater.\n\n## Required\n\n- [First](/quest/m0/epic/start.md) - needs it\n", + "quest/m0/epic/start.md": "# [S] First\n\n## Goal\n\nFirst.\n", "quest/m0/epic/other.md": "# [XS] Other\n\n## Goal\n\nOther.\n", "quest/m0/solo.md": "# [L] Solo\n\n## Goal\n\nAlone.\n", // Requiring an epic puts a quest after everything the epic still holds. @@ -39,15 +37,15 @@ describe("quest map", () => { expect(region.href).toBe("/repos/demo#m0"); }); - it("draws epics and the milestone's own quests as paths in priority order", () => { + it("draws epics and the milestone's own quests as paths in path order", () => { expect(region.paths.map((path) => path.title)).toEqual(["An epic", "Main path"]); expect(region.paths[0].href).toBe("/repos/demo/quest/m0/epic/README"); }); - it("orders each path by what it requires, then by priority", () => { + it("orders each path by what it requires, then by path", () => { const titles = region.paths.map((path) => path.waypoints.map((quest) => quest.title)); expect(titles).toEqual([ - ["First", "Other", "Later"], + ["Other", "First", "Later"], ["Solo", "Finale"], ]); }); @@ -89,9 +87,9 @@ describe("waypoint status", () => { it("survives a Required cycle", async () => { const html = await render({ documents: [ - ...project.documents.filter((doc) => doc.path !== "quest/m0/epic/first.md"), + ...project.documents.filter((doc) => doc.path !== "quest/m0/epic/start.md"), { - path: "quest/m0/epic/first.md", + path: "quest/m0/epic/start.md", content: "# [S] First\n\n## Goal\n\nFirst.\n\n## Required\n\n- [Later](/quest/m0/epic/later.md) - loop\n", }, diff --git a/cloudflare/test/project-fixtures.ts b/cloudflare/test/project-fixtures.ts index bdd0264c..e2334f92 100644 --- a/cloudflare/test/project-fixtures.ts +++ b/cloudflare/test/project-fixtures.ts @@ -13,10 +13,7 @@ const db = env.DB; export const commit = "a".repeat(40); export const head = "d".repeat(40); export const documents = [ - { - path: "quest/README.md", - content: "# Project\n\n## Goal\n\nBuild it.\n\n## Required\n\n- [First](/quest/first.md)\n", - }, + { path: "quest/README.md", content: "# Project\n\n## Goal\n\nBuild it.\n" }, { path: "quest/first.md", content: "# [S] First\n\n## Goal\n\nBuild first.\n" }, ]; diff --git a/cloudflare/test/projects.test.ts b/cloudflare/test/projects.test.ts index 2487f9e5..1abc3de6 100644 --- a/cloudflare/test/projects.test.ts +++ b/cloudflare/test/projects.test.ts @@ -35,11 +35,7 @@ function blobOid(content: string) { return createHash("sha1").update(`blob ${bytes.length}\0`).update(bytes).digest("hex"); } const documents = [ - { - path: "quest/README.md", - content: - "# Project\n\n## Goal\n\nBuild it.\n\n## Required\n\n- [First](/quest/first.md)\n- [Second](/quest/second.md)\n", - }, + { path: "quest/README.md", content: "# Project\n\n## Goal\n\nBuild it.\n" }, { path: "quest/first.md", content: "# [S] First\n\n## Goal\n\nBuild first.\n" }, { path: "quest/second.md", @@ -569,13 +565,7 @@ describe("project enrollment", () => { path: `quest/quest-${i}.md`, content: `# [S] Quest ${i}\n\n## Goal\n\nBuild it.\n`, })); - const snapshot = [ - { - path: "quest/README.md", - content: `# Project\n\n## Goal\n\nBuild it.\n\n## Required\n\n${quests.map((q, i) => `- [Quest ${i}](/${q.path})`).join("\n")}\n`, - }, - ...quests, - ]; + const snapshot = [{ path: "quest/README.md", content: "# Project\n\n## Goal\n\nBuild it.\n" }, ...quests]; const { service, calls } = github({ documents: snapshot, subrequestLimit: 50 }); // Enrollment routes resolve the submitted repository before enabling it. await service.resolveRepository(repo.owner, repo.name); diff --git a/examples/export/quest/README.md b/examples/export/quest/README.md index fc34c27b..21cc5cb6 100644 --- a/examples/export/quest/README.md +++ b/examples/export/quest/README.md @@ -4,7 +4,3 @@ Illustrate a two-quest feature: build a CSV endpoint, then add a download button. These are sample plans for an imaginary application, not Quest's own backlog. - -## Required - -- [M0: Download your data](/quest/m0/README.md) - let users export their own records diff --git a/examples/export/quest/m0/README.md b/examples/export/quest/m0/README.md index 8d8a6de3..bd063c47 100644 --- a/examples/export/quest/m0/README.md +++ b/examples/export/quest/m0/README.md @@ -3,8 +3,3 @@ ## Goal Users can download their records as a CSV file from the settings page. - -## Required - -- [CSV endpoint](/quest/m0/export.md) - return the signed-in user's records as CSV -- [Download button](/quest/m0/download.md) - make the export available in settings diff --git a/quest/README.md b/quest/README.md index 05a03a75..228412cf 100644 --- a/quest/README.md +++ b/quest/README.md @@ -10,9 +10,3 @@ versioned Markdown, with a standalone CLI and a reversible adoption path. `m0` is adoption on moq-dev's own repositories, `m1` the public release, and `m2` later work. Add later horizons when concrete work warrants them, keeping milestone numbers stable as earlier milestones complete. - -## Required - -- [M0: moq-dev adoption](/quest/m0/README.md) - kix at quest.moq.dev, used daily on moq-dev/moq, moq-dev/quest, and moq-dev/moq.pro, beside the standalone CLI -- [M1: Public release](/quest/m1/README.md) - kix.quest open to any maintainer, with onboarding, contributor sandboxing, the themed site, and launch material -- [M2: Later work](/quest/m2/README.md) - cloud runners, a native mobile app, shared runners, and donated reviews and CI diff --git a/quest/m0/README.md b/quest/m0/README.md index b9c7b2de..18356895 100644 --- a/quest/m0/README.md +++ b/quest/m0/README.md @@ -51,6 +51,10 @@ Decided 2026-10-30 (user, /quest-plan), replacing "First public release": The land work is what moq-dev's repositories use every day, and the maintainer ranked it first in the 2026-10-30 and 2026-11-01 sessions. + Superseded 2026-11-05 (user, /quest-plan, the + [token waste](/quest/m0/token-waste/README.md) audit): epics no longer + list their children, so no list ranks work within m0; `quest unblocked` + ranks by milestone, then downstream impact, then path. - How do moq-dev's repositories land? Decided 2026-11-01 (maintainer, /quest-plan), reversing the 2026-10-26 move to a batched gate: - ✅ Through GitHub's merge queue again, one PR at a time, with no batching @@ -87,20 +91,3 @@ ownership-manifest design: limits). Prefer offline, deterministic commands, and keep GitHub calls in the CLI rather than skill prose. - Repository-specific rules stay in the repository's own root instructions. - -## Required - -- [Land through the merge queue with an async fixer](/quest/m0/queue-watcher/README.md) - GitHub's merge queue lands one PR at a time, and a host watcher fixes and re-enqueues each PR it drops -- [Merge through a host gate](/quest/m0/host-land/README.md) - the host's fixer containers, and the frozen batched gate for the repositories not yet switched, with merge-commit landing as its one exception -- [The land fixer resolves every mechanical failure](/quest/m0/land-fixer/README.md) - the docs listing what the fixer resolves and hands back -- [Review sessions keyed by upstream branch](/quest/m0/review-session-key.md) - a round from a local branch tracking the PR branch continues that branch's review session -- [Kix decision UI](/quest/m0/kix/README.md) - planning and implementation through prompts and summaries, run on the maintainer's own runners -- [Route quests to models by size](/quest/m0/model-routing/README.md) - `/quest-spawn` starts each quest on the first model of its size's ranked list that can run, reviews rank the same way, and PRs record size, implementer, and reviewer -- [Repositories and hosts follow quest's main](/quest/m0/pin-sync.md) - every push to main reaches each enrolled repository and host through a bot-queued pin bump -- [Cut agent token waste](/quest/m0/token-waste/README.md) - sessions stop paying for loading rules, a second review pass, polling, oversized coordinators, and merge churn -- [Model check](/quest/m0/model-check.md) - recurring: the first audit of the routed PRs retunes the built-in size lists -- [Codex cloud off](/quest/m0/codex-cloud-off.md) - automatic Codex cloud reviews stop once no open PR relies on them -- [Codex project-config skip](/quest/m0/codex-project-config.md) - once Codex keeps a supported way to skip a project's `.codex/` layer, reviews keep the user's config -- [Agents get the dev shell from user settings](/quest/m0/user-dev-shell/README.md) - maintainers' own Claude and Codex settings load the dev shell; repositories drop dev-shell hooks, Quest worktree hooks, and `nix develop` instructions, and `quest init` writes no hooks -- [Session checkouts released](/quest/m0/session-checkouts.md) - a Claude session's own checkout is released when the session ends and reclaimed on resume -- [claude rm upstream report](/quest/m0/claude-rm-upstream.md) - posting approved: ask Claude Code to run `WorktreeRemove` instead of advising an unlock diff --git a/quest/m0/kix/README.md b/quest/m0/kix/README.md index 56e1a35c..ba76f415 100644 --- a/quest/m0/kix/README.md +++ b/quest/m0/kix/README.md @@ -136,11 +136,3 @@ fixes what it finds: [moq-dev/quest#209](https://github.com/moq-dev/quest/pull/209) assumes is the comparison GitHub makes. Try it with a real PR that edits a workflow (decided 2026-10-24, user). - -## Required - -- [Operator setup](/quest/m0/kix/operator-setup.md) - pilot installations and a verified test PR on moq-dev/moq and moq-dev/quest -- [Private repositories](/quest/m0/kix/private.md) - moq-dev/moq.pro enrolls, visible only to signed-in users who can read it -- [Job sandbox](/quest/m0/kix/sandbox/README.md) - head approval for kix-pushed heads, and opencode sandboxed -- [Runner account pool](/quest/m0/kix/cliproxy.md) - the runner routes every Claude and Codex job and review through its own CLIProxyAPI pool -- [Web execution](/quest/m0/kix/execution.md) - spawn and iterate through the UI, ending in contribution PRs diff --git a/quest/m0/kix/sandbox/README.md b/quest/m0/kix/sandbox/README.md index 44dea2e1..d5f0140d 100644 --- a/quest/m0/kix/sandbox/README.md +++ b/quest/m0/kix/sandbox/README.md @@ -89,8 +89,3 @@ Shipped in [moq-dev/quest#212](https://github.com/moq-dev/quest/pull/212) - Sources: [Claude Code sandboxing](https://code.claude.com/docs/en/sandboxing) and [sandbox-runtime](https://www.npmjs.com/package/@anthropic-ai/sandbox-runtime). - -## Required - -- [Per-job opencode saved output](/quest/m0/kix/sandbox/opencode-data.md) - each opencode job saves its tool output and shell captures beside its checkout, so no job reads another's, while sessions and the credential stay in the account's database -- [Claude Code boundary test](/quest/m0/kix/sandbox/claude-boundary.md) - the same hostile-repository test for Claude Code jobs, with a fake model set in the account's settings diff --git a/quest/m0/model-check.md b/quest/m0/model-check.md index 65dfe3c1..4f6d0ce7 100644 --- a/quest/m0/model-check.md +++ b/quest/m0/model-check.md @@ -18,8 +18,7 @@ run is in m0 once routing lands, then each milestone. routing epic's last quest landed. It skips m1's model id comparison and sandbox test, which m0 ran in [moq-dev/quest#426](https://github.com/moq-dev/quest/pull/426). -- m1's run already exists, listed in [m1](/quest/m1/README.md)'s `Required` - and requiring m0. The PR that finishes this run creates no new run: it +- m1's run already exists in [m1](/quest/m1/README.md), requiring m0. The PR that finishes this run creates no new run: it carries the tallies and any table changes into m1's Plan as its baseline. ## Required diff --git a/quest/m0/model-routing/README.md b/quest/m0/model-routing/README.md index 8d24777e..c967fd04 100644 --- a/quest/m0/model-routing/README.md +++ b/quest/m0/model-routing/README.md @@ -85,9 +85,3 @@ are mostly judgment. iterate decisions are in [Route by size](/quest/m0/model-routing/models.md). - Which milestone? ✅ m0 (rejected: m1). It ranks first among m0's work after Kix, by the 2026-11-01 order: land work, then Kix, then the rest. - -## Required - -- [Route by size](/quest/m0/model-routing/models.md) - `/quest-spawn` and iterate dispatches start on the first entry of the size's ranked list that can run, an iterate sized by its remaining work -- [kix records its follow-up sessions](/quest/m0/model-routing/kix-sessions.md) - kix `iterate` and `merge` jobs that change an existing PR record their `Implementer:` line in a PR comment -- [moq-dev pins](/quest/m0/model-routing/pins.md) - moq-dev/moq and moq-dev/moq.pro bump their `quest` pin to pick up the routing diff --git a/quest/m0/queue-watcher/README.md b/quest/m0/queue-watcher/README.md index 071c6c1e..b123c3d0 100644 --- a/quest/m0/queue-watcher/README.md +++ b/quest/m0/queue-watcher/README.md @@ -133,14 +133,6 @@ Shared shape, for the children to follow: lets them admit ahead of agent load, set from moq's workflow or the runner's environment. -## Required - -- [The other repositories follow](/quest/m0/queue-watcher/follow.md) - quest, rind and rust2 are cut over and landing; waits for a fork PR to land through one of their queues -- [Harden the queue runners](/quest/m0/queue-watcher/runners.md) - each queue runner runs only its repository's queue workflow, and every outside fork PR needs approval -- [Tests fit their timeout on the queue runner](/quest/m0/queue-watcher/queue-test-timeouts.md) - the root and Worker suites stop timing out or stalling in merge-group runs, so the queue stops ejecting PRs for them -- [Daemons prune their logs](/quest/m0/queue-watcher/log-retention.md) - the watcher and gate delete their finished logs after a window, so state stays bounded (4.1 GiB on nixos on 2026-11-04) -- [Retire the batching gate](/quest/m0/queue-watcher/retire.md) - once no repository lands through `quest land serve`, its batching code and host units go - ## Related - [The land fixer](/quest/m0/land-fixer/README.md) - the fixer the watcher runs diff --git a/quest/m0/token-waste/README.md b/quest/m0/token-waste/README.md index 8c9e9763..de320f02 100644 --- a/quest/m0/token-waste/README.md +++ b/quest/m0/token-waste/README.md @@ -66,17 +66,6 @@ Decision prompts, chosen options marked ✅: semver-breaking features) is moq-dev/moq's own plan: ✅ re-plan moq separately (rejected: make it quest's convention; not now). -## Required - -- [Single-pass review](/quest/m0/token-waste/review-single-pass.md) - a review round explores the change once, with the diff and REVIEW.md given up front -- [Rules load once](/quest/m0/token-waste/rule-loading.md) - skills and rules arrive in the first turn and survive compaction -- [Coordinators and waits](/quest/m0/token-waste/coordinator-waits.md) - coordinators lean on compaction, children report briefly, and waits block -- [Epics list no children](/quest/m0/token-waste/child-lists.md) - an epic's children are its directory, so finishing a quest edits no README -- [Base merges only when needed](/quest/m0/token-waste/base-merges.md) - a branch merges its base on a conflict, not before every queue attempt -- [Mechanical rules become checks](/quest/m0/token-waste/rule-checks.md) - hooks enforce em dashes, push refspecs, no rebase or force-push, the footer, and `.tmp/`, and their prose leaves the always-loaded rules -- [quest usage](/quest/m0/token-waste/usage.md) - per quest and PR: which models and efforts worked on it, their tokens and API-equal cost, and how the work went; the epic's re-measure runs it -- [token-max](/quest/m0/token-waste/token-max.md) - a standalone Rust CLI that replays Claude Code and Codex transcripts against API prices and recommends cache TTL, compaction, and Bash cap settings - ## Related - [Model check](/quest/m0/model-check.md) - audits the size tables the review quest changes diff --git a/quest/m0/token-waste/base-merges.md b/quest/m0/token-waste/base-merges.md index fd8e846e..135af3eb 100644 --- a/quest/m0/token-waste/base-merges.md +++ b/quest/m0/token-waste/base-merges.md @@ -27,8 +27,9 @@ Decision prompts, chosen options marked ✅: - Merge churn: ✅ the watcher merges quest files, and agents merge the base only on a real conflict or at queue time (rejected: stop editing READMEs, - which [Epics list no children](/quest/m0/token-waste/child-lists.md) now - does a cleaner way; membership from directories, adopted there too). The + which epics listing no children, from + [moq-dev/quest#518](https://github.com/moq-dev/quest/pull/518), now does + a cleaner way; membership from directories, adopted there too). The watcher half already exists: it merges a dropped PR's conflict with the quest merge driver before using a fixer slot ([moq-dev/quest#389](https://github.com/moq-dev/quest/pull/389)). diff --git a/quest/m0/token-waste/child-lists.md b/quest/m0/token-waste/child-lists.md deleted file mode 100644 index 3c35b226..00000000 --- a/quest/m0/token-waste/child-lists.md +++ /dev/null @@ -1,44 +0,0 @@ -# [L] Epics list no children - -## Goal - -An epic's children are the quests in its directory, and its `Required` -section lists only the work that blocks it. Finishing a quest deletes its -file and edits no epic or milestone README, so PRs that finish sibling -quests stop conflicting. `quest check --fix` strips the old child lists from -a repository's tree. - -## Plan - -Decided 2026-11-05 (user, /quest-plan, the -[token waste](/quest/m0/token-waste/README.md) audit). - -Measured, moq-dev PRs created 2026-10-06 to 11-05: - -- `quest/m1/README.md` was touched by 33% of merged moq-dev/moq PRs, and - milestone READMEs as a group by 45%; in moq-dev/rust2, `quest/m3/README.md` - by 290 of 585. -- GitHub's merge queue cannot run quest's merge driver and ejected 723 PRs - for conflicts. The [queue watcher](/quest/m0/queue-watcher/README.md) - re-merges such a PR with the driver since - [moq-dev/quest#389](https://github.com/moq-dev/quest/pull/389), but each - ejection still costs a requeue and a CI run, and the rate after 11-01 - stayed at 0.13 per merged PR. - -Decision prompts, chosen options marked ✅: - -- Ordering: ✅ drop the ordering. The maintainer proposed it. - `quest unblocked` already ranks by milestone, then downstream impact, and - only then by list order (`src/core/unblocked.ts`), so order is only a - tiebreak. Path order replaces it. -- Scope: ✅ every epic (rejected: milestones only; unordered lists). The - directory already is the tree and `Required` already holds blockers, so - epics stay the graph they are minus the copy of the directory. A child - that must precede a sibling becomes an explicit blocker in `Required`. - Parallel siblings spawned from one epic conflict on its README today, as - milestones do. - -The guide's Model, Format, and Creation sections, the skills that rank or -place work (`/quest-plan`, `/quest-audit`, `/quest-spawn`, -`/quest-recurring`, `/quest-import`), and `quest tree`'s output change with -it. The merge driver keeps resolving the blocker lists that remain. diff --git a/quest/m0/user-dev-shell/README.md b/quest/m0/user-dev-shell/README.md index 10b84cad..360d8d0e 100644 --- a/quest/m0/user-dev-shell/README.md +++ b/quest/m0/user-dev-shell/README.md @@ -70,8 +70,3 @@ The user-level hooks live in [kixelated/dotfiles](https://github.com/kixelated/d installed into each Claude profile's `settings.json` and Codex's user config, and generalize this repository's `.claude/hooks/direnv.sh` and moq-dev/moq's `.codex/hooks/direnv.sh`. - -## Required - -- [.worktrees/ stays out of git status](/quest/m0/user-dev-shell/worktrees-exclude.md) - `quest worktree` adds `/.worktrees/` to the clone's local exclude unless something ignores it -- [Repositories drop dev-shell config](/quest/m0/user-dev-shell/repo-config.md) - quest, moq, moq.pro, rind, and rust2 drop their dev-shell hooks and `nix develop` instructions diff --git a/quest/m1/README.md b/quest/m1/README.md index 820c930a..3a837559 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -19,16 +19,3 @@ earlier "Later work" milestone became m2. - ✅ Move to kix.quest in m1 - Stay on quest.moq.dev - Decide later - -## Required - -- [User state in their RunnerHub](/quest/m1/user-state.md) - each user's runners, jobs, inbox, and push subscriptions live in their Durable Object, and D1 keeps repository data and other cross-user state -- [Open kix.quest](/quest/m1/open.md) - the Worker moves to kix.quest and any owner may enroll -- [Release with worktree hooks](/quest/m1/release.md) - tag a release that has `quest worktree hook`, so SETUP.md's release routes work -- [Kix for any repository](/quest/m1/kix/README.md) - onboarding, read-only CI checks, contributor sandboxing, and the maintainer guide -- [Quest log theme](/quest/m1/theme/README.md) - an MMO-style identity, copy, board, landing page, and CLI output for the demo and launch -- [Launch material](/quest/m1/launch.md) - README, quickstart, demo, comparison, and launch-post drafts -- [Workers in a 5-minute cache](/quest/m1/worker-cache.md) - re-plan #276's worker/coordinator split and gate tickets, after confirming the cache premise -- [Retire Decisions needed](/quest/m1/decisions-needed.md) - only `## Waiting` hands a draft back, once no open draft uses the old heading -- [Bun EFAULT report](/quest/m1/bun-efault.md) - report concurrent `rmSync` `EFAULT` on Windows, and drop the workaround once Bun fixes it -- [Model check](/quest/m1/model-check.md) - recurring each milestone: the built-in implementation and review tables use the newest models at efforts retuned from outcomes, and the live sandbox test passes diff --git a/quest/m1/kix/README.md b/quest/m1/kix/README.md index 9a3ca15e..65b84813 100644 --- a/quest/m1/kix/README.md +++ b/quest/m1/kix/README.md @@ -12,8 +12,3 @@ unconfined on their own machines. Moved from m0 on 2026-10-30 (user, /quest-plan): moq-dev's own repositories already carry Quest, are enrolled by the operator, and are worked on by their maintainers, so they need none of this first. - -## Required - -- [Contributor sandboxing](/quest/m1/kix/sandbox/README.md) - contributors' PR heads build in a VM, on stock Ubuntu and verified on macOS -- [Onboarding guide](/quest/m1/kix/guide.md) - a complete maintainer path, from runner setup through a reviewed PR diff --git a/quest/m1/kix/sandbox/README.md b/quest/m1/kix/sandbox/README.md index f66fc35d..43e961f3 100644 --- a/quest/m1/kix/sandbox/README.md +++ b/quest/m1/kix/sandbox/README.md @@ -13,8 +13,3 @@ Split from [the m0 sandbox epic](/quest/m0/kix/sandbox/README.md) on 2026-10-30 (user, /quest-plan): moq-dev's maintainers run their jobs on trusted or approved heads, so untrusted heads stay refused until m1. The design decisions for the whole sandbox stay in the m0 epic's Plan. - -## Required - -- [macOS sandbox](/quest/m1/kix/sandbox/macos.md) - the boundary verified under Seatbelt, then the answer-approval gate removed -- [Untrusted devShells](/quest/m1/kix/sandbox/vm.md) - untrusted PR heads build their devShell in a per-job VM diff --git a/quest/m1/model-check.md b/quest/m1/model-check.md index a14291b9..764138a6 100644 --- a/quest/m1/model-check.md +++ b/quest/m1/model-check.md @@ -92,9 +92,9 @@ work it was routed for: which passes `--ignore-user-config`) nor `quest agent` used Codex hooks, and `quest init` installs none. Recheck if either starts to. - The PR that finishes this run creates the next milestone's run the same - way: listed in that milestone's `Required`, requiring this milestone's - README, carrying forward the model ids and efforts it found, the routing - tallies as a baseline, and anything to check first. + way: in that milestone's directory, requiring this milestone's README, + carrying forward the model ids and efforts it found, the routing tallies + as a baseline, and anything to check first. ## Required diff --git a/quest/m1/theme/README.md b/quest/m1/theme/README.md index da40cc8a..55c8248e 100644 --- a/quest/m1/theme/README.md +++ b/quest/m1/theme/README.md @@ -15,8 +15,7 @@ The pass also renames the "difficulty" leftovers to "size": the Worker's `Difficulty` component (`cloudflare/src/layout.tsx`, used by `cloudflare/src/home.tsx` and `cloudflare/src/board/pages.tsx`), the board's "weighted by difficulty" wording (`cloudflare/src/board/pages.tsx`, -`cloudflare/src/board/model.ts`, `cloudflare/test/board.test.ts`), and the -wording in this README's `Required` list. +`cloudflare/src/board/model.ts`, `cloudflare/test/board.test.ts`). It also replaces the display aliases on the board, the home page, and `cloudflare/README.md` with format terms: Available and `?show=available` become ready, the Requires status and filter become blocked, Accepted by @@ -110,10 +109,6 @@ Decided while planning on 2026-10-05, amended 2026-10-14 where noted: uses these terms. A blocked waypoint's tooltip lists what it needs under "Required:". -## Required - -- [Landing page](/quest/m1/theme/landing.md) - the home page's calls to action lead to sign-in, onboarding, and the setup paste - ## Related - [Launch material](/quest/m1/launch.md) - posts, quickstart, demo, and comparison written in the same voice diff --git a/quest/m2/README.md b/quest/m2/README.md index fc36765e..7c9eca1c 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -5,17 +5,3 @@ Extend kix.quest with cloud runners, a native mobile app, runners shared with other projects, donated reviews and CI, stronger isolation, and additional login providers. This milestone does not gate the public release. - -## Required - -- [Cloud runners](/quest/m2/cloud/README.md) - one-click free cloud runners, API-key and donor funding, then paid compute -- [Native mobile app](/quest/m2/mobile-app.md) - push notifications with quick replies to decisions -- [Shared runners](/quest/m2/donor-runner.md) - offer your runner and accounts to other projects -- [Review and check automation](/quest/m2/automation/README.md) - donated reviews, CI, and a shared Nix cache -- [opencode reviewers](/quest/m2/review-harnesses.md) - `quest review` runs opencode read-only, for the council's DeepSeek member -- [Review council](/quest/m2/council.md) - `/quest-council` reviews a PR with one blind model per maker and merges their findings with agreement counts -- [Donor isolation](/quest/m2/donor-isolation.md) - stronger boundaries for untrusted shared jobs -- [ChatGPT hosted runs](/quest/m2/chatgpt-hosted.md) - conditional on provider approval and current terms -- [ChatGPT approval](/quest/m2/chatgpt-waitlist.md) - resolve hosted-use approval before implementation -- [Delete the legacy hold labels](/quest/m2/legacy-labels.md) - once every gated repository pins quest past #326, only `quest:active` and `quest:kix` are holds -- [Worktree hook PATH error](/quest/m2/hook-path-error.md) - a worktree hook without `quest` on `PATH` says so and names the dev-shell launch route diff --git a/quest/m2/automation/README.md b/quest/m2/automation/README.md index 1c33ccb7..dd6ed835 100644 --- a/quest/m2/automation/README.md +++ b/quest/m2/automation/README.md @@ -10,9 +10,3 @@ authorized agent reviews and CI capacity using ordinary GitHub interfaces. Decided 2026-10-13: C1 first, then C2. Existing repository checks remain part of implementation; this epic adds independent donated review and CI jobs. No custom review database or git-note approval protocol is introduced. - -## Required - -- [Agent reviews](/quest/m2/automation/review.md) - attributed, advisory GitHub reviews -- [Donated checks](/quest/m2/automation/checks.md) - repository-defined check execution with explicit trust -- [Nix cache](/quest/m2/automation/cache.md) - optional main-only signed build cache diff --git a/quest/m2/cloud/README.md b/quest/m2/cloud/README.md index cf1fabc2..6c50de33 100644 --- a/quest/m2/cloud/README.md +++ b/quest/m2/cloud/README.md @@ -26,10 +26,3 @@ Decided 2026-10-15 in the decisions-not-implementations interview: for the cloud runners that depend on it. - Funding setup and operating guidance stay in existing service documentation; each implementation updates the docs it changes. - -## Required - -- [API funding](/quest/m2/cloud/funding.md) - maintainer API keys, the credential proxy, and durable usage accounting -- [Hosted runners](/quest/m2/cloud/runners.md) - free, capped cloud runners enabled with one click -- [Donor allocations](/quest/m2/cloud/donors.md) - shared API budgets after maintainer-funded cloud runners work -- [Paid compute](/quest/m2/cloud/billing.md) - charge for cloud runner compute once free capacity is not enough diff --git a/scripts/lifecycle-check.mjs b/scripts/lifecycle-check.mjs index 44ff1f9f..04773be3 100644 --- a/scripts/lifecycle-check.mjs +++ b/scripts/lifecycle-check.mjs @@ -84,16 +84,8 @@ try { for (const skill of skills) assertFile(root, `${dir}/quest-${skill}/SKILL.md`, run(root, "skill", skill, "--stub")); } - write( - root, - "quest/README.md", - "# Lifecycle\r\n\r\n## Goal\r\n\r\nKeep plans.\r\n\r\n## Required\r\n\r\n- [First](/quest/m0/README.md)\r\n", - ); - write( - root, - "quest/m0/README.md", - "# First\r\n\r\n## Goal\r\n\r\nA milestone.\r\n\r\n## Required\r\n\r\n- [One](/quest/m0/one.md)\r\n- [Two](/quest/m0/two.md)\r\n", - ); + write(root, "quest/README.md", "# Lifecycle\r\n\r\n## Goal\r\n\r\nKeep plans.\r\n"); + write(root, "quest/m0/README.md", "# First\r\n\r\n## Goal\r\n\r\nA milestone.\r\n"); write(root, "quest/m0/one.md", "# [S] One\r\n\r\n## Goal\r\n\r\nFirst.\r\n"); write( root, diff --git a/src/cli/main.ts b/src/cli/main.ts index d094ee97..7d39b199 100644 --- a/src/cli/main.ts +++ b/src/cli/main.ts @@ -163,14 +163,15 @@ export function main(argv: string[], out: Output): number | Promise { "first: a stale base can predate the quest and skip it.\n\n" + "With --fix, first drop every Required, Related, or Closes entry that links to a quest deleted in " + "the history of HEAD, and of MERGE_HEAD during a merge, that the working tree lacks, as quest rm " + - "does, such as the quests a merged base finished, with any heading left empty. It prints M for each " + - "edited document and leaves the edits unstaged. A quest moved rather than deleted, a link that never " + - "named a quest, and a link in prose stay for the check to report. Refuses outside a git work tree " + - "and while a quest file has unresolved conflicts.", + "does, such as the quests a merged base finished, and every epic's Required entry naming a quest in " + + "its own directory, which the epic already waits for, with any heading left empty. It prints M for " + + "each edited document and leaves the edits unstaged. A quest moved rather than deleted, a link that " + + "never named a quest, and a link in prose stay for the check to report. Refuses outside a git work " + + "tree and while a quest file has unresolved conflicts.", ) .option("--base ", "Also check the quest branch's diff from its merge base with this ref") .option("--branch ", "The PR's head branch, when it differs from the current branch (needs --base)") - .option("--fix", "First drop list links to quests the history deleted") + .option("--fix", "First drop list links to quests the history deleted, and epics' links to their own quests") .action((options: { base?: string; branch?: string; fix?: boolean }) => { if (options.branch !== undefined && options.base === undefined) { throw new UsageError("--branch requires --base"); @@ -245,7 +246,7 @@ export function main(argv: string[], out: Output): number | Promise { .command("unblocked") .summary("Rank ready quests, or print what blocks one quest") .description( - "Rank ready quests by milestone priority, distinct transitive dependents, then tree order. " + + "Rank ready quests by milestone priority, distinct transitive dependents, then path order. " + "Given a path, print what blocks that quest instead.\n\n" + "Counts exclude structural epic membership. Other prerequisites may remain for dependents. " + "Invalid trees fail before printing a ranking. Prints a count and path per line; --json prints an " + @@ -332,7 +333,7 @@ export function main(argv: string[], out: Output): number | Promise { .description( "List every quest with a ## Waiting section and every open draft PR handed back with one (or the " + "older ## Decisions needed): those waiting on the maintainer first, then milestone priority, distinct " + - "transitive dependents as quest unblocked counts them, ready before blocked, then tree order, with " + + "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, and every " + @@ -1186,8 +1187,9 @@ export function main(argv: string[], out: Output): number | Promise { "root-absolute link to it under quest/. The change is staged.\n\n" + "Refuses the root epic and milestones, which are permanent. Refuses outside a git work tree, when " + "the destination exists, and while a moved quest has a claim branch or open PR on origin, or on " + - "the upstream that holds origin's claims (see quest start), since the old branch would no longer name it. Moving a " + - "quest into or out of an epic changes which epic lists it; the check afterwards reports what to fix.\n\n" + + "the upstream that holds origin's claims (see quest start), since the old branch would no longer name it. A " + + "quest belongs to the epic whose directory holds it, so moving it into another directory moves it " + + "into that epic.\n\n" + "Prints R for the move and M for each edited document. Mentions of the old path that are not links, " + "or are outside quest/, are reported on stderr and left alone. Runs quest check on the result and " + "exits 1 if it fails.", @@ -1210,8 +1212,8 @@ export function main(argv: string[], out: Output): number | Promise { .description( "Delete a quest, or an epic and the quests under it, with git rm, and drop every Required, Related, " + "or Closes entry that links to it, with any heading left empty. It also drops every Required link to a " + - "finished milestone, one whose README has no Required left, except the root's own listing. The change " + - "is staged.\n\n" + + "finished milestone, one whose directory holds no other quest and whose README has no Required left, " + + "and every epic's Required entry naming a quest in its own directory. The change is staged.\n\n" + "Refuses outside a git work tree. An epic is its directory or README; removing one that holds other " + "quests requires -r. The root epic and milestones are permanent.\n\n" + "Prints D for each deleted quest and M for each edited document. Mentions that are not list entries, " + diff --git a/src/cli/move.ts b/src/cli/move.ts index 52b74402..9283e41c 100644 --- a/src/cli/move.ts +++ b/src/cli/move.ts @@ -76,7 +76,8 @@ export async function moveQuest( /** * Delete a quest, or an epic with the quests under it, and drop every list - * entry that links to what was deleted. The root and milestones are permanent. + * entry that links to what was deleted, as `remove` does. The root and + * milestones are permanent. */ export function removeQuest(root: string, arg: string, recursive: boolean): Report { workTree(root); @@ -113,10 +114,11 @@ export function removeQuest(root: string, arg: string, recursive: boolean): Repo /** * Drop every list entry that links to a quest deleted in the history of `HEAD`, and of * `MERGE_HEAD` during a merge, that the working tree lacks, as `quest rm` drops the links to a - * quest it deletes. Merging the base brings in the quests it finished as deletions, which leaves - * this branch's links to them dangling. A quest the history moved is a rename, not a deletion, and - * a link to a path that never held a quest is a mistake; both stay for `quest check` to report, as - * does a link in prose. Writes the edited documents without staging them, and refuses while a + * quest it deletes, and every epic's `Required` entry naming a quest in its own directory, which + * the epic already waits for. Merging the base brings in the quests it finished as deletions, which + * leaves this branch's links to them dangling. A quest the history moved is a rename, not a deletion, + * and a link to a path that never held a quest is a mistake; both stay for `quest check` to report, + * as does a link in prose. Writes the edited documents without staging them, and refuses while a * quest file is unmerged, since its conflict markers are not yet a document. Returns `M path` for * each. */ @@ -130,23 +132,24 @@ export function fixLinks(root: string): string[] { throw new Error(`resolve the merge conflicts in ${[...new Set(unmerged)].join(", ")} before quest check --fix`); } const heads = ["HEAD", "MERGE_HEAD"].filter((ref) => verified(root, ref)); - if (heads.length === 0) return []; const deleted = new Set( - // `--relative` names paths from `root`, as the tree's links do, when the tree is nested in its repository. - git(root, [ - "log", - "--relative", - "--diff-filter=D", - "--find-renames", - "--name-only", - "--format=", - "-z", - ...heads, - "--", - "quest", - ]) - .split("\0") - .filter(isQuest), + heads.length === 0 + ? [] + : // `--relative` names paths from `root`, as the tree's links do, when the tree is nested in its repository. + git(root, [ + "log", + "--relative", + "--diff-filter=D", + "--find-renames", + "--name-only", + "--format=", + "-z", + ...heads, + "--", + "quest", + ]) + .split("\0") + .filter(isQuest), ); const edited = remove(sources(root), (path) => deleted.has(path) && !exists(root, path)); for (const [path, text] of edited) writeFileSync(join(root, path), text); diff --git a/src/core/doc.ts b/src/core/doc.ts index a179dcc9..109946f0 100644 --- a/src/core/doc.ts +++ b/src/core/doc.ts @@ -16,7 +16,7 @@ import { gfmTableFromMarkdown } from "mdast-util-gfm-table"; import { gfmStrikethrough } from "micromark-extension-gfm-strikethrough"; import { gfmTable } from "micromark-extension-gfm-table"; -import { depth, escapes, fileName, join, normalize, parent } from "./path"; +import { comparePaths, depth, escapes, fileName, join, normalize, parent } from "./path"; /** * Where a link sits inside its `## Section`, which is what separates a @@ -47,7 +47,7 @@ export interface Link { span: [number, number]; } -/** One top-level list entry: the shape a `Required` child or blocker has. */ +/** One top-level list entry: the shape a `Required` blocker has. */ export interface Entry { /** 1-based source line, for findings. */ line: number; @@ -173,26 +173,43 @@ export function owner(path: string): string { } /** - * The `Required` entries that sit directly under a README's directory: the - * epic's children, in priority order. Every other entry is a blocker like any - * quest's, and a quest that is not a README has no children. + * Whether the epic README `readme` holds `path`: it sits anywhere under the + * epic's directory, so the epic already waits for it. */ -export function children(doc: Doc): string[] { +export function holds(readme: string, path: string): boolean { + return isReadme(readme) && path !== readme && path.startsWith(`${parent(readme)}/`); +} + +/** + * An epic's children: the quests directly in its directory and the READMEs of + * the epics one level down, in path order. A quest that is not a README has + * none. + */ +export function children(docs: readonly Doc[], doc: Doc): string[] { if (!isReadme(doc.path)) return []; const dir = parent(doc.path); - return entries(doc, "Required") - .map((entry) => (entry.target === null ? null : rooted(entry.target))) - .filter((child): child is string => child !== null && owner(child) === dir); + return docs + .map((d) => d.path) + .filter((path) => owner(path) === dir) + .sort(comparePaths); } /** - * An epic is a `README.md` that still requires a child. Any other README is - * what an epic becomes when its last child merges: the epic's own remaining - * work, executed like any other quest. The root and the milestones are the - * exception. + * An epic is a `README.md` whose directory still holds another quest. Any + * other README is what an epic becomes when its last child merges: the epic's + * own remaining work, executed like any other quest. The root and the + * milestones are the exception. */ -export function isEpic(doc: Doc): boolean { - return isReadme(doc.path) && (children(doc).length > 0 || permanent(doc.path)); +export function isEpic(docs: readonly Doc[], doc: Doc): boolean { + return permanent(doc.path) || docs.some((d) => holds(doc.path, d.path)); +} + +/** What must finish before `doc`: its `Required` quests, then, for an epic, its children. */ +export function requires(docs: readonly Doc[], doc: Doc): string[] { + const required = entries(doc, "Required") + .map((entry) => (entry.target === null ? null : rooted(entry.target))) + .filter((target): target is string => target !== null); + return [...required, ...children(docs, doc)]; } /** @@ -223,7 +240,7 @@ export function resolve(docPath: string, target: string): string | null { /** * A root-absolute target as a repository-relative path, or `null` if it is not - * root-absolute or cannot resolve safely. The index and cycle walk use the same + * root-absolute or cannot resolve safely. The rules and cycle walk use the same * decoded, normalized path as link validation. */ export function rooted(target: string): string | null { diff --git a/src/core/edit.ts b/src/core/edit.ts index 8e9c0e3a..b1bd6b16 100644 --- a/src/core/edit.ts +++ b/src/core/edit.ts @@ -5,7 +5,7 @@ // dependency graph. Anything else that mentions a path is prose, which the // caller reports rather than rewriting. -import { type Doc, type Entry, parse, rooted, withoutFragment } from "./doc"; +import { type Doc, type Entry, holds, parse, rooted, withoutFragment } from "./doc"; import { LIST_SECTIONS, finishedMilestone } from "./rules"; /** One quest document as loaded: its repository-relative path and source text. */ @@ -71,24 +71,34 @@ export function move(sources: Source[], from: string, to: string): Moved { * Drop every list entry, in a list section, that opens with a link to a * deleted document, and a section heading left with no entries. Then drop * every `Required` link to a finished milestone, whether this removal emptied - * it or the link was already stale, repeating until nothing changes so the - * result passes `quest check`. Returns the new text of every surviving + * it or the link was already stale, and every epic's `Required` link to a + * quest it holds, which it already waits for, repeating until nothing changes + * so the result passes `quest check`. Returns the new text of every surviving * document that changed. */ export function remove(sources: Source[], deleted: (path: string) => boolean): Map { const texts = new Map(sources.filter((s) => !deleted(s.path)).map((s) => [s.path, s.text])); const changed = new Set(); + const target = (entry: Entry) => (entry.target === null ? null : rooted(entry.target)); const linksDeleted = (entry: Entry) => { - if (entry.section === null || !LIST_SECTIONS.includes(entry.section) || entry.target === null) return false; - const target = rooted(entry.target); - return target !== null && deleted(target); + if (entry.section === null || !LIST_SECTIONS.includes(entry.section)) return false; + const path = target(entry); + return path !== null && deleted(path); + }; + const held = (doc: Doc, entry: Entry) => { + const path = target(entry); + return entry.section === "Required" && path !== null && holds(doc.path, path); }; for (let progress = true; progress;) { progress = false; const docs = [...texts].map(([path, text]) => parse(path, text)); const finished = finishedMilestone(docs); for (const doc of docs) { - const text = drop(texts.get(doc.path)!, doc, (entry) => linksDeleted(entry) || finished(doc, entry)); + const text = drop( + texts.get(doc.path)!, + doc, + (entry) => linksDeleted(entry) || finished(doc, entry) || held(doc, entry), + ); if (text === null) continue; texts.set(doc.path, text); changed.add(doc.path); diff --git a/src/core/index.ts b/src/core/index.ts index c3817b34..ed0d8d50 100644 --- a/src/core/index.ts +++ b/src/core/index.ts @@ -16,12 +16,14 @@ export { children, entries, has, + holds, isQuest, isEpic, owner, parse, permanent, questBranch, + requires, resolve, rooted, SIZES, diff --git a/src/core/path.ts b/src/core/path.ts index 47949f66..e8b7a178 100644 --- a/src/core/path.ts +++ b/src/core/path.ts @@ -60,14 +60,25 @@ export function escapes(path: string): boolean { } /** - * Order paths component by component, so `a/b.md` sorts before `a-b.md` the - * way a directory listing walks them, rather than by raw characters. + * Path order, which is also the quest tree's order: component by component, so + * `a/b.md` sorts before `a-b.md` the way a directory listing walks them, with a + * directory's `README.md` first, since an epic precedes its children, and each + * run of digits compared by value, so the milestone `m10` follows `m9`. */ export function comparePaths(a: string, b: string): number { const left = a.split("/"); const right = b.split("/"); for (let i = 0; i < Math.min(left.length, right.length); i++) { - if (left[i] !== right[i]) return left[i] < right[i] ? -1 : 1; + if (left[i] === right[i]) continue; + if (left[i] === "README.md" || right[i] === "README.md") return left[i] === "README.md" ? -1 : 1; + const [x, y] = [numbered(left[i]), numbered(right[i])]; + if (x !== y) return x < y ? -1 : 1; + return left[i] < right[i] ? -1 : 1; } return left.length - right.length; } + +/** A name with each run of digits zero-padded, so comparing two compares their numbers by value. */ +function numbered(name: string): string { + return name.replace(/\d+/g, (digits) => digits.padStart(20, "0")); +} diff --git a/src/core/ready.ts b/src/core/ready.ts index f152b586..75a31be5 100644 --- a/src/core/ready.ts +++ b/src/core/ready.ts @@ -1,5 +1,5 @@ -// Whether a quest can be started, read from the same `Required` section -// the rules validate. +// Whether a quest can be started, read from the same `Required` sections and +// epic directories the rules validate. // // Readiness is a property of the tree alone, which is what makes it cheap and // deterministic: a finished quest is deleted, so a blocker that still resolves @@ -7,9 +7,8 @@ // coherent, and already done by some other PR - and answering it means asking // the forge, so it belongs to the flow that is already talking to it. -import { type Doc, type Entry, children, entries, has, isEpic, rooted } from "./doc"; +import { type Doc, children, entries, has, isEpic, rooted } from "./doc"; import { comparePaths, normalize } from "./path"; -import { ROOT } from "./rules"; /** One thing standing between a quest and being started. */ export interface Blocker { @@ -38,9 +37,12 @@ export function renderBlocker(blocker: Blocker, depth = 0): string[] { return [`${" ".repeat(depth)}${label(blocker)}`, ...blocker.blockers.flatMap((b) => renderBlocker(b, depth + 1))]; } -/** What blocks `doc`, a required epic expanded into the quests it still holds. Empty means ready. */ +/** + * What blocks `doc`: its `Required` entries, then, for an epic, its children, + * each epic among them expanded into the quests it still holds. Empty means ready. + */ export function blockers(docs: Doc[], doc: Doc): Blocker[] { - return expand(new Map(docs.map((d) => [d.path, d])), doc, [doc.path]); + return expand(docs, new Map(docs.map((d) => [d.path, d])), doc, [doc.path]); } /** @@ -55,30 +57,15 @@ export function lookup(docs: Doc[], path: string): Doc | null { return null; } -/** - * Every document's path in tree order: the root's `Required` walked depth - * first, each epic before its children, then any document no epic lists, by - * path. - */ +/** Every document's path in tree order, which is path order: each epic before its children. */ export function treeOrder(docs: Doc[]): string[] { - const sorted = [...docs].sort((a, b) => comparePaths(a.path, b.path)); - const remaining = new Map(sorted.map((doc) => [doc.path, doc])); - const pending = [ROOT]; - const order: string[] = []; - for (let path = pending.pop(); path !== undefined; path = pending.pop()) { - const doc = remaining.get(path); - if (!doc) continue; - remaining.delete(path); - order.push(path); - if (isEpic(doc)) pending.push(...children(doc).reverse()); - } - return [...order, ...remaining.keys()]; + return docs.map((doc) => doc.path).sort(comparePaths); } /** * Every quest that can be started now, in tree order. * - * An epic is not listed while it still requires children; a README with + * An epic is not listed while its directory holds other quests; a README with * none left is the epic's own remaining work and lists like any other quest. * A quest is ready when it has no `## Required` heading. */ @@ -86,12 +73,12 @@ export function ready(docs: Doc[]): string[] { const byPath = new Map(docs.map((doc) => [doc.path, doc])); return treeOrder(docs).filter((path) => { const doc = byPath.get(path)!; - return !isEpic(doc) && !has(doc, "Required"); + return !isEpic(docs, doc) && !has(doc, "Required"); }); } -/** The blockers of one document: its `Required` entries, which for an epic include its children. */ -function expand(byPath: Map, doc: Doc, stack: string[]): Blocker[] { +/** The blockers of one document: its `Required` entries, then an epic's children. */ +function expand(docs: Doc[], byPath: Map, doc: Doc, stack: string[]): Blocker[] { const found: Blocker[] = []; // A heading left standing after its last blocker still reads as blocked to // everything that greps for it, including `quest check`, which reports it. @@ -104,26 +91,27 @@ function expand(byPath: Map, doc: Doc, stack: string[]): Blocker[] blockers: [], }); } - for (const entry of required) found.push(blocker(byPath, entry, stack)); + for (const entry of required) { + // A bullet that does not open with a link into the tree is invalid, and + // nothing here can clear it, so it is a blocker with nothing under it. + const target = entry.target === null ? null : rooted(entry.target); + found.push(blocker(docs, byPath, target !== null && byPath.has(target) ? target : null, entry.text, stack)); + } + for (const child of children(docs, doc)) found.push(blocker(docs, byPath, child, child, stack)); return found; } -function blocker(byPath: Map, entry: Entry, stack: string[]): Blocker { - // A bullet that does not open with a link into the tree is invalid, and - // nothing here can clear it, so it is a blocker with nothing under it. - const target = entry.target === null ? null : rooted(entry.target); - const path = target !== null && byPath.has(target) ? target : null; - +function blocker(docs: Doc[], byPath: Map, path: string | null, text: string, stack: string[]): Blocker { // Only an epic expands. A required QUEST is the blocker itself, and its // own chain is the answer to running this on that quest instead; printing // it here buries the entries that were asked for under a repeated subtree. // The stack guard is for a tree nobody has run `quest check` on yet, where an - // epic listing an ancestor must print rather than recurse forever. + // epic requiring an ancestor must print rather than recurse forever. let nested: Blocker[] = []; - if (path !== null && isEpic(byPath.get(path)!) && !stack.includes(path)) { + if (path !== null && isEpic(docs, byPath.get(path)!) && !stack.includes(path)) { stack.push(path); - nested = expand(byPath, byPath.get(path)!, stack); + nested = expand(docs, byPath, byPath.get(path)!, stack); stack.pop(); } - return { path, text: entry.text, blockers: nested }; + return { path, text, blockers: nested }; } diff --git a/src/core/rules.ts b/src/core/rules.ts index 11783036..ff4d1369 100644 --- a/src/core/rules.ts +++ b/src/core/rules.ts @@ -6,9 +6,9 @@ // tree. // // The whole tree is validated on every run, never just the changed files: the -// link graph and the epic index are global, so completing one quest breaks -// files the diff never mentions. That is not hypothetical - it is how the index -// entry for a completed quest survived a rebase that produced no conflict at +// link graph and the epic directories are global, so completing one quest +// breaks files the diff never mentions. That is not hypothetical - it is how a +// link to a completed quest survived a rebase that produced no conflict at // all. import { @@ -16,11 +16,12 @@ import { type Entry, entries, has, + holds, isEpic, - children, owner, permanent, questBranch, + requires, resolve, rooted, size, @@ -81,12 +82,12 @@ export function check(docs: Doc[], exists: (path: string) => boolean): Finding[] const known = new Set(docs.map((d) => d.path)); for (const doc of docs) { - headings(found, doc); + headings(found, docs, doc); links(found, exists, known, doc); } collisions(found, known, docs); - index(found, known, docs); + membership(found, known, docs); milestones(found, docs); cycles(found, docs); @@ -115,8 +116,8 @@ function collisions(found: Finding[], known: Set, docs: Doc[]) { } } -function headings(found: Finding[], doc: Doc) { - if (!isEpic(doc)) { +function headings(found: Finding[], docs: Doc[], doc: Doc) { + if (!isEpic(docs, doc)) { if (size(doc) === null) found.push({ path: doc.path, line: null, message: "quest title must be '# [XS|S|M|L|XL] Title'" }); } @@ -207,19 +208,27 @@ function links(found: Finding[], exists: (path: string) => boolean, known: Set, docs: Doc[]) { - const listed = new Set(); - +function membership(found: Finding[], known: Set, docs: Doc[]) { for (const doc of docs) { - for (const child of children(doc)) listed.add(child); + const epic = join(owner(doc.path), "README.md"); + // The root epic is permanent and has nothing above it. + if (doc.path !== ROOT && !known.has(epic)) { + found.push({ + path: doc.path, + line: null, + message: `sits in ${owner(doc.path)}, which has no README.md; every directory under quest/ is an epic, so add its README or move the quest`, + }); + } const seen = new Set(); for (const entry of entries(doc, "Required")) { @@ -236,29 +245,26 @@ function index(found: Finding[], known: Set, docs: Doc[]) { found.push({ path: doc.path, line: entry.line, message: `requires ${entry.target} twice` }); } seen.add(target); + if (holds(doc.path, target)) { + found.push({ + path: doc.path, + line: entry.line, + message: `requires ${entry.target}, which this epic holds; an epic waits for everything in its directory, so remove the entry (quest check --fix does)`, + }); + } } } - - for (const doc of docs) { - // The root epic is permanent and has nothing above it to list it. - if (doc.path === ROOT || listed.has(doc.path)) continue; - found.push({ - path: doc.path, - line: null, - message: `not listed in ${join(owner(doc.path), "README.md")}'s '## Required'; an unlisted quest is unreachable`, - }); - } } /** * A link to a finished milestone is removed. Milestones are permanent, so * unlike a finished quest, which is deleted, the link would keep resolving and - * block its quest forever. A milestone is finished once its README has no - * `## Required`, which counts blockers outside its own directory too. + * block its quest forever. A milestone is finished once its directory holds no + * other quest and its README has no `## Required`. * * Readiness stays a grep for the heading; this rule is what keeps that answer - * true once the milestone empties. The root's own listing of its milestones is - * membership, not a blocker, so it is exempt. + * true once the milestone empties. A root entry naming a milestone is the + * membership rule's finding, not this one's. */ function milestones(found: Finding[], docs: Doc[]) { const finished = finishedMilestone(docs); @@ -285,25 +291,18 @@ export function finishedMilestone(docs: Doc[]): (doc: Doc, entry: Entry) => bool const target = rooted(entry.target); if (target === null || target === ROOT || !permanent(target)) return false; const milestone = byPath.get(target); - return milestone !== undefined && !has(milestone, "Required"); + return milestone !== undefined && !has(milestone, "Required") && !docs.some((d) => holds(target, d.path)); }; } /** * `Required` must be acyclic. A cycle is a set of quests none of which can ever * start, and walking the links to rule one out is exactly the manual step an - * author would otherwise take before adding a blocker. An epic requires its + * author would otherwise take before adding a blocker. An epic waits for its * children, so a quest requiring the epic that holds it is a cycle too. */ function cycles(found: Finding[], docs: Doc[]) { - const blockers = new Map(); - for (const doc of docs) { - const edges = doc.links - .filter((l) => l.section === "Required" && l.position === "entry") - .map((l) => rooted(l.target)) - .filter((t): t is string => t !== null); - blockers.set(doc.path, [...(blockers.get(doc.path) ?? []), ...edges]); - } + const blockers = new Map(docs.map((doc) => [doc.path, requires(docs, doc)])); const state = new Map(); const walk = (node: string, stack: string[]) => { diff --git a/src/core/unblocked.ts b/src/core/unblocked.ts index d83d41e4..5a5fd606 100644 --- a/src/core/unblocked.ts +++ b/src/core/unblocked.ts @@ -1,4 +1,4 @@ -// Rank ready work without mistaking the epic index for downstream work. +// Rank ready work without mistaking epic membership for downstream work. import { handBackWaits } from "./claim"; import { type Doc, branchQuest, children, entries, permanent, rooted } from "./doc"; @@ -18,7 +18,7 @@ export interface RankedQuest { * structure; callers validate filesystem links. */ export interface Ranking { - /** The root's subtree rank of `path`, lowest first; unindexed paths sort last. */ + /** The rank of the root's child that holds `path`, lowest first; the root itself sorts last. */ priority(path: string): number; /** Distinct transitive dependents of `path`, excluding epic membership and milestones. */ impact(path: string): number; @@ -31,14 +31,14 @@ export function ranking(docs: Doc[]): Ranking { const byPath = new Map(docs.map((doc) => [doc.path, doc])); const reverse = new Map(); + const depend = (target: string, path: string, structural: boolean) => { + const dependents = reverse.get(target) ?? []; + dependents.push({ path, structural }); + reverse.set(target, dependents); + }; for (const doc of docs) { - const members = new Set(children(doc)); - for (const entry of entries(doc, "Required")) { - const target = rooted(entry.target!)!; - const dependents = reverse.get(target) ?? []; - dependents.push({ path: doc.path, structural: members.has(target) }); - reverse.set(target, dependents); - } + for (const entry of entries(doc, "Required")) depend(rooted(entry.target!)!, doc.path, false); + for (const child of children(docs, doc)) depend(child, doc.path, true); } // Assign the root's subtrees their priority before scoring. In particular, @@ -48,10 +48,10 @@ export function ranking(docs: Doc[]): Ranking { if (priority.has(path)) return; priority.set(path, rank); const doc = byPath.get(path); - if (doc) for (const child of children(doc)) assign(child, rank); + if (doc) for (const child of children(docs, doc)) assign(child, rank); }; const root = byPath.get(ROOT); - if (root) children(root).forEach(assign); + if (root) children(docs, root).forEach(assign); const impact = (path: string): number => { const visited = new Set([path]); diff --git a/test/fixture.ts b/test/fixture.ts index 364aa633..16f7c159 100644 --- a/test/fixture.ts +++ b/test/fixture.ts @@ -29,10 +29,6 @@ export const ROOT_README = `# Quests ## Goal The permanent root epic. - -## Required - -- [M0](/quest/m0/README.md) `; export const M0_README = `# M0 @@ -40,10 +36,6 @@ export const M0_README = `# M0 ## Goal A milestone. - -## Required - -- [Epic](/quest/m0/epic/README.md) `; export const EPIC_README = `# Epic @@ -51,11 +43,6 @@ export const EPIC_README = `# Epic ## Goal An epic. - -## Required - -- [One](/quest/m0/epic/one.md) -- [Two](/quest/m0/epic/two.md) `; export const ONE = `# [S] One diff --git a/test/land-watch.test.ts b/test/land-watch.test.ts index 1faac133..d7c4589f 100644 --- a/test/land-watch.test.ts +++ b/test/land-watch.test.ts @@ -857,8 +857,9 @@ const bin = fileURLToPath(new URL("../src/cli/bin.ts", import.meta.url)); const bunfig = fileURLToPath(new URL("../bunfig.toml", import.meta.url)); const PATH = process.env.PATH; -const EPIC = (entries: string[]) => - `# Epic\n\n## Goal\n\nAn epic.\n\n## Required\n\n${entries.map((entry) => `- [${entry}](/quest/m0/${entry}.md)`).join("\n")}\n`; +/** The launch quest, which every quest the PRs plan or finish blocks: the list they all edit. */ +const LAUNCH = (entries: string[]) => + `# [S] Launch\n\n## Goal\n\nLaunch.\n\n## Required\n\n${entries.map((entry) => `- [${entry}](/quest/m0/${entry}.md)`).join("\n")}\n`; /** github.com's `upstream/project` on disk: main, and each PR's branch `branch-`, also at `refs/pull//head`. */ function upstream() { @@ -878,8 +879,9 @@ function upstream() { commit( { ".gitattributes": "quest/** merge=quest\n", - "quest/README.md": "# Quests\n\n## Goal\n\nRoot.\n\n## Required\n\n- [M0](/quest/m0/README.md)\n", - "quest/m0/README.md": EPIC(["a"]), + "quest/README.md": "# Quests\n\n## Goal\n\nRoot.\n", + "quest/m0/README.md": "# M0\n\n## Goal\n\nA milestone.\n", + "quest/m0/launch.md": LAUNCH(["a"]), "quest/m0/a.md": "# [S] A\n\n## Goal\n\nA.\n", "code.txt": "one\ntwo\nthree\n", }, @@ -1198,14 +1200,14 @@ describe.skipIf(process.platform === "win32")("the watcher's land fixer", () => test("a quest-file conflict is merged with the quest driver, and a code conflict goes to the fixer", async () => { const { repo, state, fix, context } = setup(1); const quests = repo.pull(3, { - "quest/m0/README.md": EPIC(["a", "c"]), + "quest/m0/launch.md": LAUNCH(["a", "c"]), "quest/m0/c.md": "# [S] C\n\n## Goal\n\nC.\n", }); const code = repo.pull(4, { "code.txt": "one\nII\nthree\n" }); const failing = repo.pull(6, { "feature.txt": "new\n" }); const built = repo.main(); const base = repo.advance({ - "quest/m0/README.md": EPIC(["a", "b"]), + "quest/m0/launch.md": LAUNCH(["a", "b"]), "quest/m0/b.md": "# [S] B\n\n## Goal\n\nB.\n", "code.txt": "one\n2\nthree\n", }); @@ -1272,7 +1274,7 @@ printf '[{"number":%s,"action":"fixed","head":"%s","reason":"preserve both confl "fixing 4", `requeued 3 ${merged()}`, ]); - expect(git(repo.origin, "show", `${merged()}:quest/m0/README.md`)).toBe(EPIC(["a", "b", "c"]).trim()); + expect(git(repo.origin, "show", `${merged()}:quest/m0/launch.md`)).toBe(LAUNCH(["a", "b", "c"]).trim()); expect(git(repo.origin, "rev-parse", `${merged()}^1`, `${merged()}^2`).split("\n")).toEqual([quests, base]); expect(github.mutations).toEqual([`enablePullRequestAutoMerge 3 ${merged()}`]); expect(github.comments[3].at(-1)!.body).toContain( diff --git a/test/land.test.ts b/test/land.test.ts index 74e9b096..efa0383a 100644 --- a/test/land.test.ts +++ b/test/land.test.ts @@ -104,8 +104,9 @@ function git(cwd: string, ...args: string[]): string { const QUEST = (title: string) => `# [S] ${title}\n\n## Goal\n\n${title}.\n`; -const EPIC = (entries: string[]) => - `# Epic\n\n## Goal\n\nAn epic.\n\n## Required\n\n${entries.map((entry) => `- [${entry}](/quest/m0/${entry}.md)`).join("\n")}\n`; +/** The launch quest, which every quest the PRs plan or finish blocks: the list they all edit. */ +const LAUNCH = (entries: string[]) => + `# [S] Launch\n\n## Goal\n\nLaunch.\n\n## Required\n\n${entries.map((entry) => `- [${entry}](/quest/m0/${entry}.md)`).join("\n")}\n`; /** The tip of every forge's main, which the template sets. */ let forgeBase: string | undefined; @@ -119,8 +120,9 @@ const forge = template((dir) => { const work = initRepository(join(dir, "work")); const files: Record = { ".gitattributes": "quest/** merge=quest\n", - "quest/README.md": "# Quests\n\n## Goal\n\nRoot.\n\n## Required\n\n- [M0](/quest/m0/README.md)\n", - "quest/m0/README.md": EPIC(["a"]), + "quest/README.md": "# Quests\n\n## Goal\n\nRoot.\n", + "quest/m0/README.md": "# M0\n\n## Goal\n\nA milestone.\n", + "quest/m0/launch.md": LAUNCH(["a"]), "quest/m0/a.md": "# [S] A\n\n## Goal\n\nA.\n", "code.txt": "one\ntwo\nthree\n", }; @@ -509,8 +511,8 @@ describe.skipIf(process.platform === "win32")("quest land", () => { test("lands a batch as merge commits that keep each head's ancestry and the tested tree", async () => { const forge = new Forge(); const base = forge.main(); - const one = forge.pull("Add b", { "quest/m0/README.md": EPIC(["a", "b"]), "quest/m0/b.md": QUEST("B") }); - const two = forge.pull("Add c", { "quest/m0/README.md": EPIC(["a", "c"]), "quest/m0/c.md": QUEST("C") }); + const one = forge.pull("Add b", { "quest/m0/launch.md": LAUNCH(["a", "b"]), "quest/m0/b.md": QUEST("B") }); + const two = forge.pull("Add c", { "quest/m0/launch.md": LAUNCH(["a", "c"]), "quest/m0/c.md": QUEST("C") }); const heads = [one.head!, two.head!]; const deps = await forge.deps(); const plan = await resolveQueue(REPOSITORY, MERGE, deps); @@ -535,15 +537,15 @@ describe.skipIf(process.platform === "win32")("quest land", () => { expect(git(forge.origin, "show", "-s", "--format=%P", "main")).toBe(`${one.squash} ${two.head}`); expect(git(forge.origin, "rev-parse", `${one.squash}^{tree}`)).toBe(chain.links[0].tree); expect(git(forge.origin, "rev-parse", "main^{tree}")).toBe(chain.links[1].tree); - expect(git(forge.origin, "show", "main:quest/m0/README.md")).toBe(EPIC(["a", "b", "c"]).trim()); + expect(git(forge.origin, "show", "main:quest/m0/launch.md")).toBe(LAUNCH(["a", "b", "c"]).trim()); }); test("prepares a behind-base PR with quest resolve and the exact tested tree", async () => { const forge = new Forge(); - forge.advance({ "quest/m0/README.md": EPIC(["a", "b"]), "quest/m0/b.md": QUEST("B") }); - const pull = forge.pull("Remove a", { "quest/m0/README.md": EPIC(["b"]), "quest/m0/a.md": null }); + forge.advance({ "quest/m0/launch.md": LAUNCH(["a", "b"]), "quest/m0/b.md": QUEST("B") }); + const pull = forge.pull("Remove a", { "quest/m0/launch.md": LAUNCH(["b"]), "quest/m0/a.md": null }); const pin = pull.head!; - forge.advance({ "quest/m0/README.md": EPIC(["a", "b", "c"]), "quest/m0/c.md": QUEST("C") }); + forge.advance({ "quest/m0/launch.md": LAUNCH(["a", "b", "c"]), "quest/m0/c.md": QUEST("C") }); const base = forge.main(); const deps = await forge.deps(); const plan = await resolveQueue(REPOSITORY, SQUASH, deps); @@ -562,22 +564,22 @@ describe.skipIf(process.platform === "win32")("quest land", () => { const adding = mode === "adding"; if (!adding) forge.advance({ - "quest/m0/README.md": EPIC(["a", "b", "c"]), + "quest/m0/launch.md": LAUNCH(["a", "b", "c"]), "quest/m0/b.md": QUEST("B"), "quest/m0/c.md": QUEST("C"), }); // Each PR adds or finishes its own quest, so each passes `quest check` alone on the base. const one = forge.pull("Change b", { - "quest/m0/README.md": EPIC(adding ? ["a", "b"] : ["a", "c"]), + "quest/m0/launch.md": LAUNCH(adding ? ["a", "b"] : ["a", "c"]), "quest/m0/b.md": adding ? QUEST("B") : null, }); const two = forge.pull("Change c", { - "quest/m0/README.md": EPIC(adding ? ["a", "c"] : ["a", "b"]), + "quest/m0/launch.md": LAUNCH(adding ? ["a", "c"] : ["a", "b"]), "quest/m0/c.md": adding ? QUEST("C") : null, }); expect((await forge.round()).landing).toEqual([`landed 1 ${one.squash}`, `landed 2 ${two.squash}`]); - expect(git(forge.origin, "show", "main:quest/m0/README.md")).toBe( - EPIC(adding ? ["a", "b", "c"] : ["a"]).trim(), + expect(git(forge.origin, "show", "main:quest/m0/launch.md")).toBe( + LAUNCH(adding ? ["a", "b", "c"] : ["a"]).trim(), ); }); @@ -987,11 +989,11 @@ describe.skipIf(process.platform === "win32")("quest land", () => { "bunfig.toml": 'preload = ["./evil.ts"]\n', ".env": "BUN_OPTIONS=--preload=./evil.ts\n", "evil.ts": "throw new Error('PR code ran');\n", - "quest/m0/README.md": EPIC(["a", "b"]), + "quest/m0/launch.md": LAUNCH(["a", "b"]), "quest/m0/b.md": "# [S] B\n\n## Goal\n\nB.\n", }); forge.pull("Add c quest", { - "quest/m0/README.md": EPIC(["a", "c"]), + "quest/m0/launch.md": LAUNCH(["a", "c"]), "quest/m0/c.md": "# [S] C\n\n## Goal\n\nC.\n", }); const { landing } = await forge.round(); @@ -1374,7 +1376,7 @@ describe.skipIf(process.platform === "win32")("host daemon", () => { test("ejects alone a PR that fails quest check on the current base, before batching", async () => { const forge = new Forge(); - forge.advance({ "quest/m0/README.md": EPIC(["a", "b"]), "quest/m0/b.md": QUEST("B") }); + forge.advance({ "quest/m0/launch.md": LAUNCH(["a", "b"]), "quest/m0/b.md": QUEST("B") }); // A mistyped link never named a quest, so nothing the base did explains it. forge.pull("Link b", { "quest/m0/a.md": `${QUEST("A")}\n## Related\n\n- [B](/quest/m0/bb.md) - b\n`, @@ -1390,15 +1392,15 @@ describe.skipIf(process.platform === "win32")("host daemon", () => { test("drops a queued PR's list links to a quest the base finished, in the chain and the landed head", async () => { const forge = new Forge(); - forge.advance({ "quest/m0/README.md": EPIC(["a", "b"]), "quest/m0/b.md": QUEST("B") }); + forge.advance({ "quest/m0/launch.md": LAUNCH(["a", "b"]), "quest/m0/b.md": QUEST("B") }); const pull = forge.pull("Plan c", { - "quest/m0/README.md": EPIC(["a", "b", "c"]), + "quest/m0/launch.md": LAUNCH(["a", "b", "c"]), "quest/m0/c.md": `${QUEST("C")}\n## Required\n\n- [B](/quest/m0/b.md) - b first\n`, "quest/m0/a.md": `${QUEST("A")}\n## Related\n\n- [B](/quest/m0/b.md) - b\n- [C](/quest/m0/c.md) - c\n`, }); const pin = pull.head!; // The base finishes b after the PR was queued, leaving both of its links to b dangling. - forge.advance({ "quest/m0/README.md": EPIC(["a"]), "quest/m0/b.md": null }); + forge.advance({ "quest/m0/launch.md": LAUNCH(["a"]), "quest/m0/b.md": null }); const base = forge.main(); const { checked, landing } = await forge.round(); expect(checked).toEqual([[1]]); @@ -1417,28 +1419,28 @@ describe.skipIf(process.platform === "win32")("host daemon", () => { test("two sibling PRs land together when one finishes a quest the other links", async () => { const forge = new Forge(); forge.advance({ - "quest/m0/README.md": EPIC(["a", "b", "c"]), + "quest/m0/launch.md": LAUNCH(["a", "b", "c"]), "quest/m0/b.md": QUEST("B"), "quest/m0/c.md": QUEST("C"), }); // Each passes `quest check` alone on the base; chained, the first leaves the second's link dangling. - const one = forge.pull("Finish b", { "quest/m0/README.md": EPIC(["a", "c"]), "quest/m0/b.md": null }); + const one = forge.pull("Finish b", { "quest/m0/launch.md": LAUNCH(["a", "c"]), "quest/m0/b.md": null }); const two = forge.pull("Finish c", { - "quest/m0/README.md": EPIC(["a", "b"]), + "quest/m0/launch.md": LAUNCH(["a", "b"]), "quest/m0/c.md": null, "quest/m0/a.md": `${QUEST("A")}\n## Related\n\n- [B](/quest/m0/b.md) - b\n`, }); const { checked, landing } = await forge.round(); expect(checked).toEqual([[1, 2]]); expect(landing).toEqual([`landed 1 ${one.squash}`, `landed 2 ${two.squash}`]); - expect(git(forge.origin, "show", "main:quest/m0/README.md")).toBe(EPIC(["a"]).trim()); + expect(git(forge.origin, "show", "main:quest/m0/launch.md")).toBe(LAUNCH(["a"]).trim()); expect(git(forge.origin, "show", "main:quest/m0/a.md")).toBe(QUEST("A").trim()); }); test("ejects a PR whose prose links a quest the base finished, and keeps links to a quest the base moved", async () => { const forge = new Forge(); forge.advance({ - "quest/m0/README.md": EPIC(["a", "b", "c"]), + "quest/m0/launch.md": LAUNCH(["a", "b", "c"]), "quest/m0/b.md": QUEST("B"), "quest/m0/c.md": `${QUEST("C")}\nMore about c, so a move keeps enough of it to read as a rename.\n`, }); @@ -1448,7 +1450,7 @@ describe.skipIf(process.platform === "win32")("host daemon", () => { }); // The base finishes b and moves c to d. forge.advance({ - "quest/m0/README.md": EPIC(["a", "d"]), + "quest/m0/launch.md": LAUNCH(["a", "d"]), "quest/m0/b.md": null, "quest/m0/c.md": null, "quest/m0/d.md": `${QUEST("C")}\nMore about c, so a move keeps enough of it to read as a rename.\n`, @@ -1461,11 +1463,11 @@ describe.skipIf(process.platform === "win32")("host daemon", () => { test("screens only the PRs a batch reaches, leaving the rest of a long queue for later", async () => { const forge = new Forge(); - forge.advance({ "quest/m0/README.md": EPIC(["a", "b"]), "quest/m0/b.md": QUEST("B") }); + forge.advance({ "quest/m0/launch.md": LAUNCH(["a", "b"]), "quest/m0/b.md": QUEST("B") }); for (let i = 0; i < 4; i++) forge.pull(`PR ${i}`, { [`${i}.txt`]: "ok" }); forge.pull("Link b", { "quest/m0/a.md": `${QUEST("A")}\n## Related\n\n- [B](/quest/m0/b.md) - b\n` }); // The base finishes b, so the last PR's link dangles, but an oldest-first batch of three never reaches it. - forge.advance({ "quest/m0/README.md": EPIC(["a"]), "quest/m0/b.md": null }); + forge.advance({ "quest/m0/launch.md": LAUNCH(["a"]), "quest/m0/b.md": null }); const { checked, landing } = await forge.round(); expect(checked).toEqual([[1, 2, 3]]); expect(landing.map((line) => line.split(" ")[0])).toEqual(["landed", "landed", "landed"]); @@ -2090,8 +2092,8 @@ mv '${result}.new' '${result}' test("a prepared tree mismatch ejects only that PR, and the next round rebuilds the rest on the new base", async () => { const forge = new Forge(); // Both PRs edit the epic, so preparing PR 2 on PR 1's squash runs the quest merge driver. - forge.pull("Add b", { "quest/m0/README.md": EPIC(["a", "b"]), "quest/m0/b.md": QUEST("B") }); - forge.pull("Add c", { "quest/m0/README.md": EPIC(["a", "c"]), "quest/m0/c.md": QUEST("C") }); + forge.pull("Add b", { "quest/m0/launch.md": LAUNCH(["a", "b"]), "quest/m0/b.md": QUEST("B") }); + forge.pull("Add c", { "quest/m0/launch.md": LAUNCH(["a", "c"]), "quest/m0/c.md": QUEST("C") }); forge.pull("Three", { "3.txt": "yes" }); forge.pull("Four", { "4.txt": "yes" }); const deps = await forge.deps(); diff --git a/test/landed.test.ts b/test/landed.test.ts index ddbeb4cc..759cc1df 100644 --- a/test/landed.test.ts +++ b/test/landed.test.ts @@ -29,12 +29,8 @@ function commit(tree: Tree, message: string) { test("a quest branch that deletes its quest passes", () => { const tree = repo("quest/m0/epic/one"); - tree.remove("quest/m0/epic/one.md") - .write( - "quest/m0/epic/README.md", - "# Epic\n\n## Goal\n\nAn epic.\n\n## Required\n\n- [Two](/quest/m0/epic/two.md)\n", - ) - .write("quest/m0/epic/two.md", "# [S] Two\n\n## Goal\n\nAnother quest.\n"); + // Finishing a quest edits only what it blocked, never its epic's README. + tree.remove("quest/m0/epic/one.md").write("quest/m0/epic/two.md", "# [S] Two\n\n## Goal\n\nAnother quest.\n"); commit(tree, "finish one"); expect(tree.run("check", "--base", "main")).toEqual({ code: 0, stdout: "quest: 4 documents ok\n", stderr: "" }); }); @@ -88,7 +84,6 @@ test("a branch that is not a quest branch adds no finding", () => { test("a branch naming no quest at the merge base adds no finding", () => { const tree = repo("quest/m0/epic/three"); tree.write("quest/m0/epic/three.md", "# [S] Three\n\n## Goal\n\nNew.\n"); - tree.append("quest/m0/epic/README.md", "- [Three](/quest/m0/epic/three.md)\n"); commit(tree, "plan three"); expect(tree.run("check", "--base", "main").code).toBe(0); }); diff --git a/test/links.test.ts b/test/links.test.ts index e90985a4..0cb024bb 100644 --- a/test/links.test.ts +++ b/test/links.test.ts @@ -5,10 +5,7 @@ import { ONE, Tree } from "./fixture"; function linked(name: string, target: string): Tree { return new Tree() - .write( - "quest/README.md", - `# Quests\n\n## Goal\n\nShip it.\n\n## Required\n\n- [One](${target})\n- [Two](/quest/two.md)\n`, - ) + .write("quest/README.md", "# Quests\n\n## Goal\n\nShip it.\n") .write(`quest/${name}`, ONE) .write("quest/two.md", `# [S] Two\n\n## Goal\n\nLater.\n\n## Required\n\n- [One](${target})\n`); } diff --git a/test/move.test.ts b/test/move.test.ts index 38c8b860..895719b8 100644 --- a/test/move.test.ts +++ b/test/move.test.ts @@ -10,7 +10,7 @@ import { move, remove } from "../src/core"; import { openPullRequests } from "../src/cli/claims"; import { GitHub, type GitHubDependencies } from "../src/cli/github"; import { main } from "../src/cli/main"; -import { EPIC_README, ROOT_README, Tree, initRepository, tempDir } from "./fixture"; +import { EPIC_README, M0_README, ROOT_README, Tree, initRepository, tempDir } from "./fixture"; // Each test spawns git up to a dozen times, which a busy Windows runner can stretch past 5 s. vi.setConfig({ testTimeout: 30_000 }); @@ -63,22 +63,23 @@ describe("move", () => { const moved = move( [ { - path: "quest/m0/README.md", - text: "# M0\n\n## Goal\n\nG.\n\n## Required\n\n- [E](/quest/m0/e/README.md)\n", + path: "quest/m0/next.md", + text: "# [S] Next\n\n## Goal\n\nG.\n\n## Required\n\n- [E](/quest/m0/e/README.md)\n", }, + { path: "quest/m0/e/README.md", text: "# E\n\n## Goal\n\nG.\n" }, + { path: "quest/m0/e/a.md", text: "# [S] A\n\n## Goal\n\nG.\n" }, { - path: "quest/m0/e/README.md", - text: "# E\n\n## Goal\n\nG.\n\n## Required\n\n- [A](/quest/m0/e/a.md)\n", + path: "quest/m0/e/b.md", + text: "# [S] B\n\n## Goal\n\nG.\n\n## Required\n\n- [A](/quest/m0/e/a.md)\n", }, - { path: "quest/m0/e/a.md", text: "# [S] A\n\n## Goal\n\nG.\n" }, { path: "quest/m0/elsewhere.md", text: "# [S] X\n\n## Related\n\n- [E2](/quest/m0/e2.md)\n" }, ], "quest/m0/e", "quest/m1/e", ); - expect([...moved.texts.keys()]).toEqual(["quest/m0/README.md", "quest/m1/e/README.md"]); - expect(moved.texts.get("quest/m0/README.md")).toContain("- [E](/quest/m1/e/README.md)\n"); - expect(moved.texts.get("quest/m1/e/README.md")).toContain("- [A](/quest/m1/e/a.md)\n"); + expect([...moved.texts.keys()]).toEqual(["quest/m0/next.md", "quest/m1/e/b.md"]); + expect(moved.texts.get("quest/m0/next.md")).toContain("- [E](/quest/m1/e/README.md)\n"); + expect(moved.texts.get("quest/m1/e/b.md")).toContain("- [A](/quest/m1/e/a.md)\n"); }); test("reports a link whose destination is not written as parsed", () => { @@ -119,11 +120,9 @@ describe("remove", () => { "# [S] A\n\n## Goal\n\nAfter [B](/quest/b.md).\n\n- [B](/quest/b.md) in a goal list\n\n## Related\n\nContext.\n", ); }); - test("drops links to finished milestones until nothing changes, keeping the root's listing", () => { - const root = - "# Quests\n\n## Goal\n\nG.\n\n## Required\n\n- [M0](/quest/m0/README.md)\n- [M1](/quest/m1/README.md)\n"; + test("drops links to finished milestones until nothing changes", () => { const sources = [ - { path: "quest/README.md", text: root }, + { path: "quest/README.md", text: "# Quests\n\n## Goal\n\nG.\n" }, // m0 finishes once b goes, which finishes m1, which only waited on m0. { path: "quest/m0/README.md", text: "# M0\n\n## Goal\n\nG.\n\n## Required\n\n- [B](/quest/b.md)\n" }, { @@ -132,7 +131,7 @@ describe("remove", () => { }, { path: "quest/b.md", text: "# [S] B\n\n## Goal\n\nG.\n" }, { - path: "quest/m1/a.md", + path: "quest/a.md", text: "# [S] A\n\n## Goal\n\nG.\n\n## Required\n\n- [M1](/quest/m1/README.md)\n- [M2](/quest/m2/README.md)\n\n" + "## Related\n\n- [M0](/quest/m0/README.md)\n", @@ -141,11 +140,29 @@ describe("remove", () => { { path: "quest/m2/README.md", text: "# M2\n\n## Goal\n\nG.\n" }, ]; const texts = remove(sources, gone); - expect([...texts.keys()].sort()).toEqual(["quest/m0/README.md", "quest/m1/README.md", "quest/m1/a.md"]); + expect([...texts.keys()].sort()).toEqual(["quest/a.md", "quest/m0/README.md", "quest/m1/README.md"]); expect(texts.get("quest/m0/README.md")).toBe("# M0\n\n## Goal\n\nG.\n"); expect(texts.get("quest/m1/README.md")).toBe("# M1\n\n## Goal\n\nG.\n"); - expect(texts.get("quest/m1/a.md")).toBe( - "# [S] A\n\n## Goal\n\nG.\n\n## Related\n\n- [M0](/quest/m0/README.md)\n", + expect(texts.get("quest/a.md")).toBe("# [S] A\n\n## Goal\n\nG.\n\n## Related\n\n- [M0](/quest/m0/README.md)\n"); + }); + + // An epic waits for everything in its directory, so its links to those quests + // are the child lists this format retired. A sibling's link is a real blocker. + test("drops an epic's Required links to quests it holds, at any depth", () => { + const readme = + "# Epic\n\n## Goal\n\nG.\n\n## Required\n\n- [A](/quest/m0/epic/a.md)\n" + + "- [Outside](/quest/m0/outside.md)\n- [Deep](/quest/m0/epic/sub/deep.md)\n\n## Related\n\n- [A](/quest/m0/epic/a.md)\n"; + const sibling = "# [S] B\n\n## Goal\n\nG.\n\n## Required\n\n- [A](/quest/m0/epic/a.md)\n"; + const texts = remove( + [ + { path: "quest/m0/epic/README.md", text: readme }, + { path: "quest/m0/epic/b.md", text: sibling }, + ], + () => false, + ); + expect([...texts.keys()]).toEqual(["quest/m0/epic/README.md"]); + expect(texts.get("quest/m0/epic/README.md")).toBe( + "# Epic\n\n## Goal\n\nG.\n\n## Required\n\n- [Outside](/quest/m0/outside.md)\n\n## Related\n\n- [A](/quest/m0/epic/a.md)\n", ); }); }); @@ -156,28 +173,22 @@ describe("quest mv", () => { const out = await quest(tree, "mv", "/quest/m0/epic/one.md", "quest/m0/epic/first.md"); expect(out).toEqual({ code: 0, - stdout: "R quest/m0/epic/one.md -> quest/m0/epic/first.md\nM quest/m0/epic/README.md\nM quest/m0/epic/two.md\n", + stdout: "R quest/m0/epic/one.md -> quest/m0/epic/first.md\nM quest/m0/epic/two.md\n", stderr: "quest: no origin remote, so claims were not checked\n", }); expect(tree.read("quest/m0/epic/two.md")).toContain("- [One](/quest/m0/epic/first.md) - must finish first"); - expect(staged(tree)).toEqual([ - "M quest/m0/epic/README.md", - "M quest/m0/epic/two.md", - "R quest/m0/epic/one.md -> quest/m0/epic/first.md", - ]); + expect(staged(tree)).toEqual(["M quest/m0/epic/two.md", "R quest/m0/epic/one.md -> quest/m0/epic/first.md"]); tree.accepts(); }); test("moves an epic into a new directory", async () => { const tree = Tree.committed(); const out = await quest(tree, "mv", "quest/m0/epic", "quest/m1/later/epic"); - expect(out.stdout).toBe( - "R quest/m0/epic -> quest/m1/later/epic\nM quest/m0/README.md\nM quest/m1/later/epic/README.md\nM quest/m1/later/epic/two.md\n", - ); - expect(tree.read("quest/m1/later/epic/README.md")).toContain("- [One](/quest/m1/later/epic/one.md)\n"); + expect(out.stdout).toBe("R quest/m0/epic -> quest/m1/later/epic\nM quest/m1/later/epic/two.md\n"); + expect(tree.read("quest/m1/later/epic/two.md")).toContain("- [One](/quest/m1/later/epic/one.md)"); // The epic left m0 for a directory with no README, which check reports rather than mv guessing. expect(out.code).toBe(1); - expect(out.stderr).toContain("quest/m1/later/epic/README.md: not listed in quest/m1/later/README.md"); + expect(out.stderr).toContain("quest/m1/later/epic/README.md: sits in quest/m1/later, which has no README.md"); }); test("reports mentions it does not edit", async () => { @@ -260,18 +271,16 @@ describe("quest mv", () => { describe("quest rm", () => { test("deletes a quest listed under several Required and Related sections", async () => { - const tree = Tree.baseline() - .append("quest/m0/epic/README.md", "- [Three](/quest/m0/epic/three.md)\n") - .write( - "quest/m0/epic/three.md", - "# [S] Three\n\n## Goal\n\nMore.\n\n## Required\n\n- [Two](/quest/m0/epic/two.md)\n- [One](/quest/m0/epic/one.md)\n\n" + - "## Related\n\n- [One](/quest/m0/epic/one.md) - similar\n", - ); + const tree = Tree.baseline().write( + "quest/m0/epic/three.md", + "# [S] Three\n\n## Goal\n\nMore.\n\n## Required\n\n- [Two](/quest/m0/epic/two.md)\n- [One](/quest/m0/epic/one.md)\n\n" + + "## Related\n\n- [One](/quest/m0/epic/one.md) - similar\n", + ); committed(tree); const out = await quest(tree, "rm", "quest/m0/epic/one.md"); expect(out).toEqual({ code: 0, - stdout: "D quest/m0/epic/one.md\nM quest/m0/epic/README.md\nM quest/m0/epic/three.md\nM quest/m0/epic/two.md\n", + stdout: "D quest/m0/epic/one.md\nM quest/m0/epic/three.md\nM quest/m0/epic/two.md\n", stderr: "", }); expect(tree.read("quest/m0/epic/two.md")).toBe("# [S] Two\n\n## Goal\n\nAnother quest.\n"); @@ -282,10 +291,9 @@ describe("quest rm", () => { tree.accepts(); }); - test("drops links to the milestone it finishes while the root still lists it", async () => { + test("drops links to the milestone it finishes", async () => { const tree = Tree.baseline() - .write("quest/README.md", `${ROOT_README}- [M1](/quest/m1/README.md)\n`) - .write("quest/m1/README.md", "# M1\n\n## Goal\n\nNext.\n\n## Required\n\n- [Later](/quest/m1/later.md)\n") + .write("quest/m1/README.md", "# M1\n\n## Goal\n\nNext.\n") .write( "quest/m1/later.md", "# [S] Later\n\n## Goal\n\nAfter m0.\n\n## Required\n\n- [M0](/quest/m0/README.md)\n", @@ -294,11 +302,9 @@ describe("quest rm", () => { const out = await quest(tree, "rm", "-r", "quest/m0/epic"); expect(out.code).toBe(0); expect(out.stdout).toBe( - "D quest/m0/epic/README.md\nD quest/m0/epic/one.md\nD quest/m0/epic/two.md\nM quest/m0/README.md\nM quest/m1/later.md\n", + "D quest/m0/epic/README.md\nD quest/m0/epic/one.md\nD quest/m0/epic/two.md\nM quest/m1/later.md\n", ); - expect(tree.read("quest/m0/README.md")).toBe("# M0\n\n## Goal\n\nA milestone.\n"); expect(tree.read("quest/m1/later.md")).toBe("# [S] Later\n\n## Goal\n\nAfter m0.\n"); - expect(tree.read("quest/README.md")).toContain("- [M0](/quest/m0/README.md)\n"); tree.accepts(); }); @@ -357,10 +363,7 @@ describe("quest check --fix", () => { async function diverged(change: (tree: Tree) => Promise | void): Promise { const tree = Tree.committed(); git(tree.path, "checkout", "-q", "-b", "feature"); - tree.append("quest/m0/epic/README.md", "- [Three](/quest/m0/epic/three.md)\n").write( - "quest/m0/epic/three.md", - THREE, - ); + tree.write("quest/m0/epic/three.md", THREE); git(tree.path, "add", "-A"); git(tree.path, "commit", "-q", "-m", "three"); git(tree.path, "checkout", "-q", "main"); @@ -407,7 +410,7 @@ describe("quest check --fix", () => { const out = await quest(tree, "check", "--fix"); expect(out.code).toBe(1); - expect(out.stdout).toBe("M quest/m0/epic/README.md\nM quest/m0/epic/second.md\nM quest/m0/epic/three.md\n"); + expect(out.stdout).toBe("M quest/m0/epic/second.md\nM quest/m0/epic/three.md\n"); expect(tree.read("quest/m0/epic/three.md").replaceAll("\r\n", "\n")).toBe( "# [S] Three\n\n## Goal\n\nMore.\n\n## Related\n\n- [Two](/quest/m0/epic/two.md) - similar\n" + "- [Nope](/quest/m0/epic/nope.md)\n\n## Plan\n\nAfter [one](/quest/m0/epic/one.md).\n", @@ -426,24 +429,45 @@ describe("quest check --fix", () => { git(repo, "commit", "-q", "-m", "finish one"); expect(await quest(tree, "check", "--fix")).toEqual({ code: 0, - stdout: "M quest/m0/epic/README.md\nM quest/m0/epic/two.md\nquest: 4 documents ok\n", + stdout: "M quest/m0/epic/two.md\nquest: 4 documents ok\n", stderr: "", }); }); test("refuses while a quest file has unresolved conflicts", async () => { const tree = await diverged((tree) => { - tree.write("quest/m0/epic/README.md", `${EPIC_README}- [Four](/quest/m0/epic/four.md)\n`); + tree.write("quest/m0/epic/three.md", "# [S] Three\n\n## Goal\n\nPlanned on main too.\n"); + git(tree.path, "add", "quest/m0/epic/three.md"); }); expect(spawnSync("git", ["-C", tree.path, "merge", "-q", "main"]).status).not.toBe(0); - const before = tree.read("quest/m0/epic/README.md"); + const before = tree.read("quest/m0/epic/three.md"); const out = await quest(tree, "check", "--fix"); expect(out).toEqual({ code: 1, stdout: "", - stderr: "quest: resolve the merge conflicts in quest/m0/epic/README.md before quest check --fix\n", + stderr: "quest: resolve the merge conflicts in quest/m0/epic/three.md before quest check --fix\n", + }); + expect(tree.read("quest/m0/epic/three.md")).toBe(before); + }); + + // Trees from before epics stopped listing their children migrate with one run. + test("strips the child lists of the root, milestones, and epics", async () => { + const tree = Tree.baseline() + .append("quest/README.md", "\n## Required\n\n- [M0](/quest/m0/README.md)\n") + .append("quest/m0/README.md", "\n## Required\n\n- [Epic](/quest/m0/epic/README.md)\n") + .append( + "quest/m0/epic/README.md", + "\n## Required\n\n- [One](/quest/m0/epic/one.md)\n- [Two](/quest/m0/epic/two.md)\n", + ); + committed(tree); + expect(await quest(tree, "check", "--fix")).toEqual({ + code: 0, + stdout: "M quest/README.md\nM quest/m0/README.md\nM quest/m0/epic/README.md\nquest: 5 documents ok\n", + stderr: "", }); - expect(tree.read("quest/m0/epic/README.md")).toBe(before); + expect(tree.read("quest/README.md")).toBe(ROOT_README); + expect(tree.read("quest/m0/README.md")).toBe(M0_README); + expect(tree.read("quest/m0/epic/README.md")).toBe(EPIC_README); }); test("fails outside a git work tree", async () => { diff --git a/test/theme.test.ts b/test/theme.test.ts index a5e27782..6ff8fc32 100644 --- a/test/theme.test.ts +++ b/test/theme.test.ts @@ -17,11 +17,7 @@ function sizes(): Tree { return new Tree() .write("quest/README.md", ROOT_README) .write("quest/m0/README.md", M0_README) - .write( - "quest/m0/epic/README.md", - "# Epic\n\n## Goal\n\nAn epic.\n\n## Required\n\n" + - ["xs", "s", "m", "l", "xl"].map((name) => `- [${name}](/quest/m0/epic/${name}.md)\n`).join(""), - ) + .write("quest/m0/epic/README.md", "# Epic\n\n## Goal\n\nAn epic.\n") .write("quest/m0/epic/xs.md", "# [XS] Tiny\n\n## Goal\n\nA quest.\n") .write("quest/m0/epic/s.md", "# [S] Small\n\n## Goal\n\nA quest.\n") .write("quest/m0/epic/m.md", "# [M] Medium\n\n## Goal\n\nA quest.\n") diff --git a/test/tree.test.ts b/test/tree.test.ts index 614cf8d1..54a067c5 100644 --- a/test/tree.test.ts +++ b/test/tree.test.ts @@ -12,7 +12,7 @@ import { basename } from "node:path"; import { describe, expect, test } from "vitest"; import { collect } from "../src/cli/tree"; -import { EPIC_README, ONE, TWO, Tree } from "./fixture"; +import { ONE, TWO, Tree } from "./fixture"; const tree = Tree.baseline; @@ -216,9 +216,9 @@ describe("headings", () => { }); }); -describe("index", () => { +describe("epics", () => { test("a quest and an epic cannot share a page and branch path", () => { - const t = tree().write("quest/m0/epic.md", ONE).append("quest/m0/README.md", "- [Quest](/quest/m0/epic.md)\n"); + const t = tree().write("quest/m0/epic.md", ONE); const finding = "quest/m0/epic.md: quest path collides with quest/m0/epic/README.md; rename one of these documents"; expect(t.findings()).toEqual([finding]); @@ -228,7 +228,6 @@ describe("index", () => { test("a collision persists after the epic's last child completes", () => { tree() .write("quest/m0/epic/one/README.md", ONE) - .append("quest/m0/epic/README.md", "- [Remaining epic](/quest/m0/epic/one/README.md)\n") .rejects("quest/m0/epic/one.md: quest path collides with quest/m0/epic/one/README.md"); }); @@ -238,7 +237,6 @@ describe("index", () => { test("a README-named directory collides with its parent README", () => { tree() .write("quest/m0/epic/README/README.md", ONE) - .append("quest/m0/epic/README.md", "- [Nested](/quest/m0/epic/README/README.md)\n") .rejects("quest/m0/epic/README.md: quest path collides with quest/m0/epic/README/README.md"); }); @@ -249,15 +247,21 @@ describe("index", () => { .rejects("quest/m0/epic/one/README.md: quest path collides with quest/m0/epic/one/README/two.md"); }); + // The directory is the epic's list of children: a new quest needs no link + // anywhere to be part of it. + test("a quest joins the epic whose directory holds it", () => { + const t = tree().write("quest/m0/epic/three.md", "# [S] Three\n\n## Goal\n\nA new child.\n"); + t.accepts(); + expect(t.ready()).toEqual(["quest/m0/epic/one.md", "quest/m0/epic/three.md"]); + }); + // A README whose last child merged is the epic's own remaining work: a leaf // quest, sized and listed as ready like any other. - test("a README without an index is a quest", () => { - const t = tree() - .write( - "quest/m0/epic/sub/README.md", - "# Sub\n\n## Goal\n\nThe end-to-end test once every child has merged.\n", - ) - .append("quest/m0/epic/README.md", "- [Sub](/quest/m0/epic/sub/README.md)\n"); + test("a README whose directory holds no other quest is a quest", () => { + const t = tree().write( + "quest/m0/epic/sub/README.md", + "# Sub\n\n## Goal\n\nThe end-to-end test once every child has merged.\n", + ); t.rejects("quest title must be"); t.write( "quest/m0/epic/sub/README.md", @@ -267,90 +271,84 @@ describe("index", () => { expect(t.ready()).toContain("quest/m0/epic/sub/README.md"); }); - // Completing an epic's last quest removes its heading with the entry, or - // deletes the directory. A bare `## Required` would block the husk forever. - test("an empty epic index", () => { - tree() - .write("quest/m0/husk/README.md", "# Husk\n\n## Goal\n\nIts last quest was completed.\n\n## Required\n") - .append("quest/m0/README.md", "- [Husk](/quest/m0/husk/README.md)\n") - .rejects("'## Required' is empty"); - }); - - // The absence of `## Required` means ready. A heading left behind by its last - // blocker reads as blocked to every readiness check, forever. + // Completing a quest's last blocker removes its heading with the entry. A + // bare `## Required` would block it forever. test("an empty Required section", () => { tree().append("quest/m0/epic/one.md", "\n## Required\n").rejects("'## Required' is empty"); - }); - - test("an unlisted quest", () => { tree() - .write("quest/m0/epic/three.md", "# [S] Three\n\n## Goal\n\nA quest nobody indexed.\n") - .rejects("not listed in quest/m0/epic/README.md's '## Required'"); + .write("quest/m0/husk/README.md", "# [S] Husk\n\n## Goal\n\nIts last blocker merged.\n\n## Required\n") + .rejects("'## Required' is empty"); }); - // Children are the entries that sit directly under the epic, so a milestone - // requiring a grandchild only waits on it; the epic still owns it. - test("requiring a grandchild is a blocker", () => { - const t = tree().append("quest/m0/README.md", "- [One](/quest/m0/epic/one.md)\n"); - t.accepts(); - expect(t.ready()).toEqual(["quest/m0/epic/one.md"]); + // Nothing above such a quest reaches it, so nothing would ever rank or + // render it. + test("a quest in a directory without a README", () => { + tree() + .write("quest/m0/loose/three.md", ONE) + .rejects( + "quest/m0/loose/three.md: sits in quest/m0/loose, which has no README.md; every directory under quest/ is an epic, so add its README or move the quest", + ); + tree() + .write("quest/m0/loose/deeper/README.md", ONE) + .rejects("quest/m0/loose/deeper/README.md: sits in quest/m0/loose, which has no README.md"); + }); + + // An epic already waits for everything in its directory, so a link to any of + // it is the child list this format retired; `quest check --fix` drops it. + test.each([ + ["quest/README.md", "/quest/m0/README.md"], + ["quest/m0/README.md", "/quest/m0/epic/README.md"], + ["quest/m0/README.md", "/quest/m0/epic/one.md"], + ["quest/m0/epic/README.md", "/quest/m0/epic/one.md"], + ])("%s requiring %s, which it holds", (readme, target) => { + const t = tree().append(readme, `\n## Required\n\n- [Held](${target})\n`); + expect(t.findings()).toHaveLength(1); + t.rejects( + `requires ${target}, which this epic holds; an epic waits for everything in its directory, so remove the entry (quest check --fix does)`, + ); }); - test("a quest listed twice", () => { + test("a quest required twice", () => { tree() - .append("quest/m0/epic/README.md", "- [One again](/quest/m0/epic/one.md)\n") + .append("quest/m0/epic/two.md", "- [One again](/quest/m0/epic/one.md)\n") .rejects("requires /quest/m0/epic/one.md twice"); }); - test("a relative index entry", () => { + test("a relative Required entry", () => { tree() - .write("quest/m0/epic/README.md", EPIC_README.replace("(/quest/m0/epic/one.md)", "(one.md)")) + .write("quest/m0/epic/two.md", TWO.replace("(/quest/m0/epic/one.md)", "(one.md)")) .rejects("link to a quest must be root-absolute: one.md"); }); // A target that merely exists is not enough: quest/AGENTS.md is a file under // quest/ that nothing can finish. - test("an index entry that is not a quest", () => { + test("a Required entry that is not a quest", () => { tree() .write("quest/AGENTS.md", "# Contract\n") - .append("quest/README.md", "- [Contract](/quest/AGENTS.md)\n") + .append("quest/m0/epic/two.md", "- [Contract](/quest/AGENTS.md)\n") .rejects("requires /quest/AGENTS.md, which is not a quest document"); }); - // The index is a list of entries, not prose that happens to link. - test("prose under the index", () => { - tree().append("quest/m0/epic/README.md", "\nSee also [One](/quest/m0/epic/one.md).\n").rejects("mid-sentence"); + // `Required` is a list of entries, not prose that happens to link. + test("prose under Required", () => { + tree().append("quest/m0/epic/two.md", "\nSee also [One](/quest/m0/epic/one.md).\n").rejects("mid-sentence"); }); - // A blocker outside the epic's directory is not a child, so a README holding - // only one is a quest and needs a size like any other. - test("an epic listing no quest", () => { + // A blocker is not a child, so a README holding only blockers is a quest + // and needs a size like any other. + test("a README with only blockers is a quest", () => { tree() .write( "quest/m0/husk/README.md", "# Husk\n\n## Goal\n\nIts last quest was completed.\n\n## Required\n\n- [One](/quest/m0/epic/one.md)\n", ) - .append("quest/m0/README.md", "- [Husk](/quest/m0/husk/README.md)\n") .rejects("quest title must be"); }); - // A LOOSE list - blank lines between entries - wraps every item in a - // paragraph. Treating that paragraph as text would classify every entry in - // the list as mid-sentence prose, which is a false positive on ordinary - // Markdown and would fire on every blocker and every index entry at once. - test("a loose index list", () => { - tree() - .write( - "quest/m0/epic/README.md", - "# Epic\n\n## Goal\n\nAn epic.\n\n## Required\n\n- [One](/quest/m0/epic/one.md)\n\n- [Two](/quest/m0/epic/two.md)\n", - ) - .accepts(); - }); - // A milestone with nothing left is not its own work, so it needs no size and // never lists as ready. test("a milestone may be empty", () => { - const t = tree().write("quest/m0/README.md", "# m0\n\n## Goal\n\nEmpty for now.\n").remove("quest/m0/epic"); + const t = tree().remove("quest/m0/epic"); t.accepts(); expect(t.ready()).toEqual([]); }); @@ -359,18 +357,11 @@ describe("index", () => { // Milestones are permanent, so a link to one keeps resolving after it // finishes. Check forces its removal; readiness stays a grep for the heading. describe("finished milestones", () => { - const EMPTY_M0 = "# M0\n\n## Goal\n\nA milestone.\n"; const GATE = "# [S] Gate\n\n## Goal\n\nRuns once m0 finishes.\n\n## Required\n\n- [M0](/quest/m0/README.md)\n"; /** The baseline plus m1, whose gate requires m0. */ const gated = () => - tree() - .append("quest/README.md", "- [M1](/quest/m1/README.md)\n") - .write( - "quest/m1/README.md", - "# M1\n\n## Goal\n\nThe next milestone.\n\n## Required\n\n- [Gate](/quest/m1/gate.md)\n", - ) - .write("quest/m1/gate.md", GATE); + tree().write("quest/m1/README.md", "# M1\n\n## Goal\n\nThe next milestone.\n").write("quest/m1/gate.md", GATE); test("a link to an open milestone blocks", () => { const t = gated(); @@ -379,7 +370,7 @@ describe("finished milestones", () => { }); test("a link to a finished milestone", () => { - const t = gated().write("quest/m0/README.md", EMPTY_M0).remove("quest/m0/epic"); + const t = gated().remove("quest/m0/epic"); expect(t.findings()).toEqual([ "quest/m1/gate.md:9: requires /quest/m0/README.md, a finished milestone; remove the link, and the '## Required' heading with its last entry", ]); @@ -387,22 +378,26 @@ describe("finished milestones", () => { }); // moq-dev/moq's m1 lists m0 quests: those blockers keep it open. - test("a milestone with only non-child blockers left is open", () => { + test("a milestone with only blockers left is open", () => { gated() - .write("quest/m0/README.md", `${EMPTY_M0}\n## Required\n\n- [Other](/quest/m1/other.md)\n`) + .append("quest/m0/README.md", "\n## Required\n\n- [Other](/quest/m1/other.md)\n") .remove("quest/m0/epic") .write("quest/m1/other.md", "# [S] Other\n\n## Goal\n\nOpen work m0 waits on.\n") - .append("quest/m1/README.md", "- [Other](/quest/m1/other.md)\n") .accepts(); }); - test("the root's listing of a finished milestone is membership", () => { - tree().write("quest/m0/README.md", EMPTY_M0).remove("quest/m0/epic").accepts(); + // The root holds every milestone, so its link to one is that finding alone. + test("the root's link to a finished milestone is one finding", () => { + const t = tree() + .append("quest/README.md", "\n## Required\n\n- [M0](/quest/m0/README.md)\n") + .remove("quest/m0/epic"); + expect(t.findings()).toEqual([ + "quest/README.md:9: requires /quest/m0/README.md, which this epic holds; an epic waits for everything in its directory, so remove the entry (quest check --fix does)", + ]); }); test("removing the link readies the quest", () => { const t = gated() - .write("quest/m0/README.md", EMPTY_M0) .remove("quest/m0/epic") .write("quest/m1/gate.md", "# [S] Gate\n\n## Goal\n\nRuns once m0 finishes.\n"); t.accepts(); @@ -424,12 +419,10 @@ describe("Required", () => { // only thing that can close it. test("a cycle through an epic", () => { tree() - .append("quest/m0/README.md", "- [Outer](/quest/m0/outer.md)\n") .write( "quest/m0/outer.md", "# [S] Outer\n\n## Goal\n\nBlocked on a whole epic.\n\n## Required\n\n- [Epic](/quest/m0/epic/README.md) - the whole epic must finish\n", ) - .append("quest/m0/epic/README.md", "- [Three](/quest/m0/epic/three.md)\n") .write( "quest/m0/epic/three.md", "# [S] Three\n\n## Goal\n\nInside the epic that blocks it.\n\n## Required\n\n- [Outer](/quest/m0/outer.md) - must finish first\n", @@ -582,12 +575,10 @@ describe("ready", () => { // useful answer is which of its quests are still open - all of them, since a // completed quest is deleted. test("blocked by an epic", () => { - const t = tree() - .append("quest/m0/README.md", "- [Outer](/quest/m0/outer.md)\n") - .write( - "quest/m0/outer.md", - "# [S] Outer\n\n## Goal\n\nBlocked on a whole epic.\n\n## Required\n\n- [Epic](/quest/m0/epic/README.md) - the whole epic must finish\n", - ); + const t = tree().write( + "quest/m0/outer.md", + "# [S] Outer\n\n## Goal\n\nBlocked on a whole epic.\n\n## Required\n\n- [Epic](/quest/m0/epic/README.md) - the whole epic must finish\n", + ); expect(t.blockers("quest/m0/outer.md")).toEqual([ "quest/m0/epic/README.md", " quest/m0/epic/one.md", @@ -599,12 +590,10 @@ describe("ready", () => { // running this on it is how you ask. Expanding buried the entries that were // asked for under a subtree repeated once per path through it. test("a required quest is not expanded", () => { - const t = tree() - .append("quest/m0/epic/README.md", "- [Three](/quest/m0/epic/three.md)\n") - .write( - "quest/m0/epic/three.md", - "# [S] Three\n\n## Goal\n\nLast in the chain.\n\n## Required\n\n- [Two](/quest/m0/epic/two.md) - must finish first\n", - ); + const t = tree().write( + "quest/m0/epic/three.md", + "# [S] Three\n\n## Goal\n\nLast in the chain.\n\n## Required\n\n- [Two](/quest/m0/epic/two.md) - must finish first\n", + ); expect(t.blockers("quest/m0/epic/three.md")).toEqual(["quest/m0/epic/two.md"]); }); @@ -619,15 +608,12 @@ describe("ready", () => { }); // The listing is the query the start flow reproduces by grepping. An - // epic is absent while it still indexes children, and `two.md` is + // epic is absent while its directory holds other quests, and `two.md` is // blocked. test("the listing", () => { const t = tree(); expect(t.ready()).toEqual(["quest/m0/epic/one.md"]); - t.append("quest/m0/README.md", "- [Outer](/quest/m0/outer.md)\n").write( - "quest/m0/outer.md", - "# [S] Outer\n\n## Goal\n\nReady too.\n", - ); + t.write("quest/m0/outer.md", "# [S] Outer\n\n## Goal\n\nReady too.\n"); expect(t.ready()).toEqual(["quest/m0/epic/one.md", "quest/m0/outer.md"]); }); @@ -636,38 +622,36 @@ describe("ready", () => { // cycle there has to print rather than recurse forever. test("a cycle terminates", () => { const t = tree() - .append("quest/m0/epic/README.md", "- [Itself](/quest/m0/epic/README.md)\n") - .append("quest/m0/README.md", "- [Outer](/quest/m0/outer.md)\n") + .append("quest/m0/epic/README.md", "\n## Required\n\n- [Itself](/quest/m0/epic/README.md)\n") .write( "quest/m0/outer.md", - "# [S] Outer\n\n## Goal\n\nBlocked on an epic that lists itself.\n\n## Required\n\n- [Epic](/quest/m0/epic/README.md) - the whole epic must finish\n", + "# [S] Outer\n\n## Goal\n\nBlocked on an epic that requires itself.\n\n## Required\n\n- [Epic](/quest/m0/epic/README.md) - the whole epic must finish\n", ); expect(t.blockers("quest/m0/outer.md")).toEqual([ "quest/m0/epic/README.md", + " quest/m0/epic/README.md", " quest/m0/epic/one.md", " quest/m0/epic/two.md", - " quest/m0/epic/README.md", ]); }); - test("the listing follows nested priority and terminates cycles", () => { + // Path order: an epic before its children, and milestone numbers by value. + test("the listing is in path order", () => { const t = tree() .write("quest/m0/epic/two.md", "# [S] Two\n\n## Goal\n\nReady.\n") - .write( - "quest/m0/epic/README.md", - "# Epic\n\n## Required\n\n- [Two](/quest/m0/epic/two.md)\n- [Self](/quest/m0/epic/README.md)\n- [One](/quest/m0/epic/one.md)\n", - ); - expect(t.ready()).toEqual(["quest/m0/epic/two.md", "quest/m0/epic/one.md"]); - }); - - test("the listing appends unindexed quests", () => { - const t = tree() - .write("quest/m0/aaa.md", "# [S] Unindexed\n\n## Goal\n\nDiscover me.\n") - .write( - "quest/m0/blocked.md", - "# [S] Blocked\n\n## Goal\n\nWait.\n\n## Required\n\n- [One](/quest/m0/epic/one.md)\n", - ); - expect(t.ready()).toEqual(["quest/m0/epic/one.md", "quest/m0/aaa.md"]); + .write("quest/m0/aaa.md", "# [S] First\n\n## Goal\n\nSorts before the epic.\n") + .write("quest/m10/README.md", "# M10\n\n## Goal\n\nLater.\n") + .write("quest/m10/one.md", ONE) + .write("quest/m2/README.md", "# M2\n\n## Goal\n\nSooner.\n") + .write("quest/m2/one.md", ONE); + t.accepts(); + expect(t.ready()).toEqual([ + "quest/m0/aaa.md", + "quest/m0/epic/one.md", + "quest/m0/epic/two.md", + "quest/m2/one.md", + "quest/m10/one.md", + ]); }); }); diff --git a/test/unblocked.test.ts b/test/unblocked.test.ts index 48bd144e..5a3cfef5 100644 --- a/test/unblocked.test.ts +++ b/test/unblocked.test.ts @@ -2,32 +2,21 @@ import { expect, test } from "vitest"; import { type Doc, owner, parse, ready, unblocked } from "../src/core"; -/** A valid indexed tree, with insertion order defining each epic's priorities. */ +/** A valid tree: each spec quest with its blockers, and the READMEs its directories need as epics. */ function graph(spec: Record, milestones = ["m0"]): Doc[] { - const index = new Map([ - ["quest/README.md", milestones.map((name) => `quest/${name}/README.md`)], - ...milestones.map((name) => [`quest/${name}/README.md`, []] as [string, string[]]), - ]); - const add = (path: string) => { - if (path === "quest/README.md") return; - const parent = `${owner(path)}/README.md`; - if (!index.has(parent)) { - index.set(parent, []); - add(parent); + const epics = new Set(["quest/README.md", ...milestones.map((name) => `quest/${name}/README.md`)]); + for (const name of Object.keys(spec)) { + for (let path = `quest/${name}`; path !== "quest/README.md";) { + path = `${owner(path)}/README.md`; + epics.add(path); } - const children = index.get(parent)!; - if (!children.includes(path)) children.push(path); - }; - for (const name of Object.keys(spec)) add(`quest/${name}`); - const paths = new Set([...index.keys(), ...Object.keys(spec).map((name) => `quest/${name}`)]); + } + const paths = new Set([...epics, ...Object.keys(spec).map((name) => `quest/${name}`)]); return [...paths].map((path) => { - const dependencies = [ - ...(index.get(path) ?? []), - ...(spec[path.slice(6)] ?? []).map((name) => `quest/${name}`), - ]; + const dependencies = (spec[path.slice(6)] ?? []).map((name) => `quest/${name}`); return parse( path, - `# ${index.has(path) ? "Epic" : "[S] Work"}\n\n## Goal\n\nWork.\n` + + `# ${epics.has(path) ? "Epic" : "[S] Work"}\n\n## Goal\n\nWork.\n` + (dependencies.length ? `\n## Required\n\n${dependencies.map((dep) => `- [Work](/${dep})`).join("\n")}\n` : ""), @@ -37,7 +26,7 @@ function graph(spec: Record, milestones = ["m0"]): Doc[] { test("ranks chains ahead of zero-impact work without changing ready", () => { const docs = graph({ "m0/zero.md": [], "m0/a.md": [], "m0/b.md": ["m0/a.md"], "m0/c.md": ["m0/b.md"] }); - expect(ready(docs)).toEqual(["quest/m0/zero.md", "quest/m0/a.md"]); + expect(ready(docs)).toEqual(["quest/m0/a.md", "quest/m0/zero.md"]); expect(unblocked(docs)).toEqual([ { path: "quest/m0/a.md", dependents: 2 }, { path: "quest/m0/zero.md", dependents: 0 }, @@ -86,7 +75,7 @@ test("retains an epic's real prerequisites alongside its children", () => { ]); }); -test("root milestone order wins over impact, counting later-milestone dependents", () => { +test("milestone order wins over impact, counting later-milestone dependents", () => { const docs = graph( { "m0/early.md": [], @@ -102,17 +91,18 @@ test("root milestone order wins over impact, counting later-milestone dependents { path: "quest/m1/later.md", dependents: 2 }, ]); expect(unblocked(docs.slice().reverse())).toEqual(unblocked(docs)); - const reordered = graph({ "m0/a.md": [], "m1/b.md": [] }, ["m1", "m0"]); - expect(unblocked(reordered).map((quest) => quest.path)).toEqual(["quest/m1/b.md", "quest/m0/a.md"]); + // Milestones rank in path order, which compares their numbers by value. + const numbered = graph({ "m10/a.md": [], "m2/b.md": [] }, ["m10", "m2"]); + expect(unblocked(numbered).map((quest) => quest.path)).toEqual(["quest/m2/b.md", "quest/m10/a.md"]); }); -test("breaks ties in existing tree order and treats a completed epic as work", () => { +test("breaks ties in path order and treats a completed epic as work", () => { const docs = graph({ "m0/z.md": [], "m0/finished/README.md": [], "m0/a.md": [] }); expect(unblocked(docs)).toEqual(ready(docs).map((path) => ({ path, dependents: 0 }))); expect(unblocked(docs).map((quest) => quest.path)).toEqual([ - "quest/m0/z.md", - "quest/m0/finished/README.md", "quest/m0/a.md", + "quest/m0/finished/README.md", + "quest/m0/z.md", ]); }); diff --git a/test/waiting.test.ts b/test/waiting.test.ts index 647dd66e..8d75553a 100644 --- a/test/waiting.test.ts +++ b/test/waiting.test.ts @@ -12,25 +12,15 @@ import { withoutHandBack, } from "../src/core"; -const ROOT = "# Quests\n\n## Goal\n\nAll.\n\n## Required\n\n- [m0](/quest/m0/README.md)\n- [m1](/quest/m1/README.md)\n"; - -/** A tree of two milestones, each listing its quests. */ +/** A tree of two milestones and their quests. */ function tree(m0: Record, m1: Record = {}): Doc[] { const milestone = (name: string, quests: Record) => [ - parse( - `quest/${name}/README.md`, - `# ${name}\n\n## Goal\n\nWork.\n` + - (Object.keys(quests).length - ? `\n## Required\n\n${Object.keys(quests) - .map((q) => `- [${q}](/quest/${name}/${q})`) - .join("\n")}\n` - : ""), - ), + parse(`quest/${name}/README.md`, `# ${name}\n\n## Goal\n\nWork.\n`), ...Object.entries(quests).map(([q, body]) => parse(`quest/${name}/${q}`, `# [S] ${q}\n\n## Goal\n\nWork.\n${body}`), ), ]; - return [parse("quest/README.md", ROOT), ...milestone("m0", m0), ...milestone("m1", m1)]; + return [parse("quest/README.md", "# Quests\n\n## Goal\n\nAll.\n"), ...milestone("m0", m0), ...milestone("m1", m1)]; } test("a wait opens with its party", () => { @@ -83,14 +73,13 @@ test("lists the maintainer's waits first, then by milestone and impact", () => { ]); }); -test("ties keep the tree's priority order, as unblocked does", () => { - // The CLI loads documents by path, so a.md comes first. +test("ties keep path order, as unblocked does", () => { const docs = tree({ "z.md": "\n## Waiting\n\n- Maintainer: pick one.\n", "a.md": "\n## Waiting\n\n- Maintainer: pick another.\n", - }).sort((x, y) => x.path.localeCompare(y.path)); - expect(unblocked(docs).map((quest) => quest.path)).toEqual(["quest/m0/z.md", "quest/m0/a.md"]); - expect(waiting(docs).map((quest) => quest.path)).toEqual(["quest/m0/z.md", "quest/m0/a.md"]); + }); + expect(unblocked(docs).map((quest) => quest.path)).toEqual(["quest/m0/a.md", "quest/m0/z.md"]); + expect(waiting(docs).map((quest) => quest.path)).toEqual(["quest/m0/a.md", "quest/m0/z.md"]); }); test("a draft hands back with Waiting, or the Decisions needed heading it replaced", () => { From 73af3ae1a6046de6a2d16b4bd55bece0caa0d44a Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 5 Nov 2026 15:03:18 -0800 Subject: [PATCH 3/6] fix(edit): strip only an epic's links to quests that exist A README's `Required` link to a mistyped path inside its own directory is a mistake for `quest check` to report, not a child link for `--fix` to drop. Co-Authored-By: Claude Opus 5.5 --- src/core/edit.ts | 3 ++- test/move.test.ts | 12 +++++++++--- 2 files changed, 11 insertions(+), 4 deletions(-) diff --git a/src/core/edit.ts b/src/core/edit.ts index b1bd6b16..3c7f94cc 100644 --- a/src/core/edit.ts +++ b/src/core/edit.ts @@ -85,9 +85,10 @@ export function remove(sources: Source[], deleted: (path: string) => boolean): M const path = target(entry); return path !== null && deleted(path); }; + // Only a quest that exists is held: a mistyped link stays for `quest check` to report. const held = (doc: Doc, entry: Entry) => { const path = target(entry); - return entry.section === "Required" && path !== null && holds(doc.path, path); + return entry.section === "Required" && path !== null && texts.has(path) && holds(doc.path, path); }; for (let progress = true; progress;) { progress = false; diff --git a/test/move.test.ts b/test/move.test.ts index 895719b8..715abd2d 100644 --- a/test/move.test.ts +++ b/test/move.test.ts @@ -147,22 +147,28 @@ describe("remove", () => { }); // An epic waits for everything in its directory, so its links to those quests - // are the child lists this format retired. A sibling's link is a real blocker. + // are the child lists this format retired. A sibling's link is a real blocker, + // and a link to no quest is a mistake for the check to report. test("drops an epic's Required links to quests it holds, at any depth", () => { const readme = "# Epic\n\n## Goal\n\nG.\n\n## Required\n\n- [A](/quest/m0/epic/a.md)\n" + - "- [Outside](/quest/m0/outside.md)\n- [Deep](/quest/m0/epic/sub/deep.md)\n\n## Related\n\n- [A](/quest/m0/epic/a.md)\n"; + "- [Outside](/quest/m0/outside.md)\n- [Deep](/quest/m0/epic/sub/deep.md)\n- [Typo](/quest/m0/epic/typo.md)\n\n" + + "## Related\n\n- [A](/quest/m0/epic/a.md)\n"; const sibling = "# [S] B\n\n## Goal\n\nG.\n\n## Required\n\n- [A](/quest/m0/epic/a.md)\n"; + const quest = (title: string) => `# [S] ${title}\n\n## Goal\n\nG.\n`; const texts = remove( [ { path: "quest/m0/epic/README.md", text: readme }, + { path: "quest/m0/epic/a.md", text: quest("A") }, { path: "quest/m0/epic/b.md", text: sibling }, + { path: "quest/m0/epic/sub/deep.md", text: quest("Deep") }, ], () => false, ); expect([...texts.keys()]).toEqual(["quest/m0/epic/README.md"]); expect(texts.get("quest/m0/epic/README.md")).toBe( - "# Epic\n\n## Goal\n\nG.\n\n## Required\n\n- [Outside](/quest/m0/outside.md)\n\n## Related\n\n- [A](/quest/m0/epic/a.md)\n", + "# Epic\n\n## Goal\n\nG.\n\n## Required\n\n- [Outside](/quest/m0/outside.md)\n- [Typo](/quest/m0/epic/typo.md)\n\n" + + "## Related\n\n- [A](/quest/m0/epic/a.md)\n", ); }); }); From c5065a293b83efa0dd8985e5f07538d99e76eee2 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 7 Nov 2026 10:55:06 -0800 Subject: [PATCH 4/6] fix: accept both tree formats so base's CLI passes the merge The merge queue checks a PR with the CLI built from its base, which rejects a tree whose epics no longer list their children. Stage the change: this PR ships directory membership with a validator that accepts an epic's Required link to a quest it holds, counting it once as a child, and keeps this tree's child lists. Removing held links and enforcing their absence move to the follow-up that migrates the tree. Co-Authored-By: Claude Opus 5.5 --- README.md | 7 ++-- assets/land-fix.md | 5 +-- quest/README.md | 6 ++++ quest/m0/README.md | 27 +++++++++++++-- quest/m0/flaky/README.md | 4 +++ quest/m0/kix/README.md | 8 +++++ quest/m0/kix/sandbox/README.md | 5 +++ quest/m0/model-check.md | 3 +- quest/m0/model-routing/README.md | 6 ++++ quest/m0/model-routing/pins.md | 8 +++-- quest/m0/queue-watcher/README.md | 12 +++++++ quest/m0/queue-watcher/flaky-quest.md | 10 +++--- quest/m0/token-waste/README.md | 8 +++++ quest/m0/token-waste/child-lists.md | 44 +++++++++++++++++++++++ quest/m0/user-dev-shell/README.md | 5 +++ quest/m1/README.md | 14 ++++++++ quest/m1/kix/README.md | 5 +++ quest/m1/kix/sandbox/README.md | 5 +++ quest/m1/theme/README.md | 7 +++- quest/m2/README.md | 14 ++++++++ quest/m2/automation/README.md | 6 ++++ quest/m2/cloud/README.md | 7 ++++ src/cli/main.ts | 13 ++++--- src/cli/move.ts | 45 +++++++++++------------- src/core/doc.ts | 8 +++-- src/core/edit.ts | 25 ++++---------- src/core/ready.ts | 4 ++- src/core/rules.ts | 16 +++------ src/core/unblocked.ts | 8 +++-- test/move.test.ts | 50 ++++++++------------------- test/tree.test.ts | 25 ++++++-------- test/unblocked.test.ts | 6 ++++ 32 files changed, 281 insertions(+), 135 deletions(-) create mode 100644 quest/m0/token-waste/child-lists.md diff --git a/README.md b/README.md index 92a3b762..511dcb17 100644 --- a/README.md +++ b/README.md @@ -284,7 +284,7 @@ quest rm -r quest/m1/drain under a moved epic. `rm` drops each `Required`, `Related`, or `Closes` entry that links to what it deleted, and the heading if that was the last entry. It also drops every `Required` link to a finished milestone, including one it -just finished, and every epic's `Required` link to a quest in its own folder. +just finished, but keeps the root's listing of the milestone. Both stage the change, print one line per file (`R from -> to`, `D path`, or `M path`), and report on stderr any other mention of the path, such as prose or files outside `quest/`, without editing it. They run `quest check` on the @@ -331,10 +331,7 @@ A clean merge can still leave this branch's list links to quests the base finished, which `quest check` then flags. `quest check --fix` drops every `Required`, `Related`, or `Closes` entry linking to a quest deleted in the history of `HEAD`, and of `MERGE_HEAD` during a merge, that the working tree -lacks, and every epic's `Required` entry naming a quest in its own folder, -which the epic already waits for, and prints `M path` for each edited -document. That last part also migrates a tree from before epics stopped -listing their children. It leaves the edits +lacks, and prints `M path` for each edited document. It leaves the edits unstaged and refuses while a quest file has unresolved conflicts. A quest moved rather than deleted, a link that never named a quest, and a link in prose stay for `quest check` to report. diff --git a/assets/land-fix.md b/assets/land-fix.md index 4940c260..8e4066bf 100644 --- a/assets/land-fix.md +++ b/assets/land-fix.md @@ -169,8 +169,9 @@ commit on it only - that follow-up quest, `quest/m0/flaky/.md`, with `` the test's name in lowercase kebab-case, whose Goal says to fix the test or delete it and links each listed job and this failure's, which the failure log names; -- `quest/m0/flaky/README.md`, the epic holding one quest per disabled test, - if it is missing. +- its link in the `Required` list of `quest/m0/flaky/README.md`, the epic + holding one quest per disabled test, created with a link in + `quest/m0/README.md`'s `Required` if it is missing. Follow the repository's quest format, and run `quest check` when the repository has it. A disabled test that is another quest's acceptance test diff --git a/quest/README.md b/quest/README.md index 228412cf..05a03a75 100644 --- a/quest/README.md +++ b/quest/README.md @@ -10,3 +10,9 @@ versioned Markdown, with a standalone CLI and a reversible adoption path. `m0` is adoption on moq-dev's own repositories, `m1` the public release, and `m2` later work. Add later horizons when concrete work warrants them, keeping milestone numbers stable as earlier milestones complete. + +## Required + +- [M0: moq-dev adoption](/quest/m0/README.md) - kix at quest.moq.dev, used daily on moq-dev/moq, moq-dev/quest, and moq-dev/moq.pro, beside the standalone CLI +- [M1: Public release](/quest/m1/README.md) - kix.quest open to any maintainer, with onboarding, contributor sandboxing, the themed site, and launch material +- [M2: Later work](/quest/m2/README.md) - cloud runners, a native mobile app, shared runners, and donated reviews and CI diff --git a/quest/m0/README.md b/quest/m0/README.md index 18356895..ac8ce4b8 100644 --- a/quest/m0/README.md +++ b/quest/m0/README.md @@ -52,9 +52,9 @@ Decided 2026-10-30 (user, /quest-plan), replacing "First public release": The land work is what moq-dev's repositories use every day, and the maintainer ranked it first in the 2026-10-30 and 2026-11-01 sessions. Superseded 2026-11-05 (user, /quest-plan, the - [token waste](/quest/m0/token-waste/README.md) audit): epics no longer - list their children, so no list ranks work within m0; `quest unblocked` - ranks by milestone, then downstream impact, then path. + [token waste](/quest/m0/token-waste/README.md) audit): an epic's children + are its directory, so list order no longer ranks work within m0; + `quest unblocked` ranks by milestone, then downstream impact, then path. - How do moq-dev's repositories land? Decided 2026-11-01 (maintainer, /quest-plan), reversing the 2026-10-26 move to a batched gate: - ✅ Through GitHub's merge queue again, one PR at a time, with no batching @@ -91,3 +91,24 @@ ownership-manifest design: limits). Prefer offline, deterministic commands, and keep GitHub calls in the CLI rather than skill prose. - Repository-specific rules stay in the repository's own root instructions. + +## Required + +- [Fix disabled flaky tests](/quest/m0/flaky/README.md) - fix or delete each disabled test + +- [Land through a serial merge queue with an async fixer](/quest/m0/queue-watcher/README.md) - GitHub's merge queue, or the watcher's own where GitHub has none, lands one PR at a time, and a host watcher fixes and re-enqueues each PR it drops +- [Merge through a host gate](/quest/m0/host-land/README.md) - the host's fixer containers, and the frozen batched gate for moq.pro until it switches, with merge-commit landing as its one exception +- [The land fixer resolves every mechanical failure](/quest/m0/land-fixer/README.md) - the docs listing what the fixer resolves and hands back +- [Review sessions keyed by upstream branch](/quest/m0/review-session-key.md) - a round from a local branch tracking the PR branch continues that branch's review session +- [Kix decision UI](/quest/m0/kix/README.md) - planning and implementation through prompts and summaries, run on the maintainer's own runners +- [Route quests to models by size](/quest/m0/model-routing/README.md) - `/quest-spawn` starts each quest on the first model of its size's ranked list that can run, reviews rank the same way, and PRs record size, implementer, and reviewer +- [Repositories and hosts follow quest's main](/quest/m0/pin-sync.md) - every push to main reaches each enrolled repository and host through a bot-queued pin bump +- [Cut agent token waste](/quest/m0/token-waste/README.md) - sessions stop paying for loading rules, a second review pass, polling, oversized coordinators, and merge churn +- [quest check rejects a misleveled Waiting heading](/quest/m0/waiting-heading-level.md) - a `### Waiting` (or any non-`##` level) fails `quest check` with its file and line, so no wait drops out of `quest waiting` +- [Model check](/quest/m0/model-check.md) - recurring: the first audit of the routed PRs retunes the built-in size lists +- [Codex cloud off](/quest/m0/codex-cloud-off.md) - automatic Codex cloud reviews stop once no open PR relies on them +- [Codex project-config skip](/quest/m0/codex-project-config.md) - once Codex keeps a supported way to skip a project's `.codex/` layer, reviews keep the user's config +- [Agents get the dev shell from user settings](/quest/m0/user-dev-shell/README.md) - maintainers' own Claude and Codex settings load the dev shell; repositories drop dev-shell hooks, Quest worktree hooks, and `nix develop` instructions, and `quest init` writes no hooks +- [Session checkouts released](/quest/m0/session-checkouts.md) - a Claude session's own checkout is released when the session ends and reclaimed on resume +- [claude rm upstream report](/quest/m0/claude-rm-upstream.md) - posting approved: ask Claude Code to run `WorktreeRemove` instead of advising an unlock +- [Three generic rules in the shared context](/quest/m0/context-rules.md) - `quest context` adds matching conventions, never loosening a flaky test, and short names under a namespace diff --git a/quest/m0/flaky/README.md b/quest/m0/flaky/README.md index 4692a93f..b8f4d5bf 100644 --- a/quest/m0/flaky/README.md +++ b/quest/m0/flaky/README.md @@ -4,3 +4,7 @@ Each disabled flaky test is fixed or deleted, with its skip removed when fixed. Each required quest records the failures that led to the skip. + +## Required + +- [Fix the reviewer usage-limit test](/quest/m0/flaky/a-reviewers-usage-limit-exits-3-with-its-reset-and-records-no-round.md) - fix or delete the test disabled after repeated timeouts diff --git a/quest/m0/kix/README.md b/quest/m0/kix/README.md index ba76f415..56e1a35c 100644 --- a/quest/m0/kix/README.md +++ b/quest/m0/kix/README.md @@ -136,3 +136,11 @@ fixes what it finds: [moq-dev/quest#209](https://github.com/moq-dev/quest/pull/209) assumes is the comparison GitHub makes. Try it with a real PR that edits a workflow (decided 2026-10-24, user). + +## Required + +- [Operator setup](/quest/m0/kix/operator-setup.md) - pilot installations and a verified test PR on moq-dev/moq and moq-dev/quest +- [Private repositories](/quest/m0/kix/private.md) - moq-dev/moq.pro enrolls, visible only to signed-in users who can read it +- [Job sandbox](/quest/m0/kix/sandbox/README.md) - head approval for kix-pushed heads, and opencode sandboxed +- [Runner account pool](/quest/m0/kix/cliproxy.md) - the runner routes every Claude and Codex job and review through its own CLIProxyAPI pool +- [Web execution](/quest/m0/kix/execution.md) - spawn and iterate through the UI, ending in contribution PRs diff --git a/quest/m0/kix/sandbox/README.md b/quest/m0/kix/sandbox/README.md index d5f0140d..44dea2e1 100644 --- a/quest/m0/kix/sandbox/README.md +++ b/quest/m0/kix/sandbox/README.md @@ -89,3 +89,8 @@ Shipped in [moq-dev/quest#212](https://github.com/moq-dev/quest/pull/212) - Sources: [Claude Code sandboxing](https://code.claude.com/docs/en/sandboxing) and [sandbox-runtime](https://www.npmjs.com/package/@anthropic-ai/sandbox-runtime). + +## Required + +- [Per-job opencode saved output](/quest/m0/kix/sandbox/opencode-data.md) - each opencode job saves its tool output and shell captures beside its checkout, so no job reads another's, while sessions and the credential stay in the account's database +- [Claude Code boundary test](/quest/m0/kix/sandbox/claude-boundary.md) - the same hostile-repository test for Claude Code jobs, with a fake model set in the account's settings diff --git a/quest/m0/model-check.md b/quest/m0/model-check.md index f134fdef..30bd6774 100644 --- a/quest/m0/model-check.md +++ b/quest/m0/model-check.md @@ -27,7 +27,8 @@ run is in m0 once routing lands, then each milestone. compare findings per round by effort across the routed PRs, with the misses later rounds, CI, or follow-ups found, and recommend restoring a higher effort where a lower one misses findings. -- m1's run already exists in [m1](/quest/m1/README.md), requiring m0. The PR that finishes this run creates no new run: it +- m1's run already exists, listed in [m1](/quest/m1/README.md)'s `Required` + and requiring m0. The PR that finishes this run creates no new run: it carries the tallies and any table changes into m1's Plan as its baseline. ## Required diff --git a/quest/m0/model-routing/README.md b/quest/m0/model-routing/README.md index 73ca040a..a5f83f07 100644 --- a/quest/m0/model-routing/README.md +++ b/quest/m0/model-routing/README.md @@ -91,3 +91,9 @@ are mostly judgment. [Route by size](/quest/m0/model-routing/models.md). - Which milestone? ✅ m0 (rejected: m1). It ranks first among m0's work after Kix, by the 2026-11-01 order: land work, then Kix, then the rest. + +## Required + +- [Route by size](/quest/m0/model-routing/models.md) - `/quest-spawn` and iterate dispatches start on the first entry of the size's ranked list that can run, an iterate sized by its remaining work +- [kix records its follow-up sessions](/quest/m0/model-routing/kix-sessions.md) - kix `iterate` and `merge` jobs that change an existing PR record their `Implementer:` line in a PR comment +- [moq-dev pins](/quest/m0/model-routing/pins.md) - moq-dev/moq and moq-dev/moq.pro bump their `quest` pin to pick up the routing diff --git a/quest/m0/model-routing/pins.md b/quest/m0/model-routing/pins.md index c60111e5..00440584 100644 --- a/quest/m0/model-routing/pins.md +++ b/quest/m0/model-routing/pins.md @@ -18,9 +18,11 @@ repository uses the same settings, so nothing in them changes but the pin. - Neither repository's `AGENTS.md` overrides the tables. - Each bump runs `quest check --fix` with the new `quest` and commits the result, since a `quest` past - [moq-dev/quest#518](https://github.com/moq-dev/quest/pull/518) rejects - epic READMEs that still list their children (coordinator, 2026-11-05, - follow-up of #518; [Pin sync](/quest/m0/pin-sync.md) does the same for + [Epics list no children](/quest/m0/token-waste/child-lists.md) rejects + epic READMEs that still list their children, and its `--fix` strips them + (coordinator, 2026-11-05, follow-up of + [moq-dev/quest#518](https://github.com/moq-dev/quest/pull/518), which + accepts both formats; [Pin sync](/quest/m0/pin-sync.md) does the same for its automated bumps). ## Required diff --git a/quest/m0/queue-watcher/README.md b/quest/m0/queue-watcher/README.md index b40233a9..4e2a0d8a 100644 --- a/quest/m0/queue-watcher/README.md +++ b/quest/m0/queue-watcher/README.md @@ -146,6 +146,18 @@ Shared shape, for the children to follow: lets them admit ahead of agent load, set from moq's workflow or the runner's environment. +## Required + +- [The other repositories follow](/quest/m0/queue-watcher/follow.md) - quest, rind and rust2 are cut over and landing; waits for a fork PR to land through one of their queues +- [Harden the queue runners](/quest/m0/queue-watcher/runners.md) - each queue runner runs only its repository's queue workflow, and every outside fork PR needs approval +- [Tests fit their timeout on the queue runner](/quest/m0/queue-watcher/queue-test-timeouts.md) - the root and Worker suites stop timing out or stalling in merge-group runs, so the queue stops ejecting PRs for them +- [The watcher writes flaky quests](/quest/m0/queue-watcher/flaky-quest.md) - a disable's follow-up quest comes from a template in `quest land watch`, so the headless land fixer writes no quest +- [Daemons prune their logs](/quest/m0/queue-watcher/log-retention.md) - the watcher and gate delete their finished logs after a window, so state stays bounded (4.1 GiB on nixos on 2026-11-04) +- [The watcher runs its own serial queue](/quest/m0/queue-watcher/own-queue.md) - `quest land watch` lands a base without GitHub's merge queue, testing one pick at a time in the repository's queue workflow +- [moq.pro lands main through the own queue](/quest/m0/queue-watcher/pro-cutover.md) - moq.pro's `main` leaves the batching gate for the watcher's own queue +- [Retire the batching gate](/quest/m0/queue-watcher/retire.md) - once no repository lands through `quest land serve`, its batching code and host units go +- [kix.quest shows each repository's landing queue](/quest/m0/queue-watcher/queue-page.md) - one page per repository with its queue order, current build, and recent drops, in both modes + ## Related - [The land fixer](/quest/m0/land-fixer/README.md) - the fixer the watcher runs diff --git a/quest/m0/queue-watcher/flaky-quest.md b/quest/m0/queue-watcher/flaky-quest.md index 89b5a310..4d3c9f57 100644 --- a/quest/m0/queue-watcher/flaky-quest.md +++ b/quest/m0/queue-watcher/flaky-quest.md @@ -15,8 +15,8 @@ only by a coordinator (`/quest-complete`, `/quest-spawn`) on Opus, never by a sub-agent. The skills already follow it: only `/quest-merge` and `/quest-complete` plan follow-ups, and `/quest-plan` refuses to run in an agent that cannot prompt. The land fixer, a headless Codex agent, is the one -exception: `assets/land-fix.md` has it write the flaky quest, and the -`quest/m0/flaky/README.md` epic when missing, in the disable commit, and +exception: `assets/land-fix.md` has it write the flaky quest and its +`quest/m0/flaky/README.md` link in the disable commit, and `src/cli/land-watch-flaky.ts` requires exactly one added quest file. Decision prompts, chosen options marked ✅: @@ -37,7 +37,7 @@ Recommendations for the implementer: - The template's Goal says to fix the test or delete it and links each job. Its size is a fixed guess, such as `[S]`, for the next coordinator to correct. -- Epics list no children since - [moq-dev/quest#518](https://github.com/moq-dev/quest/pull/518), so the - quest needs no link in `quest/m0/flaky/README.md`. +- [Epics list no children](/quest/m0/token-waste/child-lists.md) is in + flight and drops the epic README links; follow whichever format the base + has when this lands. - `validateFix` then rejects a disable commit that touches `quest/` at all. diff --git a/quest/m0/token-waste/README.md b/quest/m0/token-waste/README.md index ea5fa14b..ca8844a4 100644 --- a/quest/m0/token-waste/README.md +++ b/quest/m0/token-waste/README.md @@ -66,6 +66,14 @@ Decision prompts, chosen options marked ✅: semver-breaking features) is moq-dev/moq's own plan: ✅ re-plan moq separately (rejected: make it quest's convention; not now). +## Required + +- [Rules load once](/quest/m0/token-waste/rule-loading.md) - skills and rules arrive in the first turn and survive compaction +- [Epics list no children](/quest/m0/token-waste/child-lists.md) - an epic's children are its directory, so finishing a quest edits no README +- [Mechanical rules become checks](/quest/m0/token-waste/rule-checks.md) - hooks enforce em dashes, push refspecs, no rebase or force-push, the footer, and `.tmp/`, and their prose leaves the always-loaded rules +- [quest usage](/quest/m0/token-waste/usage.md) - per quest and PR: which models and efforts worked on it, their tokens and API-equal cost, and how the work went; the epic's re-measure runs it +- [Point to token-max](/quest/m0/token-waste/token-max.md) - `SETUP.md` recommends the standalone settings doctor, and the re-measure runs it + ## Related - [Model check](/quest/m0/model-check.md) - audits the size tables the review quest changes diff --git a/quest/m0/token-waste/child-lists.md b/quest/m0/token-waste/child-lists.md new file mode 100644 index 00000000..8f059249 --- /dev/null +++ b/quest/m0/token-waste/child-lists.md @@ -0,0 +1,44 @@ +# [S] Epics list no children + +## Goal + +This repository's epic and milestone READMEs no longer list their children, +and `quest check` rejects a README `Required` entry naming a quest in its own +directory. Finishing a quest then deletes its file and edits no README, so +PRs that finish sibling quests stop conflicting there. + +## Plan + +Decided 2026-11-05 (user, /quest-plan, the +[token waste](/quest/m0/token-waste/README.md) audit): an epic's children are +the quests in its directory, its `Required` lists only what blocks it, and +path order replaces list order. + +Measured, moq-dev PRs created 2026-10-06 to 11-05: + +- `quest/m1/README.md` was touched by 33% of merged moq-dev/moq PRs, and + milestone READMEs as a group by 45%; in moq-dev/rust2, `quest/m3/README.md` + by 290 of 585. +- GitHub's merge queue cannot run quest's merge driver and ejected 723 PRs + for conflicts. + +Decided 2026-11-07 (user): ✅ stage it in two PRs (rejected: admin-bypass +merge once; skip; delete). The merge queue checks a PR with the CLI built +from its base, which rejected the migrated tree. +[moq-dev/quest#518](https://github.com/moq-dev/quest/pull/518) shipped +directory membership with a validator that accepts both formats: an epic's +`Required` link to a quest it holds is allowed and counts once, as a child. +This quest is the second PR: + +- Make `remove()` (`src/core/edit.ts`) drop every epic's `Required` link to a + quest it holds, so `quest check --fix`, `quest rm`, and the land daemon's + base-merge prune strip old child lists, and let `quest check --fix` run with + no history to read. #518's commit caa32fc3 has both, with tests. +- Run `quest check --fix` on this tree and on prose that describes the lists. +- Turn `requires X, which this epic holds` into a `quest check` error. +- `assets/land-fix.md` stops adding the flaky quest's link to + `quest/m0/flaky/README.md`, and + [the flaky quest](/quest/m0/queue-watcher/flaky-quest.md) says so. +- The PR is breaking: other repositories migrate with `quest check --fix` on + their pin bump past it, as + [moq-dev pins](/quest/m0/model-routing/pins.md) describes. diff --git a/quest/m0/user-dev-shell/README.md b/quest/m0/user-dev-shell/README.md index 360d8d0e..10b84cad 100644 --- a/quest/m0/user-dev-shell/README.md +++ b/quest/m0/user-dev-shell/README.md @@ -70,3 +70,8 @@ The user-level hooks live in [kixelated/dotfiles](https://github.com/kixelated/d installed into each Claude profile's `settings.json` and Codex's user config, and generalize this repository's `.claude/hooks/direnv.sh` and moq-dev/moq's `.codex/hooks/direnv.sh`. + +## Required + +- [.worktrees/ stays out of git status](/quest/m0/user-dev-shell/worktrees-exclude.md) - `quest worktree` adds `/.worktrees/` to the clone's local exclude unless something ignores it +- [Repositories drop dev-shell config](/quest/m0/user-dev-shell/repo-config.md) - quest, moq, moq.pro, rind, and rust2 drop their dev-shell hooks and `nix develop` instructions diff --git a/quest/m1/README.md b/quest/m1/README.md index 3a837559..1f95b32e 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -19,3 +19,17 @@ earlier "Later work" milestone became m2. - ✅ Move to kix.quest in m1 - Stay on quest.moq.dev - Decide later + +## Required + +- [User state in their RunnerHub](/quest/m1/user-state.md) - each user's runners, jobs, inbox, and push subscriptions live in their Durable Object, and D1 keeps repository data and other cross-user state +- [Open kix.quest](/quest/m1/open.md) - the Worker moves to kix.quest and any owner may enroll +- [Release with worktree hooks](/quest/m1/release.md) - tag a release that has `quest worktree hook`, so SETUP.md's release routes work +- [Kix for any repository](/quest/m1/kix/README.md) - onboarding, read-only CI checks, contributor sandboxing, and the maintainer guide +- [Quest log theme](/quest/m1/theme/README.md) - an MMO-style identity, copy, board, landing page, and CLI output for the demo and launch +- [Launch material](/quest/m1/launch.md) - README, quickstart, demo, comparison, and launch-post drafts +- [Gate CPU weight](/quest/m1/gate-cpu-weight.md) - gated commands run at a lower CPU weight than the interactive session, so concurrent gates no longer starve the desktop +- [Workers in a 5-minute cache](/quest/m1/worker-cache.md) - re-plan #276's worker/coordinator split and gate tickets, after confirming the cache premise +- [Retire Decisions needed](/quest/m1/decisions-needed.md) - only `## Waiting` hands a draft back, once no open draft uses the old heading +- [Bun EFAULT report](/quest/m1/bun-efault.md) - report concurrent `rmSync` `EFAULT` on Windows, and drop the workaround once Bun fixes it +- [Model check](/quest/m1/model-check.md) - recurring each milestone: the built-in implementation and review tables use the newest models at efforts retuned from outcomes, and the live sandbox test passes diff --git a/quest/m1/kix/README.md b/quest/m1/kix/README.md index 65b84813..9a3ca15e 100644 --- a/quest/m1/kix/README.md +++ b/quest/m1/kix/README.md @@ -12,3 +12,8 @@ unconfined on their own machines. Moved from m0 on 2026-10-30 (user, /quest-plan): moq-dev's own repositories already carry Quest, are enrolled by the operator, and are worked on by their maintainers, so they need none of this first. + +## Required + +- [Contributor sandboxing](/quest/m1/kix/sandbox/README.md) - contributors' PR heads build in a VM, on stock Ubuntu and verified on macOS +- [Onboarding guide](/quest/m1/kix/guide.md) - a complete maintainer path, from runner setup through a reviewed PR diff --git a/quest/m1/kix/sandbox/README.md b/quest/m1/kix/sandbox/README.md index 43e961f3..f66fc35d 100644 --- a/quest/m1/kix/sandbox/README.md +++ b/quest/m1/kix/sandbox/README.md @@ -13,3 +13,8 @@ Split from [the m0 sandbox epic](/quest/m0/kix/sandbox/README.md) on 2026-10-30 (user, /quest-plan): moq-dev's maintainers run their jobs on trusted or approved heads, so untrusted heads stay refused until m1. The design decisions for the whole sandbox stay in the m0 epic's Plan. + +## Required + +- [macOS sandbox](/quest/m1/kix/sandbox/macos.md) - the boundary verified under Seatbelt, then the answer-approval gate removed +- [Untrusted devShells](/quest/m1/kix/sandbox/vm.md) - untrusted PR heads build their devShell in a per-job VM diff --git a/quest/m1/theme/README.md b/quest/m1/theme/README.md index 55c8248e..da40cc8a 100644 --- a/quest/m1/theme/README.md +++ b/quest/m1/theme/README.md @@ -15,7 +15,8 @@ The pass also renames the "difficulty" leftovers to "size": the Worker's `Difficulty` component (`cloudflare/src/layout.tsx`, used by `cloudflare/src/home.tsx` and `cloudflare/src/board/pages.tsx`), the board's "weighted by difficulty" wording (`cloudflare/src/board/pages.tsx`, -`cloudflare/src/board/model.ts`, `cloudflare/test/board.test.ts`). +`cloudflare/src/board/model.ts`, `cloudflare/test/board.test.ts`), and the +wording in this README's `Required` list. It also replaces the display aliases on the board, the home page, and `cloudflare/README.md` with format terms: Available and `?show=available` become ready, the Requires status and filter become blocked, Accepted by @@ -109,6 +110,10 @@ Decided while planning on 2026-10-05, amended 2026-10-14 where noted: uses these terms. A blocked waypoint's tooltip lists what it needs under "Required:". +## Required + +- [Landing page](/quest/m1/theme/landing.md) - the home page's calls to action lead to sign-in, onboarding, and the setup paste + ## Related - [Launch material](/quest/m1/launch.md) - posts, quickstart, demo, and comparison written in the same voice diff --git a/quest/m2/README.md b/quest/m2/README.md index 7c9eca1c..fc36765e 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -5,3 +5,17 @@ Extend kix.quest with cloud runners, a native mobile app, runners shared with other projects, donated reviews and CI, stronger isolation, and additional login providers. This milestone does not gate the public release. + +## Required + +- [Cloud runners](/quest/m2/cloud/README.md) - one-click free cloud runners, API-key and donor funding, then paid compute +- [Native mobile app](/quest/m2/mobile-app.md) - push notifications with quick replies to decisions +- [Shared runners](/quest/m2/donor-runner.md) - offer your runner and accounts to other projects +- [Review and check automation](/quest/m2/automation/README.md) - donated reviews, CI, and a shared Nix cache +- [opencode reviewers](/quest/m2/review-harnesses.md) - `quest review` runs opencode read-only, for the council's DeepSeek member +- [Review council](/quest/m2/council.md) - `/quest-council` reviews a PR with one blind model per maker and merges their findings with agreement counts +- [Donor isolation](/quest/m2/donor-isolation.md) - stronger boundaries for untrusted shared jobs +- [ChatGPT hosted runs](/quest/m2/chatgpt-hosted.md) - conditional on provider approval and current terms +- [ChatGPT approval](/quest/m2/chatgpt-waitlist.md) - resolve hosted-use approval before implementation +- [Delete the legacy hold labels](/quest/m2/legacy-labels.md) - once every gated repository pins quest past #326, only `quest:active` and `quest:kix` are holds +- [Worktree hook PATH error](/quest/m2/hook-path-error.md) - a worktree hook without `quest` on `PATH` says so and names the dev-shell launch route diff --git a/quest/m2/automation/README.md b/quest/m2/automation/README.md index dd6ed835..1c33ccb7 100644 --- a/quest/m2/automation/README.md +++ b/quest/m2/automation/README.md @@ -10,3 +10,9 @@ authorized agent reviews and CI capacity using ordinary GitHub interfaces. Decided 2026-10-13: C1 first, then C2. Existing repository checks remain part of implementation; this epic adds independent donated review and CI jobs. No custom review database or git-note approval protocol is introduced. + +## Required + +- [Agent reviews](/quest/m2/automation/review.md) - attributed, advisory GitHub reviews +- [Donated checks](/quest/m2/automation/checks.md) - repository-defined check execution with explicit trust +- [Nix cache](/quest/m2/automation/cache.md) - optional main-only signed build cache diff --git a/quest/m2/cloud/README.md b/quest/m2/cloud/README.md index 6c50de33..cf1fabc2 100644 --- a/quest/m2/cloud/README.md +++ b/quest/m2/cloud/README.md @@ -26,3 +26,10 @@ Decided 2026-10-15 in the decisions-not-implementations interview: for the cloud runners that depend on it. - Funding setup and operating guidance stay in existing service documentation; each implementation updates the docs it changes. + +## Required + +- [API funding](/quest/m2/cloud/funding.md) - maintainer API keys, the credential proxy, and durable usage accounting +- [Hosted runners](/quest/m2/cloud/runners.md) - free, capped cloud runners enabled with one click +- [Donor allocations](/quest/m2/cloud/donors.md) - shared API budgets after maintainer-funded cloud runners work +- [Paid compute](/quest/m2/cloud/billing.md) - charge for cloud runner compute once free capacity is not enough diff --git a/src/cli/main.ts b/src/cli/main.ts index e8feb0b2..3b722046 100644 --- a/src/cli/main.ts +++ b/src/cli/main.ts @@ -168,15 +168,14 @@ export function main(argv: string[], out: Output): number | Promise { "first: a stale base can predate the quest and skip it.\n\n" + "With --fix, first drop every Required, Related, or Closes entry that links to a quest deleted in " + "the history of HEAD, and of MERGE_HEAD during a merge, that the working tree lacks, as quest rm " + - "does, such as the quests a merged base finished, and every epic's Required entry naming a quest in " + - "its own directory, which the epic already waits for, with any heading left empty. It prints M for " + - "each edited document and leaves the edits unstaged. A quest moved rather than deleted, a link that " + - "never named a quest, and a link in prose stay for the check to report. Refuses outside a git work " + - "tree and while a quest file has unresolved conflicts.", + "does, such as the quests a merged base finished, with any heading left empty. It prints M for each " + + "edited document and leaves the edits unstaged. A quest moved rather than deleted, a link that never " + + "named a quest, and a link in prose stay for the check to report. Refuses outside a git work tree " + + "and while a quest file has unresolved conflicts.", ) .option("--base ", "Also check the quest branch's diff from its merge base with this ref") .option("--branch ", "The PR's head branch, when it differs from the current branch (needs --base)") - .option("--fix", "First drop list links to quests the history deleted, and epics' links to their own quests") + .option("--fix", "First drop list links to quests the history deleted") .action((options: { base?: string; branch?: string; fix?: boolean }) => { if (options.branch !== undefined && options.base === undefined) { throw new UsageError("--branch requires --base"); @@ -1238,7 +1237,7 @@ export function main(argv: string[], out: Output): number | Promise { "Delete a quest, or an epic and the quests under it, with git rm, and drop every Required, Related, " + "or Closes entry that links to it, with any heading left empty. It also drops every Required link to a " + "finished milestone, one whose directory holds no other quest and whose README has no Required left, " + - "and every epic's Required entry naming a quest in its own directory. The change is staged.\n\n" + + "except the root's own listing. The change is staged.\n\n" + "Refuses outside a git work tree. An epic is its directory or README; removing one that holds other " + "quests requires -r. The root epic and milestones are permanent.\n\n" + "Prints D for each deleted quest and M for each edited document. Mentions that are not list entries, " + diff --git a/src/cli/move.ts b/src/cli/move.ts index 9283e41c..52b74402 100644 --- a/src/cli/move.ts +++ b/src/cli/move.ts @@ -76,8 +76,7 @@ export async function moveQuest( /** * Delete a quest, or an epic with the quests under it, and drop every list - * entry that links to what was deleted, as `remove` does. The root and - * milestones are permanent. + * entry that links to what was deleted. The root and milestones are permanent. */ export function removeQuest(root: string, arg: string, recursive: boolean): Report { workTree(root); @@ -114,11 +113,10 @@ export function removeQuest(root: string, arg: string, recursive: boolean): Repo /** * Drop every list entry that links to a quest deleted in the history of `HEAD`, and of * `MERGE_HEAD` during a merge, that the working tree lacks, as `quest rm` drops the links to a - * quest it deletes, and every epic's `Required` entry naming a quest in its own directory, which - * the epic already waits for. Merging the base brings in the quests it finished as deletions, which - * leaves this branch's links to them dangling. A quest the history moved is a rename, not a deletion, - * and a link to a path that never held a quest is a mistake; both stay for `quest check` to report, - * as does a link in prose. Writes the edited documents without staging them, and refuses while a + * quest it deletes. Merging the base brings in the quests it finished as deletions, which leaves + * this branch's links to them dangling. A quest the history moved is a rename, not a deletion, and + * a link to a path that never held a quest is a mistake; both stay for `quest check` to report, as + * does a link in prose. Writes the edited documents without staging them, and refuses while a * quest file is unmerged, since its conflict markers are not yet a document. Returns `M path` for * each. */ @@ -132,24 +130,23 @@ export function fixLinks(root: string): string[] { throw new Error(`resolve the merge conflicts in ${[...new Set(unmerged)].join(", ")} before quest check --fix`); } const heads = ["HEAD", "MERGE_HEAD"].filter((ref) => verified(root, ref)); + if (heads.length === 0) return []; const deleted = new Set( - heads.length === 0 - ? [] - : // `--relative` names paths from `root`, as the tree's links do, when the tree is nested in its repository. - git(root, [ - "log", - "--relative", - "--diff-filter=D", - "--find-renames", - "--name-only", - "--format=", - "-z", - ...heads, - "--", - "quest", - ]) - .split("\0") - .filter(isQuest), + // `--relative` names paths from `root`, as the tree's links do, when the tree is nested in its repository. + git(root, [ + "log", + "--relative", + "--diff-filter=D", + "--find-renames", + "--name-only", + "--format=", + "-z", + ...heads, + "--", + "quest", + ]) + .split("\0") + .filter(isQuest), ); const edited = remove(sources(root), (path) => deleted.has(path) && !exists(root, path)); for (const [path, text] of edited) writeFileSync(join(root, path), text); diff --git a/src/core/doc.ts b/src/core/doc.ts index 109946f0..938eb110 100644 --- a/src/core/doc.ts +++ b/src/core/doc.ts @@ -204,11 +204,15 @@ export function isEpic(docs: readonly Doc[], doc: Doc): boolean { return permanent(doc.path) || docs.some((d) => holds(doc.path, d.path)); } -/** What must finish before `doc`: its `Required` quests, then, for an epic, its children. */ +/** + * What must finish before `doc`: its `Required` quests, then, for an epic, its + * children. An epic's `Required` link to a quest it holds, left from a tree + * that listed children, is one of those children rather than a blocker. + */ export function requires(docs: readonly Doc[], doc: Doc): string[] { const required = entries(doc, "Required") .map((entry) => (entry.target === null ? null : rooted(entry.target))) - .filter((target): target is string => target !== null); + .filter((target): target is string => target !== null && !holds(doc.path, target)); return [...required, ...children(docs, doc)]; } diff --git a/src/core/edit.ts b/src/core/edit.ts index 3c7f94cc..8e9c0e3a 100644 --- a/src/core/edit.ts +++ b/src/core/edit.ts @@ -5,7 +5,7 @@ // dependency graph. Anything else that mentions a path is prose, which the // caller reports rather than rewriting. -import { type Doc, type Entry, holds, parse, rooted, withoutFragment } from "./doc"; +import { type Doc, type Entry, parse, rooted, withoutFragment } from "./doc"; import { LIST_SECTIONS, finishedMilestone } from "./rules"; /** One quest document as loaded: its repository-relative path and source text. */ @@ -71,35 +71,24 @@ export function move(sources: Source[], from: string, to: string): Moved { * Drop every list entry, in a list section, that opens with a link to a * deleted document, and a section heading left with no entries. Then drop * every `Required` link to a finished milestone, whether this removal emptied - * it or the link was already stale, and every epic's `Required` link to a - * quest it holds, which it already waits for, repeating until nothing changes - * so the result passes `quest check`. Returns the new text of every surviving + * it or the link was already stale, repeating until nothing changes so the + * result passes `quest check`. Returns the new text of every surviving * document that changed. */ export function remove(sources: Source[], deleted: (path: string) => boolean): Map { const texts = new Map(sources.filter((s) => !deleted(s.path)).map((s) => [s.path, s.text])); const changed = new Set(); - const target = (entry: Entry) => (entry.target === null ? null : rooted(entry.target)); const linksDeleted = (entry: Entry) => { - if (entry.section === null || !LIST_SECTIONS.includes(entry.section)) return false; - const path = target(entry); - return path !== null && deleted(path); - }; - // Only a quest that exists is held: a mistyped link stays for `quest check` to report. - const held = (doc: Doc, entry: Entry) => { - const path = target(entry); - return entry.section === "Required" && path !== null && texts.has(path) && holds(doc.path, path); + if (entry.section === null || !LIST_SECTIONS.includes(entry.section) || entry.target === null) return false; + const target = rooted(entry.target); + return target !== null && deleted(target); }; for (let progress = true; progress;) { progress = false; const docs = [...texts].map(([path, text]) => parse(path, text)); const finished = finishedMilestone(docs); for (const doc of docs) { - const text = drop( - texts.get(doc.path)!, - doc, - (entry) => linksDeleted(entry) || finished(doc, entry) || held(doc, entry), - ); + const text = drop(texts.get(doc.path)!, doc, (entry) => linksDeleted(entry) || finished(doc, entry)); if (text === null) continue; texts.set(doc.path, text); changed.add(doc.path); diff --git a/src/core/ready.ts b/src/core/ready.ts index 75a31be5..44551edf 100644 --- a/src/core/ready.ts +++ b/src/core/ready.ts @@ -7,7 +7,7 @@ // coherent, and already done by some other PR - and answering it means asking // the forge, so it belongs to the flow that is already talking to it. -import { type Doc, children, entries, has, isEpic, rooted } from "./doc"; +import { type Doc, children, entries, has, holds, isEpic, rooted } from "./doc"; import { comparePaths, normalize } from "./path"; /** One thing standing between a quest and being started. */ @@ -95,6 +95,8 @@ function expand(docs: Doc[], byPath: Map, doc: Doc, stack: string[] // A bullet that does not open with a link into the tree is invalid, and // nothing here can clear it, so it is a blocker with nothing under it. const target = entry.target === null ? null : rooted(entry.target); + // A link to a quest the epic holds is listed below, with its children. + if (target !== null && holds(doc.path, target)) continue; found.push(blocker(docs, byPath, target !== null && byPath.has(target) ? target : null, entry.text, stack)); } for (const child of children(docs, doc)) found.push(blocker(docs, byPath, child, child, stack)); diff --git a/src/core/rules.ts b/src/core/rules.ts index ff4d1369..4c3f91bb 100644 --- a/src/core/rules.ts +++ b/src/core/rules.ts @@ -210,8 +210,9 @@ function links(found: Finding[], exists: (path: string) => boolean, known: Set, docs: Doc[]) { found.push({ path: doc.path, line: entry.line, message: `requires ${entry.target} twice` }); } seen.add(target); - if (holds(doc.path, target)) { - found.push({ - path: doc.path, - line: entry.line, - message: `requires ${entry.target}, which this epic holds; an epic waits for everything in its directory, so remove the entry (quest check --fix does)`, - }); - } } } } @@ -263,8 +257,8 @@ function membership(found: Finding[], known: Set, docs: Doc[]) { * other quest and its README has no `## Required`. * * Readiness stays a grep for the heading; this rule is what keeps that answer - * true once the milestone empties. A root entry naming a milestone is the - * membership rule's finding, not this one's. + * true once the milestone empties. The root's own listing of its milestones is + * membership, not a blocker, so it is exempt. */ function milestones(found: Finding[], docs: Doc[]) { const finished = finishedMilestone(docs); diff --git a/src/core/unblocked.ts b/src/core/unblocked.ts index 5a5fd606..17314a3d 100644 --- a/src/core/unblocked.ts +++ b/src/core/unblocked.ts @@ -1,7 +1,7 @@ // Rank ready work without mistaking epic membership for downstream work. import { handBackWaits } from "./claim"; -import { type Doc, branchQuest, children, entries, permanent, rooted } from "./doc"; +import { type Doc, branchQuest, children, entries, holds, permanent, rooted } from "./doc"; import { ready, treeOrder } from "./ready"; import { ROOT, check, formatFinding } from "./rules"; import { type Wait, onMaintainer, waits } from "./waiting"; @@ -37,7 +37,11 @@ export function ranking(docs: Doc[]): Ranking { reverse.set(target, dependents); }; for (const doc of docs) { - for (const entry of entries(doc, "Required")) depend(rooted(entry.target!)!, doc.path, false); + for (const entry of entries(doc, "Required")) { + const target = rooted(entry.target!)!; + // An old child list's entry is membership, which the children below record. + if (!holds(doc.path, target)) depend(target, doc.path, false); + } for (const child of children(docs, doc)) depend(child, doc.path, true); } diff --git a/test/move.test.ts b/test/move.test.ts index 715abd2d..793e21be 100644 --- a/test/move.test.ts +++ b/test/move.test.ts @@ -10,7 +10,7 @@ import { move, remove } from "../src/core"; import { openPullRequests } from "../src/cli/claims"; import { GitHub, type GitHubDependencies } from "../src/cli/github"; import { main } from "../src/cli/main"; -import { EPIC_README, M0_README, ROOT_README, Tree, initRepository, tempDir } from "./fixture"; +import { EPIC_README, Tree, initRepository, tempDir } from "./fixture"; // Each test spawns git up to a dozen times, which a busy Windows runner can stretch past 5 s. vi.setConfig({ testTimeout: 30_000 }); @@ -120,9 +120,11 @@ describe("remove", () => { "# [S] A\n\n## Goal\n\nAfter [B](/quest/b.md).\n\n- [B](/quest/b.md) in a goal list\n\n## Related\n\nContext.\n", ); }); - test("drops links to finished milestones until nothing changes", () => { + test("drops links to finished milestones until nothing changes, keeping the root's listing", () => { + const root = + "# Quests\n\n## Goal\n\nG.\n\n## Required\n\n- [M0](/quest/m0/README.md)\n- [M1](/quest/m1/README.md)\n"; const sources = [ - { path: "quest/README.md", text: "# Quests\n\n## Goal\n\nG.\n" }, + { path: "quest/README.md", text: root }, // m0 finishes once b goes, which finishes m1, which only waited on m0. { path: "quest/m0/README.md", text: "# M0\n\n## Goal\n\nG.\n\n## Required\n\n- [B](/quest/b.md)\n" }, { @@ -145,32 +147,6 @@ describe("remove", () => { expect(texts.get("quest/m1/README.md")).toBe("# M1\n\n## Goal\n\nG.\n"); expect(texts.get("quest/a.md")).toBe("# [S] A\n\n## Goal\n\nG.\n\n## Related\n\n- [M0](/quest/m0/README.md)\n"); }); - - // An epic waits for everything in its directory, so its links to those quests - // are the child lists this format retired. A sibling's link is a real blocker, - // and a link to no quest is a mistake for the check to report. - test("drops an epic's Required links to quests it holds, at any depth", () => { - const readme = - "# Epic\n\n## Goal\n\nG.\n\n## Required\n\n- [A](/quest/m0/epic/a.md)\n" + - "- [Outside](/quest/m0/outside.md)\n- [Deep](/quest/m0/epic/sub/deep.md)\n- [Typo](/quest/m0/epic/typo.md)\n\n" + - "## Related\n\n- [A](/quest/m0/epic/a.md)\n"; - const sibling = "# [S] B\n\n## Goal\n\nG.\n\n## Required\n\n- [A](/quest/m0/epic/a.md)\n"; - const quest = (title: string) => `# [S] ${title}\n\n## Goal\n\nG.\n`; - const texts = remove( - [ - { path: "quest/m0/epic/README.md", text: readme }, - { path: "quest/m0/epic/a.md", text: quest("A") }, - { path: "quest/m0/epic/b.md", text: sibling }, - { path: "quest/m0/epic/sub/deep.md", text: quest("Deep") }, - ], - () => false, - ); - expect([...texts.keys()]).toEqual(["quest/m0/epic/README.md"]); - expect(texts.get("quest/m0/epic/README.md")).toBe( - "# Epic\n\n## Goal\n\nG.\n\n## Required\n\n- [Outside](/quest/m0/outside.md)\n- [Typo](/quest/m0/epic/typo.md)\n\n" + - "## Related\n\n- [A](/quest/m0/epic/a.md)\n", - ); - }); }); describe("quest mv", () => { @@ -456,8 +432,9 @@ describe("quest check --fix", () => { expect(tree.read("quest/m0/epic/three.md")).toBe(before); }); - // Trees from before epics stopped listing their children migrate with one run. - test("strips the child lists of the root, milestones, and epics", async () => { + // Trees from before directory membership keep their child lists until migrated: + // finishing a quest drops only its own entry. + test("drops only the finished quest's entry from a child list", async () => { const tree = Tree.baseline() .append("quest/README.md", "\n## Required\n\n- [M0](/quest/m0/README.md)\n") .append("quest/m0/README.md", "\n## Required\n\n- [Epic](/quest/m0/epic/README.md)\n") @@ -466,14 +443,15 @@ describe("quest check --fix", () => { "\n## Required\n\n- [One](/quest/m0/epic/one.md)\n- [Two](/quest/m0/epic/two.md)\n", ); committed(tree); - expect(await quest(tree, "check", "--fix")).toEqual({ + expect(await quest(tree, "rm", "quest/m0/epic/one.md")).toEqual({ code: 0, - stdout: "M quest/README.md\nM quest/m0/README.md\nM quest/m0/epic/README.md\nquest: 5 documents ok\n", + stdout: "D quest/m0/epic/one.md\nM quest/m0/epic/README.md\nM quest/m0/epic/two.md\n", stderr: "", }); - expect(tree.read("quest/README.md")).toBe(ROOT_README); - expect(tree.read("quest/m0/README.md")).toBe(M0_README); - expect(tree.read("quest/m0/epic/README.md")).toBe(EPIC_README); + expect(tree.read("quest/m0/epic/README.md")).toBe( + `${EPIC_README}\n## Required\n\n- [Two](/quest/m0/epic/two.md)\n`, + ); + expect(await quest(tree, "check", "--fix")).toEqual({ code: 0, stdout: "quest: 4 documents ok\n", stderr: "" }); }); test("fails outside a git work tree", async () => { diff --git a/test/tree.test.ts b/test/tree.test.ts index 54a067c5..ab32322c 100644 --- a/test/tree.test.ts +++ b/test/tree.test.ts @@ -293,19 +293,18 @@ describe("epics", () => { .rejects("quest/m0/loose/deeper/README.md: sits in quest/m0/loose, which has no README.md"); }); - // An epic already waits for everything in its directory, so a link to any of - // it is the child list this format retired; `quest check --fix` drops it. + // Trees from before directory membership still list each epic's children. + // A link to a quest the epic holds is membership, so it counts once. test.each([ ["quest/README.md", "/quest/m0/README.md"], ["quest/m0/README.md", "/quest/m0/epic/README.md"], ["quest/m0/README.md", "/quest/m0/epic/one.md"], ["quest/m0/epic/README.md", "/quest/m0/epic/one.md"], ])("%s requiring %s, which it holds", (readme, target) => { - const t = tree().append(readme, `\n## Required\n\n- [Held](${target})\n`); - expect(t.findings()).toHaveLength(1); - t.rejects( - `requires ${target}, which this epic holds; an epic waits for everything in its directory, so remove the entry (quest check --fix does)`, - ); + const listed = tree().append(readme, `\n## Required\n\n- [Held](${target})\n`); + listed.accepts(); + expect(listed.ready()).toEqual(tree().ready()); + expect(listed.blockers(readme)).toEqual(tree().blockers(readme)); }); test("a quest required twice", () => { @@ -386,14 +385,12 @@ describe("finished milestones", () => { .accepts(); }); - // The root holds every milestone, so its link to one is that finding alone. - test("the root's link to a finished milestone is one finding", () => { - const t = tree() + // The root's listing of its milestones is membership, not a blocker. + test("the root's link to a finished milestone is allowed", () => { + tree() .append("quest/README.md", "\n## Required\n\n- [M0](/quest/m0/README.md)\n") - .remove("quest/m0/epic"); - expect(t.findings()).toEqual([ - "quest/README.md:9: requires /quest/m0/README.md, which this epic holds; an epic waits for everything in its directory, so remove the entry (quest check --fix does)", - ]); + .remove("quest/m0/epic") + .accepts(); }); test("removing the link readies the quest", () => { diff --git a/test/unblocked.test.ts b/test/unblocked.test.ts index 5a3cfef5..817b3b6b 100644 --- a/test/unblocked.test.ts +++ b/test/unblocked.test.ts @@ -47,6 +47,12 @@ test("deduplicates diamonds and counts work that still has another prerequisite" ]); }); +test("an epic's list of its own children is membership, not dependents", () => { + const spec = { "m0/epic/a.md": [], "m0/epic/b.md": ["m0/epic/a.md"], "m0/zero.md": [] }; + const listed = graph({ ...spec, "m0/epic/README.md": ["m0/epic/a.md", "m0/epic/b.md"] }); + expect(unblocked(listed)).toEqual(unblocked(graph(spec))); +}); + test("does not score membership, but reaches real dependents of nested epics", () => { const docs = graph({ "m0/epic/nested/a.md": [], From 9488d7abc952fbd0ebe775848a3a15f8c329b42f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 7 Nov 2026 11:05:55 -0800 Subject: [PATCH 5/6] fix: keep a held link to no quest as a blocker Co-Authored-By: Claude Opus 5.5 --- src/core/ready.ts | 5 +++-- test/tree.test.ts | 5 +++++ 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/src/core/ready.ts b/src/core/ready.ts index 44551edf..f637a69c 100644 --- a/src/core/ready.ts +++ b/src/core/ready.ts @@ -95,8 +95,9 @@ function expand(docs: Doc[], byPath: Map, doc: Doc, stack: string[] // A bullet that does not open with a link into the tree is invalid, and // nothing here can clear it, so it is a blocker with nothing under it. const target = entry.target === null ? null : rooted(entry.target); - // A link to a quest the epic holds is listed below, with its children. - if (target !== null && holds(doc.path, target)) continue; + // A link to a quest the epic holds is listed below, with its children; a + // broken one stays, since no child stands in for it. + if (target !== null && byPath.has(target) && holds(doc.path, target)) continue; found.push(blocker(docs, byPath, target !== null && byPath.has(target) ? target : null, entry.text, stack)); } for (const child of children(docs, doc)) found.push(blocker(docs, byPath, child, child, stack)); diff --git a/test/tree.test.ts b/test/tree.test.ts index ab32322c..dd9df892 100644 --- a/test/tree.test.ts +++ b/test/tree.test.ts @@ -307,6 +307,11 @@ describe("epics", () => { expect(listed.blockers(readme)).toEqual(tree().blockers(readme)); }); + test("a held link to no quest still blocks", () => { + const t = tree().append("quest/m0/epic/README.md", "\n## Required\n\n- [Gone](/quest/m0/epic/gone.md)\n"); + expect(t.blockers("quest/m0/epic/README.md")[0]).toBe("Gone"); + }); + test("a quest required twice", () => { tree() .append("quest/m0/epic/two.md", "- [One again](/quest/m0/epic/one.md)\n") From 2d9c6da53e9ea404c30e61e2b5dfc99018f54364 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 7 Nov 2026 11:11:10 -0800 Subject: [PATCH 6/6] fix: count only an epic's own children in an old child list A link to a deeper quest stays a blocker, as on a tree that listed children, so an invalid subtree cannot hide it. Co-Authored-By: Claude Opus 5.5 --- src/core/doc.ts | 9 +++++---- src/core/index.ts | 1 - src/core/ready.ts | 10 +++++----- src/core/rules.ts | 5 ++--- src/core/unblocked.ts | 7 ++++--- test/tree.test.ts | 16 ++++++++++------ 6 files changed, 26 insertions(+), 22 deletions(-) diff --git a/src/core/doc.ts b/src/core/doc.ts index 938eb110..bba071d5 100644 --- a/src/core/doc.ts +++ b/src/core/doc.ts @@ -206,14 +206,15 @@ export function isEpic(docs: readonly Doc[], doc: Doc): boolean { /** * What must finish before `doc`: its `Required` quests, then, for an epic, its - * children. An epic's `Required` link to a quest it holds, left from a tree - * that listed children, is one of those children rather than a blocker. + * children. An epic's `Required` link to one of its children, left from a tree + * that listed them, counts once. */ export function requires(docs: readonly Doc[], doc: Doc): string[] { + const kids = children(docs, doc); const required = entries(doc, "Required") .map((entry) => (entry.target === null ? null : rooted(entry.target))) - .filter((target): target is string => target !== null && !holds(doc.path, target)); - return [...required, ...children(docs, doc)]; + .filter((target): target is string => target !== null && !kids.includes(target)); + return [...required, ...kids]; } /** diff --git a/src/core/index.ts b/src/core/index.ts index ed0d8d50..6ed68e31 100644 --- a/src/core/index.ts +++ b/src/core/index.ts @@ -16,7 +16,6 @@ export { children, entries, has, - holds, isQuest, isEpic, owner, diff --git a/src/core/ready.ts b/src/core/ready.ts index f637a69c..8d8e4d8c 100644 --- a/src/core/ready.ts +++ b/src/core/ready.ts @@ -7,7 +7,7 @@ // coherent, and already done by some other PR - and answering it means asking // the forge, so it belongs to the flow that is already talking to it. -import { type Doc, children, entries, has, holds, isEpic, rooted } from "./doc"; +import { type Doc, children, entries, has, isEpic, rooted } from "./doc"; import { comparePaths, normalize } from "./path"; /** One thing standing between a quest and being started. */ @@ -84,6 +84,7 @@ function expand(docs: Doc[], byPath: Map, doc: Doc, stack: string[] // everything that greps for it, including `quest check`, which reports it. // Calling it ready here would make this the one tool that disagrees. const required = entries(doc, "Required"); + const kids = children(docs, doc); if (has(doc, "Required") && required.length === 0) { found.push({ path: null, @@ -95,12 +96,11 @@ function expand(docs: Doc[], byPath: Map, doc: Doc, stack: string[] // A bullet that does not open with a link into the tree is invalid, and // nothing here can clear it, so it is a blocker with nothing under it. const target = entry.target === null ? null : rooted(entry.target); - // A link to a quest the epic holds is listed below, with its children; a - // broken one stays, since no child stands in for it. - if (target !== null && byPath.has(target) && holds(doc.path, target)) continue; + // An old child list's entry is listed below, with the children. + if (target !== null && kids.includes(target)) continue; found.push(blocker(docs, byPath, target !== null && byPath.has(target) ? target : null, entry.text, stack)); } - for (const child of children(docs, doc)) found.push(blocker(docs, byPath, child, child, stack)); + for (const child of kids) found.push(blocker(docs, byPath, child, child, stack)); return found; } diff --git a/src/core/rules.ts b/src/core/rules.ts index 4c3f91bb..45d0dded 100644 --- a/src/core/rules.ts +++ b/src/core/rules.ts @@ -210,9 +210,8 @@ function links(found: Finding[], exists: (path: string) => boolean, known: Set { }); // Trees from before directory membership still list each epic's children. - // A link to a quest the epic holds is membership, so it counts once. + // Such a link is membership, so it counts once. test.each([ ["quest/README.md", "/quest/m0/README.md"], ["quest/m0/README.md", "/quest/m0/epic/README.md"], - ["quest/m0/README.md", "/quest/m0/epic/one.md"], ["quest/m0/epic/README.md", "/quest/m0/epic/one.md"], - ])("%s requiring %s, which it holds", (readme, target) => { + ])("%s requiring its child %s", (readme, target) => { const listed = tree().append(readme, `\n## Required\n\n- [Held](${target})\n`); listed.accepts(); expect(listed.ready()).toEqual(tree().ready()); expect(listed.blockers(readme)).toEqual(tree().blockers(readme)); }); - test("a held link to no quest still blocks", () => { - const t = tree().append("quest/m0/epic/README.md", "\n## Required\n\n- [Gone](/quest/m0/epic/gone.md)\n"); - expect(t.blockers("quest/m0/epic/README.md")[0]).toBe("Gone"); + // Only a child stands in for a link: a deeper quest, or a link to no quest, + // stays a blocker, as on a tree that listed children. + test.each([ + ["/quest/m0/epic/one.md", "quest/m0/epic/one.md"], + ["/quest/m0/gone.md", "Gone"], + ])("quest/m0/README.md requiring %s, which is not its child", (target, rendered) => { + const t = tree().append("quest/m0/README.md", `\n## Required\n\n- [Gone](${target})\n`); + expect(t.blockers("quest/m0/README.md")[0]).toBe(rendered); }); test("a quest required twice", () => {