From 5dbd9f6ae10ab4f70a2cb36fe71629ac12e7ca3e Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 26 Sep 2026 09:47:43 -0700 Subject: [PATCH 1/2] feat: read readiness through line branches `quest ready --remote origin` reads each questline from its remote-tracking line branch when one exists, outermost first. Children merge into their line before main sees them, so main alone reports finished work as ready; the spawn-quests skill worked around that in prose. Co-Authored-By: Claude Opus 5.5 --- .claude/skills/spawn-quests/SKILL.md | 2 +- docs/getting-started.md | 4 +- flake.nix | 2 + quest/AGENTS.md | 3 +- src/branch.rs | 99 +++++++++++++++++++-- src/lib.rs | 23 +++-- src/main.rs | 17 +++- src/ready.rs | 13 +-- tests/tree.rs | 123 ++++++++++++++++++++++++++- 9 files changed, 260 insertions(+), 26 deletions(-) diff --git a/.claude/skills/spawn-quests/SKILL.md b/.claude/skills/spawn-quests/SKILL.md index 80960dc8..33760b2d 100644 --- a/.claude/skills/spawn-quests/SKILL.md +++ b/.claude/skills/spawn-quests/SKILL.md @@ -11,7 +11,7 @@ If you are unsure of the best course of action, ask the user for clarification b The scope consists of all ready quests that are not claimed. Use the argument (if provided) to filter to specific quests/questlines. Main's tree lags its lines: a child finished on its line branch still looks ready from `main`. -Judge readiness from each line branch's own quest directory. +Fetch, then judge readiness with `quest ready --remote origin`, which reads each line from its branch. Inspect any blocked quests, and determine if they can be unblocked. A line whose `Quests` list has emptied is a ready quest too: finishing it marks the line's PR ready. diff --git a/docs/getting-started.md b/docs/getting-started.md index 7e171bb5..c5449e18 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -66,7 +66,9 @@ quest branch quest/m0/some-quest.md ``` `branch` prints that quest's branch and each branch it merges through, ending -at `main`. Milestones themselves have no branch. +at `main`. Milestones themselves have no branch. Children merge into their +line's branch first, so after a `git fetch`, `quest ready --remote origin` +reads each line from its branch instead of the working tree. Review the plan before starting it. `/start-quest` works on one quest; `/spawn-quests` coordinates multiple agents when your session supports them. diff --git a/flake.nix b/flake.nix index 9349e0c1..b61d9175 100644 --- a/flake.nix +++ b/flake.nix @@ -39,6 +39,8 @@ quest = craneLib.buildPackage { src = craneLib.cleanCargoSource ./.; strictDeps = true; + # The line-branch readiness tests build real repositories. + nativeCheckInputs = [ pkgs.git ]; }; in { diff --git a/quest/AGENTS.md b/quest/AGENTS.md index c031194c..0314baac 100644 --- a/quest/AGENTS.md +++ b/quest/AGENTS.md @@ -64,7 +64,8 @@ Current decisions, open questions, or implementation guidance. repository; remove it when it clears. `Required` must be acyclic. - `quest check` enforces this structure; run it before submitting quest changes. `quest ready []` prints what blocks a quest, or every ready - quest. `quest branch ` prints the branch and every branch it merges + quest; `--remote origin` reads each line from its fetched branch, where its + children finish before `main` sees them. `quest branch ` prints the branch and every branch it merges through, nearest first and ending at `main`. The root instructions say how to run `quest` when it is not on `PATH`. It reads the tree alone: whether a PR already claims a quest is GitHub's question. diff --git a/src/branch.rs b/src/branch.rs index 000e039a..ad3cd843 100644 --- a/src/branch.rs +++ b/src/branch.rs @@ -2,14 +2,16 @@ //! //! The mapping is the path alone: a quest's branch is its path without `.md` //! and a questline's is its README's. Milestones have no branch, so a -//! milestone's direct children merge into `main`. Nothing here asks git, so the -//! answer is the same on every machine and a missing line branch is simply -//! created from the next one in the chain. +//! milestone's direct children merge into `main`. Naming a branch never asks +//! git, so the answer is the same on every machine and a missing line branch is +//! simply created from the next one in the chain. Only [`overlay`] reads the +//! branches themselves, and only when asked. -use std::collections::BTreeMap; -use std::path::Path; +use std::collections::{BTreeMap, BTreeSet, VecDeque}; +use std::path::{Path, PathBuf}; +use std::process::Command; -use anyhow::{Result, bail}; +use anyhow::{Context, Result, bail}; use crate::doc::Doc; @@ -30,3 +32,88 @@ pub fn chain(root: &Path, path: &Path) -> Result> { out.push("main".to_string()); Ok(out) } + +/// The tree as the line branches on `remote` see it. +/// +/// A line's children merge into its branch, not `main`, so until the line lands +/// the working tree still lists quests that are already done. Each line whose +/// branch exists replaces its directory with that branch's copy, outermost +/// first, so a nested line's own branch has the last word on its subtree. A +/// line that an outer branch already completed stays gone even if its own +/// branch lingers. +pub(crate) fn overlay(root: &Path, docs: Vec, remote: &str) -> Result> { + // Fail on a typo'd remote or a tree outside git, rather than read every line + // as absent and report the working tree as if it were the answer. + git(root, &["remote", "get-url", remote])?; + + let mut docs: BTreeMap = docs.into_iter().map(|d| (d.path.clone(), d)).collect(); + let mut lines: Vec = docs.keys().filter(|p| is_line(p)).cloned().collect(); + lines.sort_by_key(|p| p.components().count()); + let mut pending = VecDeque::from(lines); + let mut seen = BTreeSet::new(); + + while let Some(readme) = pending.pop_front() { + if !docs.contains_key(&readme) || !seen.insert(readme.clone()) { + continue; + } + let rev = format!("refs/remotes/{remote}/{}", readme.with_extension("").display()); + // A line nobody has started has no branch yet. + if git( + root, + &["rev-parse", "--verify", "--quiet", &format!("{rev}^{{commit}}")], + ) + .is_err() + { + continue; + } + + let dir = readme.parent().unwrap_or(Path::new("")); + docs.retain(|path, _| !path.starts_with(dir)); + let listing = git( + root, + &[ + "ls-tree", + "-r", + "-z", + "--name-only", + &rev, + "--", + &format!("{}/", dir.display()), + ], + )?; + for path in listing.split('\0').filter(|p| !p.is_empty()).map(PathBuf::from) { + if !crate::is_quest(&path) { + continue; + } + let text = git(root, &["show", &format!("{rev}:./{}", path.display())])?; + if is_line(&path) { + pending.push_back(path.clone()); + } + docs.insert(path.clone(), Doc::from_str(path, &text)); + } + } + Ok(docs.into_values().collect()) +} + +/// A README with a branch: anything but the root and the milestones. +fn is_line(path: &Path) -> bool { + path.file_name().is_some_and(|n| n == "README.md") && !Doc::permanent(path) +} + +/// Run git in `root`, returning stdout; a failure is an error carrying stderr. +fn git(root: &Path, args: &[&str]) -> Result { + let out = Command::new("git") + .arg("-C") + .arg(root) + .args(args) + .output() + .context("running git")?; + if !out.status.success() { + bail!( + "git {} failed: {}", + args.join(" "), + String::from_utf8_lossy(&out.stderr).trim() + ); + } + String::from_utf8(out.stdout).context("git printed non-UTF-8") +} diff --git a/src/lib.rs b/src/lib.rs index 31f7a8d4..081ee084 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -41,17 +41,21 @@ fn walk(root: &Path, dir: &Path, out: &mut Vec) -> Result<()> { let kind = entry.file_type()?; if kind.is_dir() { walk(root, &path, out)?; - } else if path.extension().is_some_and(|e| e == "md") - && !path - .file_name() - .is_some_and(|n| NOT_QUESTS.iter().any(|skip| n == *skip)) - { + } else if is_quest(&path) { out.push(path.strip_prefix(root).unwrap_or(&path).to_path_buf()); } } Ok(()) } +/// A Markdown file other than agent instructions. +fn is_quest(path: &Path) -> bool { + path.extension().is_some_and(|e| e == "md") + && !path + .file_name() + .is_some_and(|n| NOT_QUESTS.iter().any(|skip| n == *skip)) +} + /// Parse and validate the tree. Returns every finding, worst-case empty. pub fn check(root: &Path) -> Result> { Ok(rules::check(root, &load(root)?)) @@ -65,3 +69,12 @@ fn load(root: &Path) -> Result> { } paths.into_iter().map(|p| Doc::parse(root, p)).collect() } + +/// [`load`], with each line read from its branch on `remote` when one is given. +fn load_from(root: &Path, remote: Option<&str>) -> Result> { + let docs = load(root)?; + match remote { + Some(remote) => branch::overlay(root, docs, remote), + None => Ok(docs), + } +} diff --git a/src/main.rs b/src/main.rs index 27135981..9da3588a 100644 --- a/src/main.rs +++ b/src/main.rs @@ -31,6 +31,12 @@ enum Command { Ready { /// Quest to explain. Omit to list every ready quest in tree order. path: Option, + + /// Read each questline from its branch on this remote (`origin`) when + /// that branch exists: a line's children finish there before the line + /// reaches the working tree. Fetch first; this reads remote-tracking refs. + #[arg(long)] + remote: Option, }, /// Print the branch carrying a quest, then every branch it merges through. @@ -60,8 +66,11 @@ fn main() -> Result { } Ok(ExitCode::FAILURE) } - Command::Ready { path: Some(path) } => { - let blockers = quest::ready::blockers(&cli.root, &path)?; + Command::Ready { + path: Some(path), + remote, + } => { + let blockers = quest::ready::blockers(&cli.root, &path, remote.as_deref())?; for blocker in &blockers { print!("{blocker}"); } @@ -75,8 +84,8 @@ fn main() -> Result { } Ok(ExitCode::SUCCESS) } - Command::Ready { path: None } => { - for path in quest::ready::quests(&cli.root)? { + Command::Ready { path: None, remote } => { + for path in quest::ready::quests(&cli.root, remote.as_deref())? { println!("{}", path.display()); } Ok(ExitCode::SUCCESS) diff --git a/src/ready.rs b/src/ready.rs index 62ade835..0a631983 100644 --- a/src/ready.rs +++ b/src/ready.rs @@ -61,9 +61,10 @@ impl fmt::Display for Blocker { /// holds. Empty means ready. /// /// `path` is the quest as the tree writes it (`/quest/m0/one.md`), as the shell -/// completes it (`quest/m0/one.md`), or as an absolute filesystem path. -pub fn blockers(root: &Path, path: &Path) -> Result> { - let docs = crate::load(root)?; +/// completes it (`quest/m0/one.md`), or as an absolute filesystem path. With a +/// `remote`, each line is read from its branch there; see [`crate::branch::overlay`]. +pub fn blockers(root: &Path, path: &Path, remote: Option<&str>) -> Result> { + let docs = crate::load_from(root, remote)?; let by_path: BTreeMap<&Path, &Doc> = docs.iter().map(|d| (d.path.as_path(), d)).collect(); let path = locate(root, path, &by_path)?; Ok(expand(&by_path, by_path[path.as_path()], &mut vec![path.clone()])) @@ -74,9 +75,9 @@ pub fn blockers(root: &Path, path: &Path) -> Result> { /// A questline is not listed while it still indexes children; a README with /// no `## Quests` left is the line's own remaining work and lists like any /// other quest. The absence of a `## Required` heading is what quest/AGENTS.md -/// defines as ready. -pub fn quests(root: &Path) -> Result> { - let docs = crate::load(root)?; +/// defines as ready. `remote` is as for [`blockers`]. +pub fn quests(root: &Path, remote: Option<&str>) -> Result> { + let docs = crate::load_from(root, remote)?; let mut remaining: BTreeMap = docs.iter().map(|doc| (doc.path.clone(), doc)).collect(); let mut pending = vec![PathBuf::from("quest/README.md")]; let mut ready = Vec::new(); diff --git a/tests/tree.rs b/tests/tree.rs index 435ea585..c65714a4 100644 --- a/tests/tree.rs +++ b/tests/tree.rs @@ -145,7 +145,7 @@ impl Tree { /// The rendered blocker chain: one line per blocker, nesting indented. fn blockers(&self, path: &str) -> Vec { - quest::ready::blockers(self.path(), Path::new(path)) + quest::ready::blockers(self.path(), Path::new(path), None) .expect("blockers") .iter() .flat_map(|blocker| blocker.to_string().lines().map(str::to_owned).collect::>()) @@ -153,13 +153,60 @@ impl Tree { } fn ready(&self) -> Vec { - quest::ready::quests(self.path()) + self.ready_on(None) + } + + fn ready_on(&self, remote: Option<&str>) -> Vec { + quest::ready::quests(self.path(), remote) .expect("ready") .iter() .map(|path| path.display().to_string()) .collect() } + fn git(&self, args: &[&str]) -> &Tree { + let status = std::process::Command::new("git") + .arg("-C") + .arg(self.path()) + .args(["-c", "user.name=Test", "-c", "user.email=test@example.com"]) + .args(args) + .status() + .expect("git"); + assert!(status.success(), "git {args:?}"); + self + } + + /// Commit the fixture to `main`, with an `origin` that is never contacted. + fn init_git(&self) -> &Tree { + self.git(&["init", "-q", "-b", "main"]) + .git(&["remote", "add", "origin", "https://example.invalid/repo.git"]) + .commit("main") + } + + fn commit(&self, message: &str) -> &Tree { + self.git(&["add", "-A"]).git(&["commit", "-q", "-m", message]) + } + + /// Commit whatever `edit` does as the remote copy of `branch`, then put the + /// working tree back on `main`. + fn push_line(&self, branch: &str, edit: impl FnOnce(&Tree)) -> &Tree { + self.git(&["checkout", "-q", "-b", branch]); + edit(self); + self.commit(branch) + .git(&["update-ref", &format!("refs/remotes/origin/{branch}"), "HEAD"]) + .git(&["checkout", "-q", "main"]) + } + + fn remove(&self, rel: &str) -> &Tree { + let path = self.path().join(rel); + if path.is_dir() { + std::fs::remove_dir_all(path).expect("rm"); + } else { + std::fs::remove_file(path).expect("rm"); + } + self + } + fn branch(&self, path: &str) -> Vec { quest::branch::chain(self.path(), Path::new(path)).expect("branch") } @@ -901,3 +948,75 @@ fn branch_chain_of_a_nested_line() { ] ); } + +// Line branches: `--remote` reads each line from its branch, where its +// children merge before the line reaches `main`. + +/// `one` finished on the line's branch, so `main` still lists it as ready and +/// `two` as blocked. Read through the branch, the answer flips. +#[test] +fn line_branch_hides_quests_finished_there() { + let tree = Tree::new(); + tree.init_git().push_line("quest/m0/line/README", |t| { + t.remove("quest/m0/line/one.md") + .write( + "quest/m0/line/README.md", + &LINE_README.replace("- [One](/quest/m0/line/one.md)\n", ""), + ) + .write("quest/m0/line/two.md", "# [S] Two\n\n## Goal\n\nAnother quest.\n"); + }); + assert_eq!(tree.ready(), ["quest/m0/line/one.md"]); + assert_eq!(tree.ready_on(Some("origin")), ["quest/m0/line/two.md"]); + assert!( + quest::ready::blockers(tree.path(), Path::new("quest/m0/line/two.md"), Some("origin")) + .expect("blockers") + .is_empty() + ); +} + +/// The nested line's branch is newer for its own subtree than the outer +/// line's, and once the outer branch completes the nested line, a branch left +/// behind by it must not bring the finished work back. +#[test] +fn nested_line_branch_wins_until_its_line_completes() { + let tree = Tree::new(); + tree.write( + "quest/m0/line/sub/README.md", + "# Sub\n\n## Goal\n\nA nested line.\n\n## Quests\n\n- [Three](/quest/m0/line/sub/three.md)\n", + ) + .write( + "quest/m0/line/sub/three.md", + "# [S] Three\n\n## Goal\n\nA nested quest.\n", + ) + .append("quest/m0/line/README.md", "- [Sub](/quest/m0/line/sub/README.md)\n"); + tree.accepts(); + tree.init_git(); + + // Every child of `sub` merged: its README is the line's own remaining work. + tree.push_line("quest/m0/line/sub/README", |t| { + t.remove("quest/m0/line/sub/three.md").write( + "quest/m0/line/sub/README.md", + "# [S] Sub\n\n## Goal\n\nThe end-to-end test.\n", + ); + }); + assert_eq!( + tree.ready_on(Some("origin")), + ["quest/m0/line/one.md", "quest/m0/line/sub/README.md"] + ); + + // Then `sub` itself landed on the outer line, whose branch has no `sub/`. + tree.push_line("quest/m0/line/README", |t| { + t.remove("quest/m0/line/sub") + .write("quest/m0/line/README.md", LINE_README); + }); + assert_eq!(tree.ready_on(Some("origin")), ["quest/m0/line/one.md"]); +} + +/// A remote that does not exist is a mistake, not a tree with no line branches. +#[test] +fn unknown_remote_is_an_error() { + let tree = Tree::new(); + tree.init_git(); + let err = quest::ready::quests(tree.path(), Some("upstream")).expect_err("unknown remote"); + assert!(err.to_string().contains("remote"), "{err}"); +} From f15dfa193e0f8d5352e261a24e703b8daf2d3213 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 26 Sep 2026 10:34:06 -0700 Subject: [PATCH 2/2] docs: rewrap the quest command bullet Co-Authored-By: Claude Opus 5.5 --- quest/AGENTS.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/quest/AGENTS.md b/quest/AGENTS.md index 0314baac..f806d616 100644 --- a/quest/AGENTS.md +++ b/quest/AGENTS.md @@ -65,10 +65,11 @@ Current decisions, open questions, or implementation guidance. - `quest check` enforces this structure; run it before submitting quest changes. `quest ready []` prints what blocks a quest, or every ready quest; `--remote origin` reads each line from its fetched branch, where its - children finish before `main` sees them. `quest branch ` prints the branch and every branch it merges - through, nearest first and ending at `main`. The root instructions say how - to run `quest` when it is not on `PATH`. It reads the tree alone: whether a - PR already claims a quest is GitHub's question. + children finish before `main` sees them. `quest branch ` prints the + branch and every branch it merges through, nearest first and ending at + `main`. The root instructions say how to run `quest` when it is not on + `PATH`. Only `--remote` reads git; nothing asks GitHub whether a PR already + claims a quest. ## Creation