From 7b787dac1f7053169cab78a13e5dd6481458d8ed Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 26 Sep 2026 09:48:32 -0700 Subject: [PATCH 1/4] chore(quest): vendor kixelated/quest instead of forking it Replace rs/quest, quest/AGENTS.md, and the four quest skills with a .claude/quest submodule pinned to kixelated/quest, so a workflow fix lands once for moq, moq.pro, and the standalone tool. `just quest ...` runs the pinned CLI; the SessionStart hook populates the submodule like .claude/shared. MoQ-only quest rules move to the root AGENTS.md. Co-Authored-By: Claude Opus 5.5 --- .claude/hooks/submodule.sh | 25 +- .claude/quest | 1 + .claude/skills/plan-issues | 1 + .claude/skills/plan-issues/SKILL.md | 7 - .claude/skills/plan-issues/agents/openai.yaml | 4 - .claude/skills/plan-quests | 1 + .claude/skills/plan-quests/SKILL.md | 44 - .claude/skills/plan-quests/agents/openai.yaml | 4 - .claude/skills/spawn-quests | 1 + .claude/skills/spawn-quests/SKILL.md | 35 - .../skills/spawn-quests/agents/openai.yaml | 4 - .claude/skills/start-quest | 1 + .claude/skills/start-quest/SKILL.md | 22 - .claude/skills/start-quest/agents/openai.yaml | 4 - .gitmodules | 3 + .remarkignore | 7 +- AGENTS.md | 4 + Cargo.lock | 27 - Cargo.toml | 3 - justfile | 20 +- quest/AGENTS.md | 116 +-- rs/quest/Cargo.toml | 21 - rs/quest/src/branch.rs | 32 - rs/quest/src/doc.rs | 318 ------- rs/quest/src/lib.rs | 67 -- rs/quest/src/main.rs | 91 -- rs/quest/src/ready.rs | 178 ---- rs/quest/src/rules.rs | 394 -------- rs/quest/tests/tree.rs | 871 ------------------ 29 files changed, 46 insertions(+), 2260 deletions(-) create mode 160000 .claude/quest create mode 120000 .claude/skills/plan-issues delete mode 100644 .claude/skills/plan-issues/SKILL.md delete mode 100644 .claude/skills/plan-issues/agents/openai.yaml create mode 120000 .claude/skills/plan-quests delete mode 100644 .claude/skills/plan-quests/SKILL.md delete mode 100644 .claude/skills/plan-quests/agents/openai.yaml create mode 120000 .claude/skills/spawn-quests delete mode 100644 .claude/skills/spawn-quests/SKILL.md delete mode 100644 .claude/skills/spawn-quests/agents/openai.yaml create mode 120000 .claude/skills/start-quest delete mode 100644 .claude/skills/start-quest/SKILL.md delete mode 100644 .claude/skills/start-quest/agents/openai.yaml mode change 100644 => 120000 quest/AGENTS.md delete mode 100644 rs/quest/Cargo.toml delete mode 100644 rs/quest/src/branch.rs delete mode 100644 rs/quest/src/doc.rs delete mode 100644 rs/quest/src/lib.rs delete mode 100644 rs/quest/src/main.rs delete mode 100644 rs/quest/src/ready.rs delete mode 100644 rs/quest/src/rules.rs delete mode 100644 rs/quest/tests/tree.rs diff --git a/.claude/hooks/submodule.sh b/.claude/hooks/submodule.sh index cda3fd4ace2..b4dc6630937 100755 --- a/.claude/hooks/submodule.sh +++ b/.claude/hooks/submodule.sh @@ -1,7 +1,8 @@ #!/usr/bin/env bash -# The shared skills in .claude/skills are symlinks into the .claude/shared -# submodule. git leaves that unpopulated in a new worktree, and a dangling -# symlink is silently skipped. A checkout on the wrong commit stays stale too. +# The shared and quest skills in .claude/skills are symlinks into the +# .claude/shared and .claude/quest submodules. git leaves those unpopulated in a +# new worktree, and a dangling symlink is silently skipped. A checkout on the +# wrong commit stays stale too. set -eu @@ -9,12 +10,14 @@ set -eu [ -n "${CLAUDE_PROJECT_DIR:-}" ] || exit 0 cd "$CLAUDE_PROJECT_DIR" || exit 0 -# '-' is uninitialized. '+' is populated at a commit other than the gitlink. -# A matching checkout has no prefix. -case "$(git submodule status .claude/shared 2>/dev/null)" in - -* | +*) ;; - *) exit 0 ;; -esac +for path in .claude/shared .claude/quest; do + # '-' is uninitialized. '+' is populated at a commit other than the gitlink. + # A matching checkout has no prefix. + case "$(git submodule status "$path" 2>/dev/null)" in + -* | +*) ;; + *) continue ;; + esac -echo "submodule hook: updating .claude/shared to the pinned skills." >&2 -git submodule update --init .claude/shared >&2 + echo "submodule hook: updating $path to the pinned commit." >&2 + git submodule update --init "$path" >&2 +done diff --git a/.claude/quest b/.claude/quest new file mode 160000 index 00000000000..53dc538b214 --- /dev/null +++ b/.claude/quest @@ -0,0 +1 @@ +Subproject commit 53dc538b214f6507545d30036e7a8af3a8519b7e diff --git a/.claude/skills/plan-issues b/.claude/skills/plan-issues new file mode 120000 index 00000000000..b80a201bcd9 --- /dev/null +++ b/.claude/skills/plan-issues @@ -0,0 +1 @@ +../quest/.claude/skills/plan-issues \ No newline at end of file diff --git a/.claude/skills/plan-issues/SKILL.md b/.claude/skills/plan-issues/SKILL.md deleted file mode 100644 index ea261e9c751..00000000000 --- a/.claude/skills/plan-issues/SKILL.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -name: plan-issues -description: Plan quests from open GitHub issues without the quest label. ---- - -Call /plan-quests for repository's open GitHub issues without the `quest` label. -Add the `quest` label to these issues after the PR merges. diff --git a/.claude/skills/plan-issues/agents/openai.yaml b/.claude/skills/plan-issues/agents/openai.yaml deleted file mode 100644 index e52345a27ad..00000000000 --- a/.claude/skills/plan-issues/agents/openai.yaml +++ /dev/null @@ -1,4 +0,0 @@ -interface: - display_name: "plan-issues" - short_description: "Turn unplanned GitHub issues into repository quests" - default_prompt: "Use $plan-issues to invoke $plan-quests for open GitHub issues without the quest label." diff --git a/.claude/skills/plan-quests b/.claude/skills/plan-quests new file mode 120000 index 00000000000..4a90495210d --- /dev/null +++ b/.claude/skills/plan-quests @@ -0,0 +1 @@ +../quest/.claude/skills/plan-quests \ No newline at end of file diff --git a/.claude/skills/plan-quests/SKILL.md b/.claude/skills/plan-quests/SKILL.md deleted file mode 100644 index 8ba5c9ff8e8..00000000000 --- a/.claude/skills/plan-quests/SKILL.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -name: plan-quests -description: Scope, create, and publish a quest through an interactive grilling interview. Use when the user invokes /plan-quests, asks to plan a quest, or wants unsettled work split into quests. ---- - -Before you begin, read `quest/AGENTS.md` completely. - -Interview the user until you reach a shared understanding. - -Work the tree in **rounds**. -The **frontier** is every decision whose prerequisites are already settled. -Ask the whole frontier in one round, interactively if supported. -Select at least one answer as (recommended) and wait for the user's answers (never guess) before the next round. - -Each round the user answers reshapes the tree: settled decisions push the frontier outward and unblock questions that depended on them. -Recompute the frontier and ask the next round. -A question whose answer depends on another question still open in this round belongs to a *later* round, not this one. - -Finding *facts* is your job, never the user's. -When a frontier question needs a fact from the environment (filesystem, tools, etc.), dispatch a sub-agent to find it. -Don't block on it, ask the rest of the frontier now. -The *decisions* are the user's: put each to them and wait. - -Search other quests and questlines to keep the larger plan consistent. -When the work changes what a user sees (a wire, an API, a flag, a dashboard), ask whether it needs documentation the feature quest cannot carry inline (a new page or guide), and recommend a quest for that; docs a change makes stale stay in that change. -When the frontier disagrees with a settled quest/plan, challenge the user and resolve the conflict. - -Begin the interview by scoping the goal: the observable outcome, why it matters, and its important boundaries and non-goals. -Restate the goal in one sentence and get it confirmed before moving on to implementation decisions. -If the goal contains independently completable outcomes, split them before planning. -Map the implementation plan as a design tree: every material decision branches into the decisions that hang off it. - -The session is done when the frontier is empty. -The result may be one quest or multiple quests and questlines, split based on what can be completed independently. -Prefix each quest title with `[XS]`, `[S]`, `[M]`, `[L]`, or `[XL]`, including implementation, verification, and landing work. -Once complete, create, update, or delete the relevant quests and questlines. -Record each settled decision and its reason in the quest's Plan, so later sessions don't ask it again. -New work joins the milestone matching its priority, at its rank; a questline groups only quests that ship together, and its README holds the work no child owns (the end-to-end test, the docs page). - -When done, commit and create a draft PR following `CONTRIBUTING.md`. -After local checks pass, mark it ready and monitor CI and the automatic reviews. -Address one review round, then stop and report if the next review still has findings. - -Merge the PR when ready. diff --git a/.claude/skills/plan-quests/agents/openai.yaml b/.claude/skills/plan-quests/agents/openai.yaml deleted file mode 100644 index 0aa796e75f0..00000000000 --- a/.claude/skills/plan-quests/agents/openai.yaml +++ /dev/null @@ -1,4 +0,0 @@ -interface: - display_name: "plan-quests" - short_description: "Scope and publish a repository quest" - default_prompt: "Use $plan-quests to scope and publish a repository quest." diff --git a/.claude/skills/spawn-quests b/.claude/skills/spawn-quests new file mode 120000 index 00000000000..4a6d46d65ee --- /dev/null +++ b/.claude/skills/spawn-quests @@ -0,0 +1 @@ +../quest/.claude/skills/spawn-quests \ No newline at end of file diff --git a/.claude/skills/spawn-quests/SKILL.md b/.claude/skills/spawn-quests/SKILL.md deleted file mode 100644 index b8e0f44ffab..00000000000 --- a/.claude/skills/spawn-quests/SKILL.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -name: spawn-quests -description: Spawn background agents work on quests in parallel. ---- - -Before you begin, read `quest/AGENTS.md` completely. - -Your goal is to execute, plan, and/or merge quests in parallel. -If you are unsure of the best course of action, ask the user for clarification before proceeding. - -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, or on `dev`, still looks ready from `main`. -Judge readiness from each line branch's own quest directory, and treat a quest deleted on `dev` as done. -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. - -Recommend an action for each quest: /start-quest, /plan-quests, skip, or delete. -Start the quests you'd start with no open question right away. -Interactively prompt the user about the rest, a few per prompt, each with a short summary and your recommendation. - -Spawn a background sub-agent for each /start-quest. -Create a fresh worktree on the base `quest branch` prints, creating that line branch first if it is missing. -Agents share no writable files: each keeps its scratch files in its own worktree's `.scratch/`, and anything you hand every agent goes in its prompt, not a shared file. -Each agent blocks on its own checks and reports back only when done or blocked. -Limit the concurrency to at most N agents in parallel, where N is half the number of physical CPU cores. -Other sessions share this machine: hold new agents while the load average exceeds the core count. - -Report each sub-agent's final status, staying silent on interim notifications, but do not monitor their PRs. -Prompt the user if they want to /plan-quests for any suggested follow-ups. - -Run /plan-quests for any selected quests in the foreground. -Perform any research and monitoring in the background. - -Finally, create a PR for any created/updated quests. diff --git a/.claude/skills/spawn-quests/agents/openai.yaml b/.claude/skills/spawn-quests/agents/openai.yaml deleted file mode 100644 index 84bd50b05b6..00000000000 --- a/.claude/skills/spawn-quests/agents/openai.yaml +++ /dev/null @@ -1,4 +0,0 @@ -interface: - display_name: "spawn-quests" - short_description: "Triage a milestone's quests and spawn agents for the ready ones" - default_prompt: "Use $spawn-quests to triage a scope's quests and spawn agents for the ones worth starting now." diff --git a/.claude/skills/start-quest b/.claude/skills/start-quest new file mode 120000 index 00000000000..37bf131f64a --- /dev/null +++ b/.claude/skills/start-quest @@ -0,0 +1 @@ +../quest/.claude/skills/start-quest \ No newline at end of file diff --git a/.claude/skills/start-quest/SKILL.md b/.claude/skills/start-quest/SKILL.md deleted file mode 100644 index 73d0911e40b..00000000000 --- a/.claude/skills/start-quest/SKILL.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -name: start-quest -description: Start work on a quest. ---- - -Before you begin, read `quest/AGENTS.md` completely. - -Your goal is to implement the quest, or as much of it as possible, and create a draft PR. -The argument is the quest to work on. - -If you are unsure on the best course of action, ask the user for direction. - -Confirm the quest is ready and unclaimed. -Claim it as `quest/AGENTS.md` describes: `quest branch` names the branch and its bases, missing line branches get a draft PR, and the quest branch gets an empty commit. - -Implement the quest until it is complete, or some blocker is hit, then create a PR against the base. -Keep scratch files (PR body, logs, notes) in the worktree's gitignored `.scratch/`. -Never write to or clean up a directory other agents share, such as a session scratchpad. - -When done, summarize any issues encounted, and suggest potential follow-up. -If you're happy with the outcome, switch the draft PR to ready for review. -If you want another set of eyes on it, keep it a draft. diff --git a/.claude/skills/start-quest/agents/openai.yaml b/.claude/skills/start-quest/agents/openai.yaml deleted file mode 100644 index 11280e5c900..00000000000 --- a/.claude/skills/start-quest/agents/openai.yaml +++ /dev/null @@ -1,4 +0,0 @@ -interface: - display_name: "start-quest" - short_description: "Find and start an unblocked repository quest" - default_prompt: "Use $start-quest to find unblocked repository quests and start my choice." diff --git a/.gitmodules b/.gitmodules index 25cd0e0737d..30329e64ba8 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,3 +1,6 @@ [submodule ".claude/shared"] path = .claude/shared url = https://github.com/kixelated/skills +[submodule ".claude/quest"] + path = .claude/quest + url = https://github.com/kixelated/quest diff --git a/.remarkignore b/.remarkignore index 5716b01a44d..1a863f0443c 100644 --- a/.remarkignore +++ b/.remarkignore @@ -16,9 +16,10 @@ doc/draft/ # Quests use a constrained Markdown dialect checked by the quest validator. quest/ -# Skills are symlinks into the kixelated/skills submodule, which formats its -# own files; remark would follow them (and .agents, Codex's link to the same -# directory) and rewrite the pinned checkout. +# Skills are symlinks into the kixelated/skills and kixelated/quest submodules, +# which format their own files; remark would follow them (and .agents, Codex's +# link to the same directory) and rewrite the pinned checkouts. .claude/shared/ +.claude/quest/ .claude/skills/ .agents/ diff --git a/AGENTS.md b/AGENTS.md index 494dbdaa8fb..ede129d13c4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -89,6 +89,10 @@ just fix # Auto-fix lint/formatting, same scope These diff the branch against its base and only run the affected packages. +Quests are vendored from kixelated/quest in the `.claude/quest` submodule, including `quest/AGENTS.md` and the quest skills; change them upstream. +Run the CLI as `just quest ...`. +A quest deleted on `dev` is done, even while `main` still lists it. + # Cross-Package Sync | Change in | Also update | diff --git a/Cargo.lock b/Cargo.lock index 73b7247c95f..71b92555d9a 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -6807,17 +6807,6 @@ version = "1.0.18" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "3d595e54a326bc53c1c197b32d295e14b169e3cfeaa8dc82b529f947fba6bcf5" -[[package]] -name = "pulldown-cmark" -version = "0.13.4" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "e9f068eba8e7071c5f9511831b44f32c740d5adf574e990f946ddb53db2f314e" -dependencies = [ - "bitflags 2.13.2", - "memchr", - "unicase", -] - [[package]] name = "pulseaudio" version = "0.3.1" @@ -6853,16 +6842,6 @@ dependencies = [ "web-transport-trait", ] -[[package]] -name = "quest" -version = "0.1.0" -dependencies = [ - "anyhow", - "clap", - "pulldown-cmark", - "tempfile", -] - [[package]] name = "quick-xml" version = "0.41.0" @@ -9214,12 +9193,6 @@ dependencies = [ "windows-sys 0.61.2", ] -[[package]] -name = "unicase" -version = "2.9.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "dbc4bc3a9f746d862c45cb89d705aa10f187bb96c76001afab07a0d35ce60142" - [[package]] name = "unicode-ident" version = "1.0.26" diff --git a/Cargo.toml b/Cargo.toml index 5f9dcd44315..40b1902a8a9 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -38,7 +38,6 @@ members = [ "rs/moq-v4l", "rs/moq-video", "rs/moq-wasm", - "rs/quest", "rs/uniffi-bindgen", ] default-members = [ @@ -79,7 +78,6 @@ default-members = [ "rs/moq-v4l", "rs/moq-video", # "rs/moq-wasm", # wasm32-unknown-unknown target only - "rs/quest", # Maturin runs the workspace's `uniffi-bindgen` binary from the root to # generate the Python wheel, and that only searches default members. A # `cargo build -p moq-ffi` still never compiles it. @@ -202,7 +200,6 @@ objc2-screen-capture-kit = "0.3.2" object_store = { version = "0.14", default-features = false } percent-encoding = "2" pollster = "1.0" -pulldown-cmark = { version = "0.13", default-features = false } qmux = { version = "0.5.1", default-features = false } rand = "0.10.1" # default-features off so each consumer picks its own TLS backend and body diff --git a/justfile b/justfile index 9d8af7a6636..a29dddeee5f 100644 --- a/justfile +++ b/justfile @@ -240,6 +240,16 @@ worktree ACTION="check" $BASE="": echo "recorded: $(git rev-parse --short "$recorded") (STALE; $base has moved since setup)" fi +# Run the quest CLI pinned by the .claude/quest submodule: `just quest ready`. +[positional-arguments] +quest *args: + #!/usr/bin/env bash + set -euo pipefail + # A fresh worktree or CI checkout leaves the submodule empty. Only an empty + # one is initialized, so an unstaged bump under test is left alone. + [[ -e .claude/quest/Cargo.toml ]] || git submodule update --init .claude/quest + cargo run --quiet --locked --manifest-path .claude/quest/Cargo.toml -- "$@" + # Install repo-wide tooling. Per-language deps install on first check. install: bun install @@ -441,7 +451,7 @@ _tools $FILES="": # `_check-common` runs on every invocation, so its tools are unconditional. tools=(actionlint bun jq nix nixfmt shellcheck shfmt taplo python3 nfpm dpkg-deb envsubst rpm) scoped '^(drafts/|doc/\.vitepress/drafts\.ts$)' && tools+=(kramdown-rfc xml2rfc) - scoped '^(bench/|quest/|rs/|Cargo\.(toml|lock)$|rust-toolchain\.toml$)' && tools+=(cargo envsubst) + scoped '^(bench/|quest/|\.claude/quest$|rs/|Cargo\.(toml|lock)$|rust-toolchain\.toml$)' && tools+=(cargo envsubst) scoped '^(py/|pyproject\.toml$|uv\.lock$|rs/moq-ffi/|doc/lib/py/|doc/lib/samples\.sh$)' && tools+=(uv) scoped '^(kt/|rs/moq-ffi/|doc/lib/kt/|doc/lib/samples\.sh$)' && tools+=(gradle java) # cargo because `go check` builds moq-ffi for the host, and skips on a @@ -542,7 +552,7 @@ _check $BASE $TEST: just rs tokio-features just rs media-features just --justfile bench/justfile check - cargo run --quiet --locked --package quest -- check + just quest check # Not covered by the line above: moq-wasm only exists on the wasm32 target. just rs wasm just py check @@ -565,9 +575,9 @@ _check $BASE $TEST: just drafts check fi # Quest documents form one graph, so validate the whole living tree when - # either a quest or its validator changes. - if echo "$files" | grep -qE '^(quest/|rs/quest/)'; then - cargo run --quiet --locked --package quest -- check + # either a quest or the pinned validator changes. + if echo "$files" | grep -qE '^(quest/|\.claude/quest$)'; then + just quest check fi just py check "$files" just kt check "$files" diff --git a/quest/AGENTS.md b/quest/AGENTS.md deleted file mode 100644 index 16eebac7aa5..00000000000 --- a/quest/AGENTS.md +++ /dev/null @@ -1,115 +0,0 @@ -# Quests - -Read this file whenever work mentions a quest or questline. - -Quests are versioned plans checked into the repository under `quest/`. GitHub -issues remain the public front door; prefer a quest for work that needs -durable scope or coordination. - -## Model - -- A quest is a Markdown file, completed in one PR. A questline is a directory - whose `README.md` is its quest: its `Quests` section lists the children, and - it completes when its own work is done and every child has merged. -- The root's entries are milestones, `m0`, `m1`, ..., grouping work by - priority horizon; lower numbers matter more. [README.md](README.md) says - what each holds. Priority, not breakage, decides the milestone, and starting - a quest does not move it. -- A document's branch is its path without `.md`: `quest/m1/foo/bar.md` is - branch `quest/m1/foo/bar`, and its line is `quest/m1/foo/README`. A quest - merges into its line's branch, a line into its parent's, and a milestone's - direct children into `main`. Milestones have no branch. -- A published API or wire break retargets to `dev` at PR time, per the root - `AGENTS.md`; a quest's Plan may note it. -- Every `Quests` list is ordered by priority. Insert at rank, never append. -- Link with root-absolute paths. Finished documents are deleted; git history - keeps them. Merge conflicts are expected; resolve them by aligning quests. - -## Format - -```markdown -# [S] Short title - -## Goal - -The observable outcome and important boundaries. - -## Plan - -Current decisions, open questions, or implementation guidance. - -## Quests - -- [Child quest](/quest/foo/bar.md) - the outcome, so the list reads without opening it -- [Nested questline](/quest/foo/baz/README.md) - what the whole line delivers - -## Required - -- [Blocker](/quest/bar.md) - work that must finish before this can start - -## Closes - -- [#701](https://github.com/moq-dev/moq/issues/701) - close this issue when the quest finishes - -## Related - -- [Other](/quest/other.md) - similar work that is not a blocker -``` - -- `Goal` is required; everything else is optional. Use these exact headings. -- Size the title `[XS]` to `[XL]` for implementation, verification, and - landing. A README with children carries no size; one without is a plain - quest and needs one. -- Only a README has `Quests`. `Required` lists what must finish before the - work starts; no section means ready. A required questline clears when the - whole line has merged. A plain-text bullet names a condition outside the - repository; remove it when it clears. `Required` must be acyclic. -- `quest check` enforces this structure; `just check` runs it on any branch - touching `quest/`. `quest ready []` prints what blocks a quest, or - every ready quest. `quest branch ` prints the branch and every branch - it merges through, nearest first and ending at `main`. Run them as - `cargo run --quiet --locked --package quest -- ...`. They read the tree - alone: whether a PR already claims a quest is GitHub's question. - -## Creation - -- Quests are created in PRs and reviewed. Search the tree and git history - first. -- Split independently completable work into separate quests. Group them in a - questline only when they ship together, and give the README the work no - child owns: the end-to-end test, the docs page. -- New work joins the milestone matching its priority, at its rank. -- Every issue under `Closes` carries the `quest` GitHub label - (`gh issue edit --add-label quest`), applied when the quest lands. - `Related` is context and gets none. -- A release or pin bump that unblocks work is its own quest holding the - condition as a plain-text `Required` bullet; every dependent requires it. - -## Execution - -- Start only ready quests. `quest branch` names the branch and its bases: push - each missing line branch from the one after it and open its draft PR against - that base, then push the quest's branch with an empty commit. The remote - branch is the claim; continue only if an existing one is stale (old, no open - PR). -- Set the upstream to the base so `just check` scopes against - it. Keep a line current by merging its base in; never rebase a shared branch. -- Update the quest as the plan changes. Complete it when no work remains, and - suggest follow-ups as new quests. -- Open the PR per [CONTRIBUTING.md](../CONTRIBUTING.md) against the base, with - a closing keyword for every issue under `Closes`, including those of any - questline the same PR completes. -- A line's PR stays a draft until its `Quests` list is empty. The PR that - removes the last child sizes the README's title; the README is then a ready - quest whose completion marks the line's PR ready and merges it. - -## Deletion - -- A quest that is no longer needed or cannot be completed is abandoned: delete - it and explain why in the PR. Remove the `quest` label from issues no other - quest tracks. -- Delete a quest in the PR that completes or abandons it. Grep its absolute - path and remove every reference; that reveals what it unblocks. Remove a - heading with its last entry. -- Deleting a README deletes its directory. The root and the milestones are - permanent: an empty milestone stays as a horizon. diff --git a/quest/AGENTS.md b/quest/AGENTS.md new file mode 120000 index 00000000000..0ab54696207 --- /dev/null +++ b/quest/AGENTS.md @@ -0,0 +1 @@ +../.claude/quest/quest/AGENTS.md \ No newline at end of file diff --git a/rs/quest/Cargo.toml b/rs/quest/Cargo.toml deleted file mode 100644 index 0bef17e7eef..00000000000 --- a/rs/quest/Cargo.toml +++ /dev/null @@ -1,21 +0,0 @@ -[package] -name = "quest" -version = "0.1.0" -edition = "2024" -rust-version.workspace = true -authors = ["Luke Curley"] -license = "MIT OR Apache-2.0" -publish = false -description = "Validator and readiness gate for the quest tree: the interlinked Markdown plans under quest/, whose contract is quest/AGENTS.md. Enforces link resolution, the questline index, the heading vocabulary, and an acyclic Required graph, so a structural mistake fails the PR instead of the next reader, reports what blocks a quest so a flow does not reconstruct that by grepping, and names the branches a quest lands on." - -[[bin]] -name = "quest" -path = "src/main.rs" - -[dependencies] -anyhow.workspace = true -clap.workspace = true -pulldown-cmark.workspace = true - -[dev-dependencies] -tempfile.workspace = true diff --git a/rs/quest/src/branch.rs b/rs/quest/src/branch.rs deleted file mode 100644 index 000e039a928..00000000000 --- a/rs/quest/src/branch.rs +++ /dev/null @@ -1,32 +0,0 @@ -//! Which branch carries a quest, and which branches it merges through. -//! -//! 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. - -use std::collections::BTreeMap; -use std::path::Path; - -use anyhow::{Result, bail}; - -use crate::doc::Doc; - -/// The branch for `path`, then every branch it merges through, nearest first -/// and ending at `main`. -pub fn chain(root: &Path, path: &Path) -> Result> { - let docs = crate::load(root)?; - let by_path: BTreeMap<&Path, &Doc> = docs.iter().map(|d| (d.path.as_path(), d)).collect(); - let mut cur = crate::ready::locate(root, path, &by_path)?; - let mut out = Vec::new(); - while !Doc::permanent(&cur) { - out.push(cur.with_extension("").display().to_string()); - cur = Doc::owner(&cur).join("README.md"); - } - if out.is_empty() { - bail!("{} is the root or a milestone, which has no branch", path.display()); - } - out.push("main".to_string()); - Ok(out) -} diff --git a/rs/quest/src/doc.rs b/rs/quest/src/doc.rs deleted file mode 100644 index 11c2f0794cc..00000000000 --- a/rs/quest/src/doc.rs +++ /dev/null @@ -1,318 +0,0 @@ -//! Parsing one quest document into the facts every rule reads. -//! -//! This is a real Markdown AST rather than line matching. The shell version -//! that came before it was defeated by a fence longer than three backticks -//! (which inverted its fence tracking and silently skipped the rest of the -//! file), by a `Required` bullet that wrapped onto a second line (which moved -//! the link out of reach of the check that exists to catch it), and by -//! reference-style links (which produced a rendered dependency with no edge). -//! None of those are special cases here; the parser simply reports the -//! structure that Markdown actually has. - -use std::path::{Path, PathBuf}; - -use anyhow::{Context, Result}; -use pulldown_cmark::{Event, HeadingLevel, Options, Parser, Tag, TagEnd}; - -/// Where a link sits inside its `## Section`, which is what separates a -/// dependency edge from prose that merely mentions one. -#[derive(Clone, Copy, Debug, PartialEq, Eq)] -pub enum Position { - /// The link opens a list item, ignoring any emphasis around it. This is the - /// shape every `Required` blocker and every `Quests` entry must have. - Entry, - /// Somewhere else inside a list item: a sentence that happens to link. - Inside, - /// Outside any list item. - Prose, -} - -/// One Markdown link, located precisely enough to be a graph edge. -#[derive(Clone, Debug)] -pub struct Link { - /// 1-based source line, for findings. - pub line: usize, - /// The enclosing `## Heading`, or `None` above the first one. - pub section: Option, - /// The destination exactly as written, fragment included. - pub target: String, - /// Where the link sits in its section; see [`Position`]. - pub position: Position, -} - -/// One top-level list entry: the shape a `Required` blocker and a `Quests` -/// index entry both have. -#[derive(Clone, Debug)] -pub struct Entry { - /// 1-based source line, for findings. - pub line: usize, - /// The enclosing `## Heading`, or `None` above the first one. - pub section: Option, - /// The rendered text with whitespace collapsed, so a bullet that wrapped - /// onto a second line reads as the one line it renders as. - pub text: String, - /// The destination of the link that opens the entry, if one does. This is - /// the [`Position::Entry`] link, so it is a dependency rather than a - /// sentence that happens to mention one. - pub target: Option, -} - -/// One `# ` or `## ` heading as the rules need to see it. -#[derive(Clone, Debug)] -pub struct Heading { - /// 1-based source line, for findings. - pub line: usize, - /// The rendered heading text, trimmed. - pub text: String, - /// The source really is `# Text` or `## Text` on its own line. Setext and - /// decorated headings render the same, but literal syntax is the contract. - pub literal: bool, -} - -/// One parsed quest document: the structure the rules read, nothing else. -#[derive(Clone, Debug)] -pub struct Doc { - /// Repository-relative, e.g. `quest/m0/one.md`. - pub path: PathBuf, - /// The document's `# ` title, used for a quest's t-shirt size. - pub title: Option, - /// `## ` headings only. Deeper levels are free-form prose structure. - pub headings: Vec, - /// Every link in the document, in source order. - pub links: Vec, - /// Every top-level list item, in source order. A heading left behind by its - /// last entry has none, and a `Required` blocker is one of these whether or - /// not it carries a link. - pub entries: Vec, -} - -impl Doc { - /// Whether the document has this exact `## ` heading. - pub fn has(&self, heading: &str) -> bool { - self.headings.iter().any(|h| h.text == heading) - } - - /// The top-level entries under a `## ` section, in source order. - pub fn entries(&self, section: &str) -> impl Iterator { - self.entries - .iter() - .filter(move |e| e.section.as_deref() == Some(section)) - } - - /// A questline is a `README.md` with a `Quests` section. Any other README is - /// what a line becomes when its last child merges: the line's own remaining - /// work, executed like any other quest. The root and the milestones are the exception. - pub fn is_questline(&self) -> bool { - self.is_readme() && (self.has("Quests") || Self::permanent(&self.path)) - } - - /// The root and the milestones outlive their quests, so an empty one is not - /// a leaf. - pub fn permanent(path: &Path) -> bool { - path.file_name().is_some_and(|n| n == "README.md") && path.components().count() <= 3 - } - - fn is_readme(&self) -> bool { - self.path.file_name().is_some_and(|n| n == "README.md") - } - - /// The questline directory this document belongs to. A questline is a - /// DIRECTORY, so its own entry sits one level further out than a quest's: - /// `quest/m1/drain/README.md` belongs to `quest/m1`, not to `quest/m1/drain`. - pub fn owner(path: &Path) -> PathBuf { - let parent = path.parent().unwrap_or(Path::new("")); - if path.file_name().is_some_and(|n| n == "README.md") { - parent.parent().unwrap_or(Path::new("")).to_path_buf() - } else { - parent.to_path_buf() - } - } - - /// Read and parse `/`; `path` stays repository-relative. - pub fn parse(root: &Path, path: PathBuf) -> Result { - let text = std::fs::read_to_string(root.join(&path)).with_context(|| format!("reading {}", path.display()))?; - Ok(Self::from_str(path, &text)) - } - - /// Parse already-loaded Markdown; this is the whole parser, `parse` just adds IO. - pub fn from_str(path: PathBuf, text: &str) -> Doc { - let lines = LineIndex::new(text); - let text_src = text; - - let mut title = None; - let mut headings = Vec::new(); - let mut links = Vec::new(); - let mut entries: Vec = Vec::new(); - let mut entry: Option = None; - let mut section: Option = None; - - // Depth of nesting, so a sub-list inside an entry does not read as a - // second entry, and so `fresh` tracks the innermost item. - let mut item_depth = 0usize; - // Entries are the flat, top-level list. A bullet nested under a prose - // lead-in, or one inside a block quote, is illustration - counting it - // would let `- evidence:` + an indented link become a real blocker. - let mut quote_depth = 0usize; - // Nothing but emphasis has been seen since the current item opened, so a - // link here is the item's opening link. `**[Blocker](/quest/b.md)**` is - // still an opener; `A customer who justifies [b](/quest/b.md)` is not. - let mut fresh = false; - let mut heading: Option<(HeadingLevel, usize, String)> = None; - - let mut options = Options::empty(); - options.insert(Options::ENABLE_STRIKETHROUGH); - options.insert(Options::ENABLE_TABLES); - - for (event, range) in Parser::new_ext(text, options).into_offset_iter() { - match event { - Event::Start(Tag::Heading { level, .. }) if matches!(level, HeadingLevel::H1 | HeadingLevel::H2) => { - heading = Some((level, lines.line_of(range.start), String::new())); - } - Event::End(TagEnd::Heading(level)) if matches!(level, HeadingLevel::H1 | HeadingLevel::H2) => { - if let Some((start_level, line, text)) = heading.take() { - debug_assert_eq!(start_level, level); - let text = text.trim().to_string(); - // Exact, not trimmed: `rg '^## Required$'` does not match a - // line with trailing spaces either, and this rule exists - // precisely so the two can never disagree. - let prefix = if level == HeadingLevel::H1 { "#" } else { "##" }; - let parsed = Heading { - line, - literal: lines.text_of(text_src, line) == format!("{prefix} {text}"), - text: text.clone(), - }; - if level == HeadingLevel::H1 { - title = Some(parsed); - } else { - section = Some(text); - headings.push(parsed); - } - } - item_depth = 0; - entry = None; - fresh = false; - } - Event::Start(Tag::BlockQuote(..)) => { - quote_depth += 1; - fresh = false; - } - Event::End(TagEnd::BlockQuote(..)) => { - quote_depth = quote_depth.saturating_sub(1); - fresh = false; - } - Event::Start(Tag::Item) => { - if item_depth == 0 && quote_depth == 0 { - entry = Some(Entry { - line: lines.line_of(range.start), - section: section.clone(), - text: String::new(), - target: None, - }); - } - item_depth += 1; - fresh = true; - } - Event::End(TagEnd::Item) => { - if item_depth == 1 - && let Some(mut done) = entry.take() - { - done.text = collapse(&done.text); - entries.push(done); - } - item_depth = item_depth.saturating_sub(1); - fresh = false; - } - Event::Start(Tag::Link { dest_url, .. }) => { - // Reference-style links arrive here already resolved to their - // destination, so they carry an edge like any other link. - // Only a top-level, unquoted item can hold an entry. - let position = if item_depth == 0 { - Position::Prose - } else if fresh && item_depth == 1 && quote_depth == 0 { - Position::Entry - } else { - Position::Inside - }; - fresh = false; - if position == Position::Entry - && let Some(entry) = entry.as_mut() - { - entry.target = Some(dest_url.to_string()); - } - links.push(Link { - line: lines.line_of(range.start), - section: section.clone(), - target: dest_url.to_string(), - position, - }); - } - // Emphasis wraps an opening link without displacing it, and so does - // the paragraph a LOOSE list puts around every item: clearing on - // its START would classify every entry in a blank-line-separated - // list as mid-sentence prose. Its END does clear, so a link that - // opens a SECOND paragraph is inside the item, not opening it. - Event::Text(ref t) | Event::Code(ref t) => { - if let Some((_, _, buf)) = heading.as_mut() { - buf.push_str(t); - } else if let Some(entry) = entry.as_mut() { - entry.text.push_str(t); - } - if !t.trim().is_empty() { - fresh = false; - } - } - Event::Start(Tag::Emphasis | Tag::Strong | Tag::Paragraph) - | Event::End(TagEnd::Emphasis | TagEnd::Strong) => {} - Event::End(TagEnd::Paragraph) => fresh = false, - Event::SoftBreak | Event::HardBreak => { - if let Some(entry) = entry.as_mut() { - entry.text.push(' '); - } - } - _ => { - if item_depth > 0 { - fresh = false; - } - } - } - } - - Doc { - path, - title, - headings, - links, - entries, - } - } -} - -/// One line of whitespace-separated words, so a wrapped or loosely indented -/// bullet prints the way it renders. -fn collapse(text: &str) -> String { - text.split_whitespace().collect::>().join(" ") -} - -/// Byte offset -> 1-based line number, so findings can name a line. -struct LineIndex { - starts: Vec, -} - -impl LineIndex { - fn new(text: &str) -> LineIndex { - let mut starts = vec![0]; - starts.extend(text.match_indices('\n').map(|(i, _)| i + 1)); - LineIndex { starts } - } - - fn line_of(&self, offset: usize) -> usize { - self.starts.partition_point(|&start| start <= offset) - } - - /// The source of a 1-based line, without its newline. - fn text_of<'a>(&self, text: &'a str, line: usize) -> &'a str { - let start = self.starts.get(line - 1).copied().unwrap_or(text.len()); - let end = self.starts.get(line).copied().unwrap_or(text.len()); - text[start..end].trim_end_matches('\n') - } -} diff --git a/rs/quest/src/lib.rs b/rs/quest/src/lib.rs deleted file mode 100644 index 2845f241ac8..00000000000 --- a/rs/quest/src/lib.rs +++ /dev/null @@ -1,67 +0,0 @@ -//! The quest tree, whose contract is quest/AGENTS.md: structural validation of -//! it, whether a given quest can be started, and which branches carry it. -//! -//! The whole tree is validated on every run, never just the changed files: the -//! link graph and the questline 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 all. - -pub mod branch; -pub mod doc; -pub mod ready; -pub mod rules; - -use std::path::{Path, PathBuf}; - -use anyhow::{Context, Result, bail}; - -pub use doc::Doc; -pub use ready::Blocker; -pub use rules::Finding; - -/// AGENTS.md is the contract rather than a quest: not executable work, so -/// neither indexed nor validated. -const NOT_QUESTS: [&str; 1] = ["AGENTS.md"]; - -/// Every quest document under `/quest`, sorted, repository-relative. -pub fn collect(root: &Path) -> Result> { - let mut out = Vec::new(); - walk(root, &root.join("quest"), &mut out).with_context(|| format!("scanning {}", root.join("quest").display()))?; - out.sort(); - Ok(out) -} - -fn walk(root: &Path, dir: &Path, out: &mut Vec) -> Result<()> { - for entry in std::fs::read_dir(dir)? { - let entry = entry?; - let path = entry.path(); - // `file_type` does not follow symlinks, so quest/AGENTS.md is a file - // here and a directory symlink can never make this recurse forever. - 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)) - { - out.push(path.strip_prefix(root).unwrap_or(&path).to_path_buf()); - } - } - Ok(()) -} - -/// Parse and validate the tree. Returns every finding, worst-case empty. -pub fn check(root: &Path) -> Result> { - Ok(rules::check(root, &load(root)?)) -} - -/// Every quest document, parsed, in tree order. -fn load(root: &Path) -> Result> { - let paths = collect(root)?; - if paths.is_empty() { - bail!("no quest documents found under {}", root.join("quest").display()); - } - paths.into_iter().map(|p| Doc::parse(root, p)).collect() -} diff --git a/rs/quest/src/main.rs b/rs/quest/src/main.rs deleted file mode 100644 index 27135981cdb..00000000000 --- a/rs/quest/src/main.rs +++ /dev/null @@ -1,91 +0,0 @@ -use std::path::PathBuf; -use std::process::ExitCode; - -use anyhow::Result; -use clap::{Parser, Subcommand}; - -/// The quest tree, the interlinked Markdown plans under quest/ whose contract is -/// quest/AGENTS.md: validate its structure, report what blocks a quest, or name -/// the branches a quest lands on. -#[derive(Parser)] -#[command(version, about)] -struct Cli { - /// Repository root holding the quest/ directory. - #[arg(long, default_value = ".", global = true)] - root: PathBuf, - - #[command(subcommand)] - command: Command, -} - -#[derive(Subcommand)] -enum Command { - /// Report every structural mistake in the tree; exit non-zero if any. - Check, - - /// Print what blocks a quest, or list every ready quest. - /// - /// Exits 0 either way: the blocker list on stdout is the result, so no - /// output means ready and a caller tests that rather than parsing prose. A - /// non-zero exit means the command itself failed. - Ready { - /// Quest to explain. Omit to list every ready quest in tree order. - path: Option, - }, - - /// Print the branch carrying a quest, then every branch it merges through. - /// - /// One per line, nearest first, ending at `main`: a quest merges into its - /// questline's branch, a questline into its parent's, and a milestone's - /// children into `main`. A line missing from the remote is created from the - /// one printed after it. - Branch { - /// Quest or questline to locate. - path: PathBuf, - }, -} - -fn main() -> Result { - let cli = Cli::parse(); - match cli.command { - Command::Check => { - let findings = quest::check(&cli.root)?; - if findings.is_empty() { - let total = quest::collect(&cli.root)?.len(); - println!("quest: {total} documents ok"); - return Ok(ExitCode::SUCCESS); - } - for finding in &findings { - eprintln!("quest: {finding}"); - } - Ok(ExitCode::FAILURE) - } - Command::Ready { path: Some(path) } => { - let blockers = quest::ready::blockers(&cli.root, &path)?; - for blocker in &blockers { - print!("{blocker}"); - } - if !blockers.is_empty() { - // Blocked is not a verdict on the whole plan: the piece of it - // that does not need the blocker is split into its own quest. - eprintln!( - "quest: {} is blocked; split any independently landable piece into its own quest (quest/AGENTS.md, Creation) rather than starting this one as it stands", - path.display() - ); - } - Ok(ExitCode::SUCCESS) - } - Command::Ready { path: None } => { - for path in quest::ready::quests(&cli.root)? { - println!("{}", path.display()); - } - Ok(ExitCode::SUCCESS) - } - Command::Branch { path } => { - for branch in quest::branch::chain(&cli.root, &path)? { - println!("{branch}"); - } - Ok(ExitCode::SUCCESS) - } - } -} diff --git a/rs/quest/src/ready.rs b/rs/quest/src/ready.rs deleted file mode 100644 index 62ade835ee6..00000000000 --- a/rs/quest/src/ready.rs +++ /dev/null @@ -1,178 +0,0 @@ -//! Whether a quest can be started, read from the same `Required` sections 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 -//! is still open. Liveness is the other question - a quest can be ready, -//! coherent, and already done by some other PR - and answering it means asking -//! GitHub, so it belongs to the flow that is already talking to it. - -use std::collections::BTreeMap; -use std::fmt; -use std::path::{Path, PathBuf}; - -use anyhow::{Result, bail}; - -use crate::doc::Doc; -use crate::rules; - -/// One thing standing between a quest and being started. -#[derive(Clone, Debug, PartialEq, Eq)] -pub struct Blocker { - /// The quest or questline that has to finish first, when the blocker is one - /// of ours. `None` is a plain-text condition, which nothing in the tree can - /// ever clear. - pub path: Option, - /// The `Required` bullet as written, whitespace collapsed. - pub text: String, - /// The still-open quests under a required questline, which is what a - /// questline blocker actually means. Empty for every other blocker: a - /// required quest's own blockers are its readiness, not this one's. - pub blockers: Vec, -} - -impl Blocker { - /// What names the blocker: the document, or the condition's own words. - pub fn label(&self) -> String { - match &self.path { - Some(path) => path.display().to_string(), - None => self.text.clone(), - } - } - - fn write(&self, f: &mut fmt::Formatter<'_>, depth: usize) -> fmt::Result { - writeln!(f, "{}{}", " ".repeat(depth), self.label())?; - for blocker in &self.blockers { - blocker.write(f, depth + 1)?; - } - Ok(()) - } -} - -impl fmt::Display for Blocker { - /// The whole chain, one blocker per line and indented by depth, newline - /// included: a caller prints these back to back. - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - self.write(f, 0) - } -} - -/// What blocks `path`, a required questline expanded into the quests it still -/// 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)?; - 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()])) -} - -/// Every quest that can be started now, in tree order. -/// -/// 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)?; - 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(); - while let Some(path) = pending.pop() { - let Some(doc) = remaining.remove(&path) else { continue }; - if doc.is_questline() { - let children: Vec<_> = doc - .entries("Quests") - .filter_map(|entry| entry.target.as_deref().and_then(rules::rooted)) - .collect(); - pending.extend(children.into_iter().rev()); - } else if !doc.has("Required") { - ready.push(path); - } - } - ready.extend( - remaining - .into_iter() - .filter(|(_, doc)| !doc.is_questline() && !doc.has("Required")) - .map(|(path, _)| path), - ); - Ok(ready) -} - -/// The blockers of one document: a quest waits on its `Required` entries, and a -/// questline is complete only when all of its quests are, so it waits on those. -fn expand(by_path: &BTreeMap<&Path, &Doc>, doc: &Doc, stack: &mut Vec) -> Vec { - let section = if doc.is_questline() { "Quests" } else { "Required" }; - - // A heading left standing after its last blocker still reads as blocked to - // everything that greps for it, including `quest check`, which reports it. - // Calling it ready here would make this the one tool that disagrees. - if !doc.is_questline() && doc.has("Required") && doc.entries("Required").next().is_none() { - return vec![Blocker { - path: None, - text: "an empty '## Required' section, which blocks the quest until the heading is removed".to_string(), - blockers: Vec::new(), - }]; - } - - doc.entries(section) - .map(|entry| blocker(by_path, entry, stack)) - .collect() -} - -fn blocker(by_path: &BTreeMap<&Path, &Doc>, entry: &crate::doc::Entry, stack: &mut Vec) -> Blocker { - // A bullet that does not open with a link into the tree is a plain-text - // condition: an issue, a release, a customer. Nothing here can clear it, so - // it is a blocker with nothing under it. - let path = entry - .target - .as_deref() - .and_then(rules::rooted) - .filter(|path| by_path.contains_key(path.as_path())); - - // Only a questline 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 a - // questline listing an ancestor must print rather than recurse forever. - let blockers = match &path { - Some(path) if by_path[path.as_path()].is_questline() && !stack.contains(path) => { - stack.push(path.clone()); - let blockers = expand(by_path, by_path[path.as_path()], stack); - stack.pop(); - blockers - } - _ => Vec::new(), - }; - - Blocker { - path, - text: entry.text.clone(), - blockers, - } -} - -/// Resolve a quest path the way a caller is likely to have it to the -/// repository-relative one the tree is keyed on. -pub(crate) fn locate(root: &Path, path: &Path, by_path: &BTreeMap<&Path, &Doc>) -> Result { - let mut candidates = vec![rules::normalize(path)]; - if let Some(rooted) = path.to_str().and_then(|p| p.strip_prefix('/')) { - candidates.push(rules::normalize(Path::new(rooted))); - } - if let (Ok(absolute), Ok(root)) = (path.canonicalize(), root.canonicalize()) - && let Ok(relative) = absolute.strip_prefix(root) - { - candidates.push(relative.to_path_buf()); - } - - match candidates.into_iter().find(|c| by_path.contains_key(c.as_path())) { - Some(found) => Ok(found), - None => bail!( - "{} is not a quest document under {}", - path.display(), - root.join("quest").display() - ), - } -} diff --git a/rs/quest/src/rules.rs b/rs/quest/src/rules.rs deleted file mode 100644 index 923865ecf23..00000000000 --- a/rs/quest/src/rules.rs +++ /dev/null @@ -1,394 +0,0 @@ -//! The rules, and the findings they produce. -//! -//! The contract is quest/AGENTS.md. Every rule here is one that has already -//! been broken by hand, and the expensive failure is a rule that stops firing: -//! a validator that quietly enforces nothing looks exactly like a clean tree. - -use std::collections::{BTreeMap, BTreeSet}; -use std::path::{Path, PathBuf}; - -use crate::doc::{Doc, Position}; - -/// The `## ` headings a quest document may use. Readiness greps `## Required` -/// literally, so a typo turns a blocked quest ready and fails nowhere else: -/// the closed vocabulary is what catches it. -const HEADINGS: [&str; 6] = ["Goal", "Plan", "Required", "Closes", "Related", "Quests"]; -const SIZES: [&str; 5] = ["XS", "S", "M", "L", "XL"]; - -/// Sections whose whole content is a list. A heading left standing after its -/// last entry was removed is a bug in both directions: an empty `Required` -/// blocks its quest forever, and an empty `Quests` leaves a questline that -/// should have been deleted with its last quest. -/// `Quests` is deliberately absent: a bullet is not an entry (`- TBD` is a list -/// item with no quest in it), so its emptiness is decided by counting valid -/// entries in `index` instead. -const LIST_SECTIONS: [&str; 3] = ["Required", "Closes", "Related"]; - -/// The permanent root questline; the one document nothing has to list. -pub const ROOT: &str = "quest/README.md"; - -/// One violation, addressed like a compiler diagnostic: `path:line: message`. -#[derive(Debug, PartialEq, Eq, PartialOrd, Ord)] -pub struct Finding { - /// Repository-relative document the violation is in. - pub path: PathBuf, - /// 1-based line, when the violation has one; `None` for whole-file findings. - pub line: Option, - /// What is wrong, and often why the rule exists. - pub message: String, -} - -impl std::fmt::Display for Finding { - fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { - match self.line { - Some(line) => write!(f, "{}:{}: {}", self.path.display(), line, self.message), - None => write!(f, "{}: {}", self.path.display(), self.message), - } - } -} - -struct Findings(Vec); - -impl Findings { - fn at(&mut self, path: &Path, line: usize, message: impl Into) { - self.0.push(Finding { - path: path.to_path_buf(), - line: Some(line), - message: message.into(), - }); - } - - fn on(&mut self, path: &Path, message: impl Into) { - self.0.push(Finding { - path: path.to_path_buf(), - line: None, - message: message.into(), - }); - } -} - -/// `root` is the repository root; every path in `docs` is relative to it. -pub fn check(root: &Path, docs: &[Doc]) -> Vec { - let mut found = Findings(Vec::new()); - let known: BTreeSet<&Path> = docs.iter().map(|d| d.path.as_path()).collect(); - - for doc in docs { - headings(&mut found, doc); - links(&mut found, root, &known, doc); - } - - let index = index(&mut found, &known, docs); - cycles(&mut found, docs, &index); - - found.0.sort(); - found.0 -} - -fn headings(found: &mut Findings, doc: &Doc) { - if !doc.is_questline() { - let valid = doc.title.as_ref().is_some_and(|title| { - let Some((size, name)) = title.text.strip_prefix('[').and_then(|s| s.split_once("] ")) else { - return false; - }; - title.literal && SIZES.contains(&size) && !name.is_empty() - }); - if !valid { - found.on(&doc.path, "quest title must be '# [XS|S|M|L|XL] Title'"); - } - } - - if !doc.has("Goal") { - found.on(&doc.path, "missing '## Goal'"); - } - - for heading in &doc.headings { - // A setext underline and a decorated ``## `Required` `` both render as - // the same heading, and this validator would treat the quest as blocked. - // Readiness greps `^## Required$` literally and would call it READY. - if HEADINGS.contains(&heading.text.as_str()) && !heading.literal { - found.at( - &doc.path, - heading.line, - format!( - "'{}' must be written literally as '## {}'; readiness greps that form and would not see this one", - heading.text, heading.text - ), - ); - } - if !HEADINGS.contains(&heading.text.as_str()) { - found.at( - &doc.path, - heading.line, - format!("unknown '## {}' (allowed: {})", heading.text, HEADINGS.join(", ")), - ); - } - } - - // Only a README indexes children; a quest is a leaf and must not, since the - // index is what makes a file a questline and questlines are not picked up. - if doc.has("Quests") && !doc.is_questline() { - found.on(&doc.path, "only a README may have '## Quests'"); - } - for heading in &doc.headings { - if LIST_SECTIONS.contains(&heading.text.as_str()) && doc.entries(&heading.text).next().is_none() { - let why = match heading.text.as_str() { - "Required" => "; an empty one blocks the quest forever, so remove the heading with its last entry", - "Quests" => "; a questline with no quests left should be deleted", - _ => "; remove the heading with its last entry", - }; - found.at(&doc.path, heading.line, format!("'## {}' is empty{why}", heading.text)); - } - } -} - -/// Strip a `#fragment`, which addresses a place inside a file rather than a -/// different file. Leaving it on made a phantom graph node that no quest could -/// ever match, so a cycle through an anchored link went unreported. -fn without_fragment(target: &str) -> &str { - target.split('#').next().unwrap_or(target) -} - -/// A root-absolute target as a repository-relative path, or `None` if it is not -/// root-absolute. Fragment-stripped AND normalized: the index and the cycle walk -/// both key on this, and a `..` left in one of them is a node nothing matches. -pub(crate) fn rooted(target: &str) -> Option { - target - .strip_prefix('/') - .map(|r| normalize(Path::new(without_fragment(r)))) -} - -fn resolve(doc_path: &Path, target: &str) -> PathBuf { - match target.strip_prefix('/') { - Some(rooted) => normalize(Path::new(rooted)), - None => normalize(&doc_path.parent().unwrap_or(Path::new("")).join(target)), - } -} - -/// Collapse `..` textually. `Path::canonicalize` would need the file to exist, -/// which is the very thing being tested. -pub(crate) fn normalize(path: &Path) -> PathBuf { - let mut out = PathBuf::new(); - for part in path.components() { - match part { - std::path::Component::ParentDir => { - // Popping unconditionally let `../..` cancel itself, so a link - // with too many `..` climbed above the root and then walked back - // down to a real file. - if out.components().next_back() == Some(std::path::Component::ParentDir) || !out.pop() { - out.push(".."); - } - } - std::path::Component::CurDir => {} - other => out.push(other.as_os_str()), - } - } - out -} - -fn links(found: &mut Findings, root: &Path, known: &BTreeSet<&Path>, doc: &Doc) { - for link in &doc.links { - if link.target.contains("://") || link.target.starts_with("mailto:") { - continue; - } - let target = without_fragment(&link.target); - if target.is_empty() { - continue; - } - - // A normalized path that still opens with `..` points above the - // repository root. Joining it to `root` and testing existence would - // follow it into whatever sits beside the checkout, so the repo's own - // directory name (or a sibling worktree) could make a broken link pass. - let path = resolve(&doc.path, target); - if path.starts_with("..") || !root.join(&path).exists() { - found.at(&doc.path, link.line, format!("link does not resolve: {}", link.target)); - continue; - } - - // Quests and questlines reference each other with root-absolute links. - // A relative one still renders, so nothing else would notice - but it is - // invisible to the dependency graph below, which only speaks /quest/... - if known.contains(path.as_path()) && !link.target.starts_with('/') { - found.at( - &doc.path, - link.line, - format!( - "link to a quest must be root-absolute: {} (write /{})", - link.target, - path.display() - ), - ); - } - - // A `Required` bullet is either a dependency edge (the link opens it) or - // a plain-text external condition (no quest link at all). - // moq-dev/moq.pro#1170 shipped the third shape: a customer-gate sentence - // mentioning a questline mid-line, which reads as context but IS a - // blocker, and so silently required all of m2. - if link.section.as_deref() == Some("Required") - && known.contains(path.as_path()) - && link.position != Position::Entry - { - found.at( - &doc.path, - link.line, - format!( - "Required links {} mid-sentence; that reads as prose but IS a blocker - open the bullet with the link, or drop the link", - link.target - ), - ); - } - } -} - -/// Which questline lists each document. The index must be exactly the file -/// tree: every document is listed by the questline it sits under, and a -/// questline lists nothing but its own children - together these also give -/// "listed by exactly one questline". -fn index<'a>(found: &mut Findings, known: &BTreeSet<&Path>, docs: &'a [Doc]) -> BTreeMap { - let mut listed: BTreeMap = BTreeMap::new(); - let mut entries: BTreeMap<&Path, usize> = BTreeMap::new(); - - for doc in docs { - for link in &doc.links { - if link.section.as_deref() != Some("Quests") { - continue; - } - // The index is a list of entries, not prose that happens to link: - // `See [One](/quest/m0/one.md)` must not make One look indexed. - if link.position != Position::Entry { - found.at( - &doc.path, - link.line, - format!("a Quests entry must open its bullet: {}", link.target), - ); - continue; - } - let Some(child) = rooted(&link.target) else { - found.at( - &doc.path, - link.line, - format!( - "a Quests entry must be a root-absolute /quest/... link: {}", - link.target - ), - ); - continue; - }; - // Existence is not enough: the index points readers at work to pick - // up, and quest/AGENTS.md is a file under quest/ that is not a quest. - if !known.contains(child.as_path()) { - found.at( - &doc.path, - link.line, - format!("lists {}, which is not a quest document", link.target), - ); - continue; - } - if Doc::owner(&child) != doc.path.parent().unwrap_or(Path::new("")) { - found.at( - &doc.path, - link.line, - format!("lists {}, which does not sit under this questline", link.target), - ); - continue; - } - if listed.insert(child, doc.path.as_path()).is_some() { - found.at(&doc.path, link.line, format!("lists {} twice", link.target)); - } - *entries.entry(doc.path.as_path()).or_default() += 1; - } - } - - for doc in docs { - // A questline lists at least one quest. Completing its last one is - // supposed to delete the directory; a heading holding a bullet with no - // quest in it (`- TBD`) leaves the husk standing just as well as a bare - // one does. - if doc.is_questline() && doc.has("Quests") && entries.get(doc.path.as_path()).copied().unwrap_or(0) == 0 { - found.on( - &doc.path, - "'## Quests' lists no quest; a questline with none left should be deleted", - ); - } - - // The root questline is permanent and has nothing above it to list it. - if doc.path == Path::new(ROOT) || listed.contains_key(&doc.path) { - continue; - } - let owner = Doc::owner(&doc.path).join("README.md"); - found.on( - &doc.path, - format!( - "not listed in {}'s '## Quests'; an unlisted quest is unreachable", - owner.display() - ), - ); - } - - listed -} - -/// `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 -/// AGENTS.md asks of an author before adding a blocker. -fn cycles(found: &mut Findings, docs: &[Doc], listed: &BTreeMap) { - let mut blockers: BTreeMap<&Path, Vec> = BTreeMap::new(); - - for doc in docs { - let edges: Vec = doc - .links - .iter() - .filter(|l| l.section.as_deref() == Some("Required") && l.position == Position::Entry) - .filter_map(|l| rooted(&l.target)) - .collect(); - blockers.entry(doc.path.as_path()).or_default().extend(edges); - } - - // A quest may require a whole QUESTLINE, and a questline is complete only - // when all of its quests are, so a questline waits on its own children. - // Without these edges the walk stops at the README and misses the deadlock - // that spans it: a quest requiring the questline that holds the quest - // requiring it back. - for (child, questline) in listed { - blockers.entry(questline).or_default().push(child.clone()); - } - - #[derive(Clone, Copy, PartialEq)] - enum State { - Open, - Done, - } - - fn walk( - node: &Path, - blockers: &BTreeMap<&Path, Vec>, - state: &mut BTreeMap, - stack: &mut Vec, - found: &mut Findings, - ) { - match state.get(node) { - Some(State::Done) => return, - Some(State::Open) => { - let from = stack.iter().position(|p| p == node).unwrap_or(0); - let mut path: Vec = stack[from..].iter().map(|p| p.display().to_string()).collect(); - path.push(node.display().to_string()); - found.on(node, format!("Required cycle: {}", path.join(" -> "))); - return; - } - None => {} - } - state.insert(node.to_path_buf(), State::Open); - stack.push(node.to_path_buf()); - for next in blockers.get(node).map(Vec::as_slice).unwrap_or_default() { - walk(next, blockers, state, stack, found); - } - stack.pop(); - state.insert(node.to_path_buf(), State::Done); - } - - let mut state = BTreeMap::new(); - for doc in docs { - walk(&doc.path, &blockers, &mut state, &mut Vec::new(), found); - } -} diff --git a/rs/quest/tests/tree.rs b/rs/quest/tests/tree.rs deleted file mode 100644 index e5577755a30..00000000000 --- a/rs/quest/tests/tree.rs +++ /dev/null @@ -1,871 +0,0 @@ -//! Every rule, each proven to actually fail, and the readiness the same tree -//! answers. -//! -//! A validator that silently stopped enforcing a rule is indistinguishable from -//! a clean tree, so each case starts from the same valid fixture and breaks -//! exactly one thing. The cases that must still PASS matter just as much: the -//! shell version this replaced was rewritten precisely because it rejected -//! legitimate Markdown and accepted the shapes it was written to catch. - -use std::path::Path; - -use tempfile::TempDir; - -const ROOT_README: &str = "\ -# Quests - -## Goal - -The permanent root questline. - -## Quests - -- [m0](/quest/m0/README.md) -"; - -const M0_README: &str = "\ -# m0 - -## Goal - -A milestone. - -## Quests - -- [Line](/quest/m0/line/README.md) -"; - -const LINE_README: &str = "\ -# Line - -## Goal - -A questline. - -## Quests - -- [One](/quest/m0/line/one.md) -- [Two](/quest/m0/line/two.md) -"; - -const ONE: &str = "\ -# [S] One - -## Goal - -A quest. -"; - -const TWO: &str = "\ -# [S] Two - -## Goal - -Another quest. - -## Required - -- [One](/quest/m0/line/one.md) - must finish first -"; - -/// A minimal but complete tree: root questline -> milestone -> questline -> two -/// quests, one blocking the other. -struct Tree(TempDir); - -impl Tree { - fn new() -> Tree { - let tree = Tree(TempDir::new().expect("tempdir")); - tree.write("quest/README.md", ROOT_README); - tree.write("quest/m0/README.md", M0_README); - tree.write("quest/m0/line/README.md", LINE_README); - tree.write("quest/m0/line/one.md", ONE); - tree.write("quest/m0/line/two.md", TWO); - tree - } - - fn path(&self) -> &Path { - self.0.path() - } - - fn write(&self, rel: &str, body: &str) -> &Tree { - let path = self.path().join(rel); - std::fs::create_dir_all(path.parent().unwrap()).expect("mkdir"); - std::fs::write(path, body).expect("write"); - self - } - - fn append(&self, rel: &str, body: &str) -> &Tree { - let path = self.path().join(rel); - let existing = std::fs::read_to_string(&path).expect("read"); - std::fs::write(path, format!("{existing}{body}")).expect("write"); - self - } - - fn findings(&self) -> Vec { - quest::check(self.path()) - .expect("check") - .iter() - .map(ToString::to_string) - .collect() - } - - /// The rendered blocker chain: one line per blocker, nesting indented. - fn blockers(&self, path: &str) -> Vec { - quest::ready::blockers(self.path(), Path::new(path)) - .expect("blockers") - .iter() - .flat_map(|blocker| blocker.to_string().lines().map(str::to_owned).collect::>()) - .collect() - } - - fn ready(&self) -> Vec { - quest::ready::quests(self.path()) - .expect("ready") - .iter() - .map(|path| path.display().to_string()) - .collect() - } - - #[track_caller] - fn accepts(&self) { - let findings = self.findings(); - assert!(findings.is_empty(), "expected the tree to pass, got: {findings:#?}"); - } - - #[track_caller] - fn without(&self, unexpected: &str) { - let findings = self.findings(); - assert!( - !findings.iter().any(|f| f.contains(unexpected)), - "expected NO finding containing {unexpected:?}, got: {findings:#?}" - ); - } - - #[track_caller] - fn rejects(&self, expected: &str) { - let findings = self.findings(); - assert!( - findings.iter().any(|f| f.contains(expected)), - "expected a finding containing {expected:?}, got: {findings:#?}" - ); - } -} - -/// The fixture itself has to pass, or every case below proves nothing. -#[test] -fn baseline_is_valid() { - Tree::new().accepts(); -} - -#[test] -fn dangling_absolute_link() { - let tree = Tree::new(); - tree.append( - "quest/m0/line/one.md", - "\n## Related\n\n- [Gone](/quest/m0/line/gone.md) - completed and deleted\n", - ); - tree.rejects("link does not resolve: /quest/m0/line/gone.md"); -} - -/// Relative links escape the tree (AGENTS.md points at ../CONTRIBUTING.md), so -/// they resolve against the LINKING FILE's directory. The pair of cases pins the -/// direction: resolving against the wrong base would flip both verdicts. -#[test] -fn relative_link_resolves_against_the_linking_file() { - let tree = Tree::new(); - tree.write("AGENTS.md", "# Guide\n"); - tree.append( - "quest/m0/line/one.md", - "\n## Plan\n\nSee [the guide](../../../AGENTS.md).\n", - ); - tree.accepts(); -} - -#[test] -fn relative_link_above_the_repository_root() { - let tree = Tree::new(); - tree.write("AGENTS.md", "# Guide\n"); - // One `..` too many, which is exactly what a file flattened up a level - // keeps: it still renders, and points at nothing. - tree.append( - "quest/m0/line/one.md", - "\n## Plan\n\nSee [the guide](../../../../AGENTS.md).\n", - ); - tree.rejects("link does not resolve: ../../../../AGENTS.md"); -} - -/// Quests reference each other root-absolutely. A relative one renders fine, so -/// nothing else would notice - but it is invisible to the dependency graph. -#[test] -fn relative_link_to_a_quest() { - let tree = Tree::new(); - tree.append("quest/m0/line/one.md", "\n## Related\n\n- [Two](two.md) - a sibling\n"); - tree.rejects("link to a quest must be root-absolute: two.md (write /quest/m0/line/two.md)"); -} - -/// Templates inside fenced blocks are illustrations. Flagging AGENTS.md's own -/// example would make this a check everyone learns to skip. -#[test] -fn fenced_templates_are_not_links() { - let tree = Tree::new(); - tree.append( - "quest/m0/line/one.md", - "\n## Plan\n\n```markdown\n## Required\n\n- [Blocker](/quest/foo/bar.md) - must finish first\n```\n", - ); - tree.accepts(); -} - -/// A fence longer than three backticks may contain shorter ones, and `~~~` is a -/// fence too. Miscounting either inverts the fence state and silently skips the -/// REST OF THE FILE - the worst failure this tool has, because it looks clean. -#[test] -fn nested_and_tilde_fences_do_not_leak() { - let tree = Tree::new(); - tree.append( - "quest/m0/line/one.md", - "\n## Plan\n\n````markdown\n```bash\njust check\n```\n````\n\n~~~text\n```\n~~~\n\n## Requires\n\n- [Gone](/quest/m0/line/gone.md) - typo'd heading and a dangling link\n", - ); - tree.rejects("unknown '## Requires'"); - tree.rejects("link does not resolve: /quest/m0/line/gone.md"); -} - -#[test] -fn missing_goal() { - let tree = Tree::new(); - tree.write( - "quest/m0/line/one.md", - "# [S] One\n\n## Plan\n\nA quest with no stated outcome.\n", - ); - tree.rejects("missing '## Goal'"); -} - -#[test] -fn quest_title_needs_a_size() { - let tree = Tree::new(); - tree.write("quest/m0/line/one.md", &ONE.replace("# [S] One", "# One")); - tree.rejects("quest title must be '# [XS|S|M|L|XL] Title'"); -} - -#[test] -fn quest_title_accepts_xl() { - let tree = Tree::new(); - tree.write("quest/m0/line/one.md", &ONE.replace("# [S] One", "# [XL] One")); - tree.accepts(); -} - -#[test] -fn quest_title_rejects_xxl() { - let tree = Tree::new(); - tree.write("quest/m0/line/one.md", &ONE.replace("# [S] One", "# [XXL] One")); - tree.rejects("quest title must be '# [XS|S|M|L|XL] Title'"); -} - -/// The closed vocabulary exists for this: readiness greps `## Required` -/// literally, so a typo makes a blocked quest read as ready and fails nowhere. -#[test] -fn typo_in_a_heading() { - let tree = Tree::new(); - tree.write("quest/m0/line/two.md", &TWO.replace("## Required", "## Requires")); - tree.rejects("unknown '## Requires'"); -} - -#[test] -fn quest_with_a_questline_index() { - let tree = Tree::new(); - tree.append( - "quest/m0/line/one.md", - "\n## Quests\n\n- [Two](/quest/m0/line/two.md)\n", - ); - tree.rejects("only a README may have '## Quests'"); -} - -/// A README whose last child merged is the line's own remaining work: a leaf -/// quest, sized and listed as ready like any other. -#[test] -fn readme_without_an_index_is_a_quest() { - let tree = Tree::new(); - tree.write( - "quest/m0/line/sub/README.md", - "# Sub\n\n## Goal\n\nThe end-to-end test once every child has merged.\n", - ); - tree.append("quest/m0/line/README.md", "- [Sub](/quest/m0/line/sub/README.md)\n"); - tree.rejects("quest title must be"); - tree.write( - "quest/m0/line/sub/README.md", - "# [S] Sub\n\n## Goal\n\nThe end-to-end test once every child has merged.\n", - ); - tree.accepts(); - assert!(tree.ready().contains(&"quest/m0/line/sub/README.md".to_string())); -} - -/// Completing a questline's last quest deletes the directory. A bare `## Quests` -/// heading otherwise satisfies the questline rule and leaves the husk standing. -/// (The other direction - a heading holding a non-quest bullet - is -/// `questline_listing_no_quest`; one rule, both shapes.) -#[test] -fn empty_questline_index() { - let tree = Tree::new(); - tree.write( - "quest/m0/husk/README.md", - "# Husk\n\n## Goal\n\nIts last quest was completed.\n\n## Quests\n", - ); - tree.append("quest/m0/README.md", "- [Husk](/quest/m0/husk/README.md)\n"); - tree.rejects("lists no quest"); -} - -/// The absence of `## Required` means ready. A heading left behind by its last -/// blocker reads as blocked to every readiness check, forever. -#[test] -fn empty_required_section() { - let tree = Tree::new(); - tree.append("quest/m0/line/one.md", "\n## Required\n"); - tree.rejects("'## Required' is empty"); -} - -#[test] -fn unlisted_quest() { - let tree = Tree::new(); - tree.write( - "quest/m0/line/three.md", - "# [S] Three\n\n## Goal\n\nA quest nobody indexed.\n", - ); - tree.rejects("not listed in quest/m0/line/README.md's '## Quests'"); -} - -/// Quests are indexed where they sit, so a milestone cannot reach past its own -/// questlines to list a grandchild. -#[test] -fn questline_listing_a_grandchild() { - let tree = Tree::new(); - tree.append("quest/m0/README.md", "- [One](/quest/m0/line/one.md)\n"); - tree.rejects("does not sit under this questline"); -} - -#[test] -fn quest_listed_twice() { - let tree = Tree::new(); - tree.append("quest/m0/line/README.md", "- [One again](/quest/m0/line/one.md)\n"); - tree.rejects("lists /quest/m0/line/one.md twice"); -} - -#[test] -fn relative_index_entry() { - let tree = Tree::new(); - tree.write( - "quest/m0/line/README.md", - &LINE_README.replace("(/quest/m0/line/one.md)", "(one.md)"), - ); - tree.rejects("must be a root-absolute /quest/... link: one.md"); -} - -/// The index points readers at work to pick up, so a target that merely exists -/// is not enough: quest/AGENTS.md is a file under quest/ that is not a quest. -#[test] -fn index_entry_that_is_not_a_quest() { - let tree = Tree::new(); - tree.write("quest/AGENTS.md", "# Contract\n"); - tree.append("quest/README.md", "- [Contract](/quest/AGENTS.md)\n"); - tree.rejects("lists /quest/AGENTS.md, which is not a quest document"); -} - -/// The index is a list of entries, not prose that happens to link. -#[test] -fn prose_under_the_index() { - let tree = Tree::new(); - tree.append("quest/m0/line/README.md", "\nSee also [One](/quest/m0/line/one.md).\n"); - tree.rejects("a Quests entry must open its bullet"); -} - -#[test] -fn direct_required_cycle() { - let tree = Tree::new(); - tree.append( - "quest/m0/line/one.md", - "\n## Required\n\n- [Two](/quest/m0/line/two.md) - must finish first\n", - ); - tree.rejects("Required cycle:"); -} - -/// A quest may require a whole questline, so the deadlock can span the README. -/// The cycle here runs strictly OUTSIDE-IN: `outer` (in m0) requires the line -/// questline, and `three` inside that questline requires `outer` back. No quest -/// requires its own questline, so containment edges are the only thing that can -/// close it. -#[test] -fn cycle_through_a_questline() { - let tree = Tree::new(); - tree.append("quest/m0/README.md", "- [Outer](/quest/m0/outer.md)\n"); - tree.write( - "quest/m0/outer.md", - "# [S] Outer\n\n## Goal\n\nBlocked on a whole questline.\n\n## Required\n\n- [Line](/quest/m0/line/README.md) - the whole questline must finish\n", - ); - tree.append("quest/m0/line/README.md", "- [Three](/quest/m0/line/three.md)\n"); - tree.write( - "quest/m0/line/three.md", - "# [S] Three\n\n## Goal\n\nInside the questline that blocks it.\n\n## Required\n\n- [Outer](/quest/m0/outer.md) - must finish first\n", - ); - tree.rejects( - "Required cycle: quest/m0/line/README.md -> quest/m0/line/three.md -> quest/m0/outer.md -> quest/m0/line/README.md", - ); -} - -/// A `#fragment` addresses a place inside a file, not a different file. Keeping -/// it on made a phantom graph node that no quest could match, so a cycle through -/// an anchored link went unreported. -#[test] -fn cycle_through_an_anchored_link() { - let tree = Tree::new(); - tree.append( - "quest/m0/line/one.md", - "\n## Required\n\n- [Two](/quest/m0/line/two.md#plan) - must finish first\n", - ); - tree.rejects("Required cycle:"); -} - -/// Reference-style links render as real dependencies, so they must carry real -/// edges. A line-oriented parser saw no `](` here and produced none. -#[test] -fn cycle_through_a_reference_style_link() { - let tree = Tree::new(); - tree.append( - "quest/m0/line/one.md", - "\n## Required\n\n- [Two][two] - must finish first\n\n[two]: /quest/m0/line/two.md\n", - ); - tree.rejects("Required cycle:"); -} - -/// moq-dev/moq.pro#1170: a plain-text external condition that happens to link a -/// questline mid-sentence reads as context but IS a dependency edge. -#[test] -fn required_link_mid_sentence() { - let tree = Tree::new(); - tree.append( - "quest/m0/line/one.md", - "\n## Required\n\n- A customer who also justifies [the line](/quest/m0/line/README.md).\n", - ); - tree.rejects("mid-sentence"); -} - -/// The same failure, reflowed onto a second line. The link is no longer on the -/// bullet's first line, which is all it took to slip past the shell version. -#[test] -fn required_link_on_a_wrapped_bullet() { - let tree = Tree::new(); - tree.append( - "quest/m0/line/one.md", - "\n## Required\n\n- A customer who also justifies\n [the line](/quest/m0/line/README.md).\n", - ); - tree.rejects("mid-sentence"); -} - -/// The other half of that rule: an external condition with no link at all is the -/// shape AGENTS.md prescribes, and must stay legal. -#[test] -fn required_external_condition() { - let tree = Tree::new(); - tree.append( - "quest/m0/line/one.md", - "\n## Required\n\n- A customer who justifies the work.\n", - ); - tree.accepts(); -} - -/// 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] -fn loose_index_list() { - let tree = Tree::new(); - tree.write( - "quest/m0/line/README.md", - "# Line\n\n## Goal\n\nA questline.\n\n## Quests\n\n- [One](/quest/m0/line/one.md)\n\n- [Two](/quest/m0/line/two.md)\n", - ); - tree.accepts(); -} - -#[test] -fn loose_required_list() { - let tree = Tree::new(); - tree.append( - "quest/m0/line/one.md", - "\n## Required\n\n- [Two](/quest/m0/line/two.md) - must finish first\n\n- A customer who justifies the work.\n", - ); - // The edge registered (hence the cycle) without reading as prose. - tree.rejects("Required cycle:"); - tree.without("mid-sentence"); -} - -/// The other side of the same seam: a link opening a SECOND paragraph is inside -/// the item, not opening it. -#[test] -fn required_link_in_a_later_paragraph() { - let tree = Tree::new(); - tree.append( - "quest/m0/line/one.md", - "\n## Required\n\n- A customer who justifies the work.\n\n [The line](/quest/m0/line/README.md) would follow.\n", - ); - tree.rejects("mid-sentence"); -} - -/// A blocker written with emphasis still opens its bullet. Rejecting it would -/// be a false positive on legitimate Markdown. -#[test] -fn required_link_with_emphasis() { - let tree = Tree::new(); - tree.append( - "quest/m0/line/one.md", - "\n## Required\n\n- **[Two](/quest/m0/line/two.md)** - must finish first\n", - ); - tree.rejects("Required cycle:"); -} - -/// A setext underline renders as an H2 and this validator would read the quest -/// as blocked - but readiness greps `^## Required$` and would call it READY. -/// Two tools disagreeing about the same file is the whole failure. -#[test] -fn setext_heading() { - let tree = Tree::new(); - tree.append( - "quest/m0/line/one.md", - "\nRequired\n--------\n\n- [Two](/quest/m0/line/two.md) - must finish first\n", - ); - tree.rejects("must be written literally as '## Required'"); -} - -#[test] -fn decorated_heading() { - let tree = Tree::new(); - tree.append( - "quest/m0/line/one.md", - "\n## `Required`\n\n- [Two](/quest/m0/line/two.md) - must finish first\n", - ); - tree.rejects("must be written literally as '## Required'"); -} - -/// A bullet nested under a prose lead-in is illustration, not a blocker. Reading -/// it as one is #1170 again, wearing an indent. -#[test] -fn nested_required_entry() { - let tree = Tree::new(); - tree.append( - "quest/m0/line/one.md", - "\n## Required\n\n- Customer evidence:\n - [The line](/quest/m0/line/README.md)\n", - ); - tree.rejects("mid-sentence"); -} - -#[test] -fn blockquoted_required_entry() { - let tree = Tree::new(); - tree.append( - "quest/m0/line/one.md", - "\n## Required\n\n- Quoting the old plan:\n\n > - [The line](/quest/m0/line/README.md)\n", - ); - tree.rejects("mid-sentence"); -} - -/// Repeated `..` must not cancel each other on the way up. Popping -/// unconditionally let a link climb above the root and walk back down to a real -/// file, so a badly flattened path resolved and reported nothing. -#[test] -fn repeated_parent_components() { - let tree = Tree::new(); - tree.write("AGENTS.md", "# Guide\n"); - tree.append( - "quest/m0/line/one.md", - "\n## Plan\n\nSee [the guide](../../../../../AGENTS.md).\n", - ); - tree.rejects("link does not resolve: ../../../../../AGENTS.md"); -} - -/// Escaping the root must fail even when the joined path happens to exist: -/// the repository's own directory name (or a sibling worktree) sits beside the -/// root, so `/..//AGENTS.md` is a real file that readers of the -/// repository-relative link can never reach. -#[test] -fn escaped_link_resolving_beside_the_root() { - let tree = Tree::new(); - tree.write("AGENTS.md", "# Guide\n"); - let name = tree.path().file_name().unwrap().to_str().unwrap(); - tree.append( - "quest/m0/line/one.md", - &format!("\n## Plan\n\nSee [the guide](../../../../{name}/AGENTS.md).\n"), - ); - tree.rejects(&format!("link does not resolve: ../../../../{name}/AGENTS.md")); -} - -/// A bullet is not an entry. `- TBD` satisfies "the heading has a list" while -/// leaving a questline that should have been deleted with its last quest. -#[test] -fn questline_listing_no_quest() { - let tree = Tree::new(); - tree.write( - "quest/m0/husk/README.md", - "# Husk\n\n## Goal\n\nIts last quest was completed.\n\n## Quests\n\n- TBD\n", - ); - tree.append("quest/m0/README.md", "- [Husk](/quest/m0/husk/README.md)\n"); - tree.rejects("lists no quest"); -} - -#[test] -fn empty_related_section() { - let tree = Tree::new(); - tree.append("quest/m0/line/one.md", "\n## Related\n"); - tree.rejects("'## Related' is empty"); -} - -#[test] -fn empty_closes_section() { - let tree = Tree::new(); - tree.append("quest/m0/line/one.md", "\n## Closes\n"); - tree.rejects("'## Closes' is empty"); -} - -/// Trailing whitespace is invisible in a diff and `rg '^## Required$'` does not -/// match it either, so accepting it recreates the same disagreement a setext -/// heading does. -#[test] -fn heading_with_trailing_space() { - let tree = Tree::new(); - tree.append( - "quest/m0/line/one.md", - "\n## Required \n\n- [Two](/quest/m0/line/two.md) - must finish first\n", - ); - tree.rejects("must be written literally as '## Required'"); -} - -/// The index and the cycle walk key on the same normalized path. A `..` left in -/// either makes a node nothing can match, so the cycle through it disappears. -#[test] -fn cycle_through_an_unnormalized_link() { - let tree = Tree::new(); - tree.append( - "quest/m0/line/one.md", - "\n## Required\n\n- [Two](/quest/m0/line/../line/two.md) - must finish first\n", - ); - tree.rejects("Required cycle:"); -} - -// Readiness: what `quest ready` reports about the same fixture. A blocker list -// is the machine-readable result, so the cases that must come back EMPTY carry -// as much weight as the ones that must not. - -/// The absence of `## Required` is the whole definition of ready. -#[test] -fn ready_quest_has_no_blockers() { - let tree = Tree::new(); - assert!(tree.blockers("quest/m0/line/one.md").is_empty()); -} - -#[test] -fn blocked_by_a_quest() { - let tree = Tree::new(); - assert_eq!(tree.blockers("quest/m0/line/two.md"), ["quest/m0/line/one.md"]); -} - -/// A plain-text bullet names a condition outside the repository, so nothing in -/// the tree can ever clear it: it is a blocker, printed as written. Wrapped -/// here because that is what the bullets in the tree actually look like. -#[test] -fn blocked_by_plain_text() { - let tree = Tree::new(); - tree.append( - "quest/m0/line/one.md", - "\n## Required\n\n- A `moq-video` release that carries\n the encoder\n", - ); - assert_eq!( - tree.blockers("quest/m0/line/one.md"), - ["A moq-video release that carries the encoder"] - ); -} - -/// A questline blocker clears only when the whole line is complete, so the -/// useful answer is which of its quests are still open - all of them, since a -/// completed quest is deleted. -#[test] -fn blocked_by_a_questline() { - let tree = Tree::new(); - tree.append("quest/m0/README.md", "- [Outer](/quest/m0/outer.md)\n"); - tree.write( - "quest/m0/outer.md", - "# [S] Outer\n\n## Goal\n\nBlocked on a whole questline.\n\n## Required\n\n- [Line](/quest/m0/line/README.md) - the whole questline must finish\n", - ); - assert_eq!( - tree.blockers("quest/m0/outer.md"), - [ - "quest/m0/line/README.md", - " quest/m0/line/one.md", - " quest/m0/line/two.md", - ] - ); -} - -/// A required QUEST does not expand: its own blockers are its readiness, and -/// 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] -fn a_required_quest_is_not_expanded() { - let tree = Tree::new(); - tree.append("quest/m0/line/README.md", "- [Three](/quest/m0/line/three.md)\n"); - tree.write( - "quest/m0/line/three.md", - "# [S] Three\n\n## Goal\n\nLast in the chain.\n\n## Required\n\n- [Two](/quest/m0/line/two.md) - must finish first\n", - ); - assert_eq!(tree.blockers("quest/m0/line/three.md"), ["quest/m0/line/two.md"]); -} - -/// `quest check` reports an empty `## Required` as a defect, and every reader -/// that greps for the heading calls the quest blocked. Reading it as ready here -/// would make this the one tool that disagrees. -#[test] -fn empty_required_section_still_blocks() { - let tree = Tree::new(); - tree.append("quest/m0/line/one.md", "\n## Required\n"); - assert_eq!( - tree.blockers("quest/m0/line/one.md"), - ["an empty '## Required' section, which blocks the quest until the heading is removed"] - ); -} - -/// The listing is the query the start flow reproduces by grepping. Questlines -/// are never executed, so they are not in it, and `two.md` is blocked. -#[test] -fn ready_listing() { - let tree = Tree::new(); - assert_eq!(tree.ready(), ["quest/m0/line/one.md"]); - - tree.append("quest/m0/README.md", "- [Outer](/quest/m0/outer.md)\n"); - tree.write("quest/m0/outer.md", "# [S] Outer\n\n## Goal\n\nReady too.\n"); - assert_eq!(tree.ready(), ["quest/m0/line/one.md", "quest/m0/outer.md"]); -} - -/// `quest check` proves the graph acyclic, but readiness also runs on trees -/// nobody has checked yet - the branch that just introduced the cycle - and a -/// cycle there has to print rather than recurse forever. -#[test] -fn cycle_terminates() { - let tree = Tree::new(); - tree.append("quest/m0/line/README.md", "- [Itself](/quest/m0/line/README.md)\n"); - tree.append("quest/m0/README.md", "- [Outer](/quest/m0/outer.md)\n"); - tree.write( - "quest/m0/outer.md", - "# [S] Outer\n\n## Goal\n\nBlocked on a questline that lists itself.\n\n## Required\n\n- [Line](/quest/m0/line/README.md) - the whole questline must finish\n", - ); - assert_eq!( - tree.blockers("quest/m0/outer.md"), - [ - "quest/m0/line/README.md", - " quest/m0/line/one.md", - " quest/m0/line/two.md", - " quest/m0/line/README.md", - ] - ); -} - -#[test] -fn ready_listing_follows_nested_priority_and_terminates_cycles() { - let tree = Tree::new(); - tree.write("quest/m0/line/two.md", "# [S] Two\n\n## Goal\n\nReady.\n"); - tree.write("quest/m0/line/README.md", "# Line\n\n## Quests\n\n- [Two](/quest/m0/line/two.md)\n- [Self](/quest/m0/line/README.md)\n- [One](/quest/m0/line/one.md)\n"); - assert_eq!(tree.ready(), ["quest/m0/line/two.md", "quest/m0/line/one.md"]); -} - -#[test] -fn ready_listing_appends_unindexed_quests() { - let tree = Tree::new(); - tree.write("quest/m0/aaa.md", "# [S] Unindexed\n\n## Goal\n\nDiscover me.\n"); - tree.write( - "quest/m0/blocked.md", - "# [S] Blocked\n\n## Goal\n\nWait.\n\n## Required\n\n- External condition\n", - ); - assert_eq!(tree.ready(), ["quest/m0/line/one.md", "quest/m0/aaa.md"]); -} - -impl Tree { - fn branch(&self, path: &str) -> Vec { - quest::branch::chain(self.path(), Path::new(path)).expect("branch") - } - - fn branch_err(&self, path: &str) -> String { - quest::branch::chain(self.path(), Path::new(path)) - .expect_err("expected no branch") - .to_string() - } -} - -/// The chain is the path: the leaf, its line's README, then `main`. Nothing -/// consults git. -#[test] -fn branch_chain_of_a_quest() { - let tree = Tree::new(); - assert_eq!( - tree.branch("quest/m0/line/one.md"), - ["quest/m0/line/one", "quest/m0/line/README", "main"] - ); - assert_eq!( - tree.branch("/quest/m0/line/README.md"), - ["quest/m0/line/README", "main"] - ); -} - -/// Neither the root nor a milestone has a branch; their children merge into `main`. -#[test] -fn root_and_milestone_have_no_branch() { - let tree = Tree::new(); - assert!(tree.branch_err("quest/README.md").contains("no branch")); - assert!(tree.branch_err("quest/m0/README.md").contains("no branch")); -} - -/// Every milestone's work branches from `main`, whatever its priority: starting a -/// quest never moves it. -#[test] -fn later_milestone_branches_from_main() { - let tree = Tree::new(); - tree.write( - "quest/m2/README.md", - "# m2\n\n## Goal\n\nLater work.\n\n## Quests\n\n- [Later](/quest/m2/later.md)\n", - ); - tree.write("quest/m2/later.md", "# [S] Later\n\n## Goal\n\nNot started.\n"); - tree.append("quest/README.md", "- [m2](/quest/m2/README.md)\n"); - tree.accepts(); - assert_eq!(tree.branch("quest/m2/later.md"), ["quest/m2/later", "main"]); -} - -/// A milestone with nothing left is not its own work, so it needs no size and -/// never lists as ready. -#[test] -fn milestone_may_be_empty() { - let tree = Tree::new(); - tree.write("quest/m0/README.md", "# m0\n\n## Goal\n\nEmpty for now.\n"); - std::fs::remove_dir_all(tree.path().join("quest/m0/line")).expect("rm"); - tree.accepts(); - assert!(tree.ready().is_empty(), "{:?}", tree.ready()); -} - -/// Lines nest to any depth: every branch ends in a leaf component (the quest -/// or `README`), so no line's branch is a path prefix of its children's, which -/// is the one shape git refuses. -#[test] -fn branch_chain_of_a_nested_line() { - 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", - ); - tree.write( - "quest/m0/line/sub/three.md", - "# [S] Three\n\n## Goal\n\nA nested quest.\n", - ); - tree.append("quest/m0/line/README.md", "- [Sub](/quest/m0/line/sub/README.md)\n"); - tree.accepts(); - assert_eq!( - tree.branch("quest/m0/line/sub/three.md"), - [ - "quest/m0/line/sub/three", - "quest/m0/line/sub/README", - "quest/m0/line/README", - "main" - ] - ); -} From d67cdc60b8c8301e7eff51b150944d27df32e9da Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 26 Sep 2026 10:44:21 -0700 Subject: [PATCH 2/4] chore(quest): vendor at .quest and pin quest main Co-Authored-By: Claude Opus 5.5 --- .claude/hooks/submodule.sh | 4 ++-- .claude/quest | 1 - .claude/skills/plan-issues | 2 +- .claude/skills/plan-quests | 2 +- .claude/skills/spawn-quests | 2 +- .claude/skills/start-quest | 2 +- .gitmodules | 4 ++-- .quest | 1 + .remarkignore | 2 +- AGENTS.md | 2 +- biome.jsonc | 9 ++++++++- justfile | 10 +++++----- quest/AGENTS.md | 2 +- 13 files changed, 25 insertions(+), 18 deletions(-) delete mode 160000 .claude/quest create mode 160000 .quest diff --git a/.claude/hooks/submodule.sh b/.claude/hooks/submodule.sh index b4dc6630937..789ddbc442b 100755 --- a/.claude/hooks/submodule.sh +++ b/.claude/hooks/submodule.sh @@ -1,6 +1,6 @@ #!/usr/bin/env bash # The shared and quest skills in .claude/skills are symlinks into the -# .claude/shared and .claude/quest submodules. git leaves those unpopulated in a +# .claude/shared and .quest submodules. git leaves those unpopulated in a # new worktree, and a dangling symlink is silently skipped. A checkout on the # wrong commit stays stale too. @@ -10,7 +10,7 @@ set -eu [ -n "${CLAUDE_PROJECT_DIR:-}" ] || exit 0 cd "$CLAUDE_PROJECT_DIR" || exit 0 -for path in .claude/shared .claude/quest; do +for path in .claude/shared .quest; do # '-' is uninitialized. '+' is populated at a commit other than the gitlink. # A matching checkout has no prefix. case "$(git submodule status "$path" 2>/dev/null)" in diff --git a/.claude/quest b/.claude/quest deleted file mode 160000 index 53dc538b214..00000000000 --- a/.claude/quest +++ /dev/null @@ -1 +0,0 @@ -Subproject commit 53dc538b214f6507545d30036e7a8af3a8519b7e diff --git a/.claude/skills/plan-issues b/.claude/skills/plan-issues index b80a201bcd9..004081c195d 120000 --- a/.claude/skills/plan-issues +++ b/.claude/skills/plan-issues @@ -1 +1 @@ -../quest/.claude/skills/plan-issues \ No newline at end of file +../../.quest/.claude/skills/plan-issues \ No newline at end of file diff --git a/.claude/skills/plan-quests b/.claude/skills/plan-quests index 4a90495210d..b932deda862 120000 --- a/.claude/skills/plan-quests +++ b/.claude/skills/plan-quests @@ -1 +1 @@ -../quest/.claude/skills/plan-quests \ No newline at end of file +../../.quest/.claude/skills/plan-quests \ No newline at end of file diff --git a/.claude/skills/spawn-quests b/.claude/skills/spawn-quests index 4a6d46d65ee..69f8c805967 120000 --- a/.claude/skills/spawn-quests +++ b/.claude/skills/spawn-quests @@ -1 +1 @@ -../quest/.claude/skills/spawn-quests \ No newline at end of file +../../.quest/.claude/skills/spawn-quests \ No newline at end of file diff --git a/.claude/skills/start-quest b/.claude/skills/start-quest index 37bf131f64a..c5fccd4a969 120000 --- a/.claude/skills/start-quest +++ b/.claude/skills/start-quest @@ -1 +1 @@ -../quest/.claude/skills/start-quest \ No newline at end of file +../../.quest/.claude/skills/start-quest \ No newline at end of file diff --git a/.gitmodules b/.gitmodules index 30329e64ba8..eb7bc693fb9 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,6 +1,6 @@ [submodule ".claude/shared"] path = .claude/shared url = https://github.com/kixelated/skills -[submodule ".claude/quest"] - path = .claude/quest +[submodule ".quest"] + path = .quest url = https://github.com/kixelated/quest diff --git a/.quest b/.quest new file mode 160000 index 00000000000..d23e9880e71 --- /dev/null +++ b/.quest @@ -0,0 +1 @@ +Subproject commit d23e9880e7193d31247445a1c5de0c516bbc6915 diff --git a/.remarkignore b/.remarkignore index 1a863f0443c..f66f6687e71 100644 --- a/.remarkignore +++ b/.remarkignore @@ -20,6 +20,6 @@ quest/ # which format their own files; remark would follow them (and .agents, Codex's # link to the same directory) and rewrite the pinned checkouts. .claude/shared/ -.claude/quest/ +.quest/ .claude/skills/ .agents/ diff --git a/AGENTS.md b/AGENTS.md index ede129d13c4..1740f36347f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -89,7 +89,7 @@ just fix # Auto-fix lint/formatting, same scope These diff the branch against its base and only run the affected packages. -Quests are vendored from kixelated/quest in the `.claude/quest` submodule, including `quest/AGENTS.md` and the quest skills; change them upstream. +Quests are vendored from kixelated/quest in the `.quest` submodule, including `quest/AGENTS.md` and the quest skills; change them upstream. Run the CLI as `just quest ...`. A quest deleted on `dev` is done, even while `main` still lists it. diff --git a/biome.jsonc b/biome.jsonc index 309ddb470f4..0f28664e879 100644 --- a/biome.jsonc +++ b/biome.jsonc @@ -21,7 +21,14 @@ // - SVG assets, which Biome routes to its HTML parser and rejects. // - The audio jitter corpus, which is generated and byte-compared by its own test, // so a formatter rewriting it would fight the generator on every `just fix`. - "includes": ["**", "!rs/moq-mux/src/container/ts/test_data", "!**/*.svg", "!doc/concept/audio-jitter/*.json"] + // And the vendored kixelated/quest submodule, which formats its own files. + "includes": [ + "**", + "!.quest", + "!rs/moq-mux/src/container/ts/test_data", + "!**/*.svg", + "!doc/concept/audio-jitter/*.json" + ] }, "linter": { "rules": { diff --git a/justfile b/justfile index a29dddeee5f..25ec30d6553 100644 --- a/justfile +++ b/justfile @@ -240,15 +240,15 @@ worktree ACTION="check" $BASE="": echo "recorded: $(git rev-parse --short "$recorded") (STALE; $base has moved since setup)" fi -# Run the quest CLI pinned by the .claude/quest submodule: `just quest ready`. +# Run the quest CLI pinned by the .quest submodule: `just quest ready`. [positional-arguments] quest *args: #!/usr/bin/env bash set -euo pipefail # A fresh worktree or CI checkout leaves the submodule empty. Only an empty # one is initialized, so an unstaged bump under test is left alone. - [[ -e .claude/quest/Cargo.toml ]] || git submodule update --init .claude/quest - cargo run --quiet --locked --manifest-path .claude/quest/Cargo.toml -- "$@" + [[ -e .quest/Cargo.toml ]] || git submodule update --init .quest + cargo run --quiet --locked --manifest-path .quest/Cargo.toml -- "$@" # Install repo-wide tooling. Per-language deps install on first check. install: @@ -451,7 +451,7 @@ _tools $FILES="": # `_check-common` runs on every invocation, so its tools are unconditional. tools=(actionlint bun jq nix nixfmt shellcheck shfmt taplo python3 nfpm dpkg-deb envsubst rpm) scoped '^(drafts/|doc/\.vitepress/drafts\.ts$)' && tools+=(kramdown-rfc xml2rfc) - scoped '^(bench/|quest/|\.claude/quest$|rs/|Cargo\.(toml|lock)$|rust-toolchain\.toml$)' && tools+=(cargo envsubst) + scoped '^(bench/|quest/|\.quest$|rs/|Cargo\.(toml|lock)$|rust-toolchain\.toml$)' && tools+=(cargo envsubst) scoped '^(py/|pyproject\.toml$|uv\.lock$|rs/moq-ffi/|doc/lib/py/|doc/lib/samples\.sh$)' && tools+=(uv) scoped '^(kt/|rs/moq-ffi/|doc/lib/kt/|doc/lib/samples\.sh$)' && tools+=(gradle java) # cargo because `go check` builds moq-ffi for the host, and skips on a @@ -576,7 +576,7 @@ _check $BASE $TEST: fi # Quest documents form one graph, so validate the whole living tree when # either a quest or the pinned validator changes. - if echo "$files" | grep -qE '^(quest/|\.claude/quest$)'; then + if echo "$files" | grep -qE '^(quest/|\.quest$)'; then just quest check fi just py check "$files" diff --git a/quest/AGENTS.md b/quest/AGENTS.md index 0ab54696207..5216dd64086 120000 --- a/quest/AGENTS.md +++ b/quest/AGENTS.md @@ -1 +1 @@ -../.claude/quest/quest/AGENTS.md \ No newline at end of file +../.quest/quest/AGENTS.md \ No newline at end of file From 061a74a7879ea257919a056fc5a7b68a9dadf523 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 27 Sep 2026 11:31:46 -0700 Subject: [PATCH 3/4] chore(quest): pin the quest binary through the flake, drop the submodule kixelated/quest now serves its guide and skills from the binary, so moq installs static `quest-*` stubs in .claude/skills and pins the version with a flake input. The .quest submodule, `just quest`, and quest/AGENTS.md go away; `quest check` runs straight from the dev shell. The merge, close, spawn-merge, and takeover skills now come from quest as quest-*. Co-Authored-By: Claude Opus 5.5 --- .claude/hooks/submodule.sh | 25 ++++++++---------- .claude/skills/close | 1 - .claude/skills/merge | 1 - .claude/skills/plan-issues | 1 - .claude/skills/plan-quests | 1 - .claude/skills/quest-close/SKILL.md | 7 +++++ .claude/skills/quest-issues/SKILL.md | 7 +++++ .claude/skills/quest-merge/SKILL.md | 7 +++++ .claude/skills/quest-plan/SKILL.md | 7 +++++ .claude/skills/quest-spawn-merge/SKILL.md | 7 +++++ .claude/skills/quest-spawn/SKILL.md | 7 +++++ .claude/skills/quest-start/SKILL.md | 7 +++++ .claude/skills/quest-takeover/SKILL.md | 7 +++++ .claude/skills/spawn-merge | 1 - .claude/skills/spawn-quests | 1 - .claude/skills/start-quest | 1 - .claude/skills/takeover | 1 - .gitignore | 2 +- .gitmodules | 3 --- .quest | 1 - .remarkignore | 7 +++-- AGENTS.md | 4 +-- CONTRIBUTING.md | 2 +- biome.jsonc | 9 +------ flake.lock | 31 +++++++++++++++++++++++ flake.nix | 13 +++++++++- justfile | 21 +++++---------- quest/AGENTS.md | 1 - 28 files changed, 124 insertions(+), 59 deletions(-) delete mode 120000 .claude/skills/close delete mode 120000 .claude/skills/merge delete mode 120000 .claude/skills/plan-issues delete mode 120000 .claude/skills/plan-quests create mode 100644 .claude/skills/quest-close/SKILL.md create mode 100644 .claude/skills/quest-issues/SKILL.md create mode 100644 .claude/skills/quest-merge/SKILL.md create mode 100644 .claude/skills/quest-plan/SKILL.md create mode 100644 .claude/skills/quest-spawn-merge/SKILL.md create mode 100644 .claude/skills/quest-spawn/SKILL.md create mode 100644 .claude/skills/quest-start/SKILL.md create mode 100644 .claude/skills/quest-takeover/SKILL.md delete mode 120000 .claude/skills/spawn-merge delete mode 120000 .claude/skills/spawn-quests delete mode 120000 .claude/skills/start-quest delete mode 120000 .claude/skills/takeover delete mode 160000 .quest delete mode 120000 quest/AGENTS.md diff --git a/.claude/hooks/submodule.sh b/.claude/hooks/submodule.sh index 789ddbc442b..cda3fd4ace2 100755 --- a/.claude/hooks/submodule.sh +++ b/.claude/hooks/submodule.sh @@ -1,8 +1,7 @@ #!/usr/bin/env bash -# The shared and quest skills in .claude/skills are symlinks into the -# .claude/shared and .quest submodules. git leaves those unpopulated in a -# new worktree, and a dangling symlink is silently skipped. A checkout on the -# wrong commit stays stale too. +# The shared skills in .claude/skills are symlinks into the .claude/shared +# submodule. git leaves that unpopulated in a new worktree, and a dangling +# symlink is silently skipped. A checkout on the wrong commit stays stale too. set -eu @@ -10,14 +9,12 @@ set -eu [ -n "${CLAUDE_PROJECT_DIR:-}" ] || exit 0 cd "$CLAUDE_PROJECT_DIR" || exit 0 -for path in .claude/shared .quest; do - # '-' is uninitialized. '+' is populated at a commit other than the gitlink. - # A matching checkout has no prefix. - case "$(git submodule status "$path" 2>/dev/null)" in - -* | +*) ;; - *) continue ;; - esac +# '-' is uninitialized. '+' is populated at a commit other than the gitlink. +# A matching checkout has no prefix. +case "$(git submodule status .claude/shared 2>/dev/null)" in + -* | +*) ;; + *) exit 0 ;; +esac - echo "submodule hook: updating $path to the pinned commit." >&2 - git submodule update --init "$path" >&2 -done +echo "submodule hook: updating .claude/shared to the pinned skills." >&2 +git submodule update --init .claude/shared >&2 diff --git a/.claude/skills/close b/.claude/skills/close deleted file mode 120000 index 31284b75087..00000000000 --- a/.claude/skills/close +++ /dev/null @@ -1 +0,0 @@ -../shared/close \ No newline at end of file diff --git a/.claude/skills/merge b/.claude/skills/merge deleted file mode 120000 index 4735484baf5..00000000000 --- a/.claude/skills/merge +++ /dev/null @@ -1 +0,0 @@ -../shared/merge \ No newline at end of file diff --git a/.claude/skills/plan-issues b/.claude/skills/plan-issues deleted file mode 120000 index 004081c195d..00000000000 --- a/.claude/skills/plan-issues +++ /dev/null @@ -1 +0,0 @@ -../../.quest/.claude/skills/plan-issues \ No newline at end of file diff --git a/.claude/skills/plan-quests b/.claude/skills/plan-quests deleted file mode 120000 index b932deda862..00000000000 --- a/.claude/skills/plan-quests +++ /dev/null @@ -1 +0,0 @@ -../../.quest/.claude/skills/plan-quests \ No newline at end of file diff --git a/.claude/skills/quest-close/SKILL.md b/.claude/skills/quest-close/SKILL.md new file mode 100644 index 00000000000..db3d093ee48 --- /dev/null +++ b/.claude/skills/quest-close/SKILL.md @@ -0,0 +1,7 @@ +--- +name: quest-close +description: Close a GitHub PR. +--- + +Run `quest skill quest-close` and follow its output. +If `quest` is not installed, follow https://github.com/kixelated/quest/blob/main/SETUP.md first. diff --git a/.claude/skills/quest-issues/SKILL.md b/.claude/skills/quest-issues/SKILL.md new file mode 100644 index 00000000000..74e65c239a4 --- /dev/null +++ b/.claude/skills/quest-issues/SKILL.md @@ -0,0 +1,7 @@ +--- +name: quest-issues +description: Plan quests from open GitHub issues without the quest label. +--- + +Run `quest skill quest-issues` and follow its output. +If `quest` is not installed, follow https://github.com/kixelated/quest/blob/main/SETUP.md first. diff --git a/.claude/skills/quest-merge/SKILL.md b/.claude/skills/quest-merge/SKILL.md new file mode 100644 index 00000000000..8196069889d --- /dev/null +++ b/.claude/skills/quest-merge/SKILL.md @@ -0,0 +1,7 @@ +--- +name: quest-merge +description: Merge a GitHub PR once reviews and CI pass. +--- + +Run `quest skill quest-merge` and follow its output. +If `quest` is not installed, follow https://github.com/kixelated/quest/blob/main/SETUP.md first. diff --git a/.claude/skills/quest-plan/SKILL.md b/.claude/skills/quest-plan/SKILL.md new file mode 100644 index 00000000000..45e6f68feae --- /dev/null +++ b/.claude/skills/quest-plan/SKILL.md @@ -0,0 +1,7 @@ +--- +name: quest-plan +description: Scope, create, and publish a quest through an interactive grilling interview. Use when the user invokes /quest-plan, asks to plan a quest, or wants unsettled work split into quests. +--- + +Run `quest skill quest-plan` and follow its output. +If `quest` is not installed, follow https://github.com/kixelated/quest/blob/main/SETUP.md first. diff --git a/.claude/skills/quest-spawn-merge/SKILL.md b/.claude/skills/quest-spawn-merge/SKILL.md new file mode 100644 index 00000000000..8cedf122249 --- /dev/null +++ b/.claude/skills/quest-spawn-merge/SKILL.md @@ -0,0 +1,7 @@ +--- +name: quest-spawn-merge +description: Decide and merge GitHub PRs in parallel. +--- + +Run `quest skill quest-spawn-merge` and follow its output. +If `quest` is not installed, follow https://github.com/kixelated/quest/blob/main/SETUP.md first. diff --git a/.claude/skills/quest-spawn/SKILL.md b/.claude/skills/quest-spawn/SKILL.md new file mode 100644 index 00000000000..da9567055c9 --- /dev/null +++ b/.claude/skills/quest-spawn/SKILL.md @@ -0,0 +1,7 @@ +--- +name: quest-spawn +description: Spawn background agents to work on quests in parallel. +--- + +Run `quest skill quest-spawn` and follow its output. +If `quest` is not installed, follow https://github.com/kixelated/quest/blob/main/SETUP.md first. diff --git a/.claude/skills/quest-start/SKILL.md b/.claude/skills/quest-start/SKILL.md new file mode 100644 index 00000000000..8ab6bf60bf3 --- /dev/null +++ b/.claude/skills/quest-start/SKILL.md @@ -0,0 +1,7 @@ +--- +name: quest-start +description: Start work on a quest. +--- + +Run `quest skill quest-start` and follow its output. +If `quest` is not installed, follow https://github.com/kixelated/quest/blob/main/SETUP.md first. diff --git a/.claude/skills/quest-takeover/SKILL.md b/.claude/skills/quest-takeover/SKILL.md new file mode 100644 index 00000000000..004e1631892 --- /dev/null +++ b/.claude/skills/quest-takeover/SKILL.md @@ -0,0 +1,7 @@ +--- +name: quest-takeover +description: Adopt someone else's open PR and drive it to landable. +--- + +Run `quest skill quest-takeover` and follow its output. +If `quest` is not installed, follow https://github.com/kixelated/quest/blob/main/SETUP.md first. diff --git a/.claude/skills/spawn-merge b/.claude/skills/spawn-merge deleted file mode 120000 index 669e016de47..00000000000 --- a/.claude/skills/spawn-merge +++ /dev/null @@ -1 +0,0 @@ -../shared/spawn-merge \ No newline at end of file diff --git a/.claude/skills/spawn-quests b/.claude/skills/spawn-quests deleted file mode 120000 index 69f8c805967..00000000000 --- a/.claude/skills/spawn-quests +++ /dev/null @@ -1 +0,0 @@ -../../.quest/.claude/skills/spawn-quests \ No newline at end of file diff --git a/.claude/skills/start-quest b/.claude/skills/start-quest deleted file mode 120000 index c5fccd4a969..00000000000 --- a/.claude/skills/start-quest +++ /dev/null @@ -1 +0,0 @@ -../../.quest/.claude/skills/start-quest \ No newline at end of file diff --git a/.claude/skills/takeover b/.claude/skills/takeover deleted file mode 120000 index f004a334efe..00000000000 --- a/.claude/skills/takeover +++ /dev/null @@ -1 +0,0 @@ -../shared/takeover \ No newline at end of file diff --git a/.gitignore b/.gitignore index ec8f692718c..af3a5c21aca 100644 --- a/.gitignore +++ b/.gitignore @@ -15,7 +15,7 @@ /.claude/tmp/ /.claude/worktrees/ -# Per-worktree agent scratch (PR bodies, logs, notes); see the start-quest skill. +# Per-worktree agent scratch (PR bodies, logs, notes); see the quest-start skill. /.scratch/ # IDE diff --git a/.gitmodules b/.gitmodules index eb7bc693fb9..25cd0e0737d 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,6 +1,3 @@ [submodule ".claude/shared"] path = .claude/shared url = https://github.com/kixelated/skills -[submodule ".quest"] - path = .quest - url = https://github.com/kixelated/quest diff --git a/.quest b/.quest deleted file mode 160000 index d23e9880e71..00000000000 --- a/.quest +++ /dev/null @@ -1 +0,0 @@ -Subproject commit d23e9880e7193d31247445a1c5de0c516bbc6915 diff --git a/.remarkignore b/.remarkignore index f66f6687e71..5716b01a44d 100644 --- a/.remarkignore +++ b/.remarkignore @@ -16,10 +16,9 @@ doc/draft/ # Quests use a constrained Markdown dialect checked by the quest validator. quest/ -# Skills are symlinks into the kixelated/skills and kixelated/quest submodules, -# which format their own files; remark would follow them (and .agents, Codex's -# link to the same directory) and rewrite the pinned checkouts. +# Skills are symlinks into the kixelated/skills submodule, which formats its +# own files; remark would follow them (and .agents, Codex's link to the same +# directory) and rewrite the pinned checkout. .claude/shared/ -.quest/ .claude/skills/ .agents/ diff --git a/AGENTS.md b/AGENTS.md index 1740f36347f..799657cafb2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -89,8 +89,8 @@ just fix # Auto-fix lint/formatting, same scope These diff the branch against its base and only run the affected packages. -Quests are vendored from kixelated/quest in the `.quest` submodule, including `quest/AGENTS.md` and the quest skills; change them upstream. -Run the CLI as `just quest ...`. +When work mentions a quest, run `quest guide` and follow it. +The `quest` binary comes from the kixelated/quest flake input and serves the quest skills; change them upstream and bump the input. A quest deleted on `dev` is done, even while `main` still lists it. # Cross-Package Sync diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 10c8135fdb7..56baa2f739d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -49,7 +49,7 @@ For each finding: If you encounter issues, or findings that are out of scope, create follow-up quests. Focus on the core problem, offering a potential solution only if its obvious. -For non-trivial tasks, file an issue or offer to run `/plan-quests`. +For non-trivial tasks, file an issue or offer to run `/quest-plan`. # Forks diff --git a/biome.jsonc b/biome.jsonc index 0f28664e879..309ddb470f4 100644 --- a/biome.jsonc +++ b/biome.jsonc @@ -21,14 +21,7 @@ // - SVG assets, which Biome routes to its HTML parser and rejects. // - The audio jitter corpus, which is generated and byte-compared by its own test, // so a formatter rewriting it would fight the generator on every `just fix`. - // And the vendored kixelated/quest submodule, which formats its own files. - "includes": [ - "**", - "!.quest", - "!rs/moq-mux/src/container/ts/test_data", - "!**/*.svg", - "!doc/concept/audio-jitter/*.json" - ] + "includes": ["**", "!rs/moq-mux/src/container/ts/test_data", "!**/*.svg", "!doc/concept/audio-jitter/*.json"] }, "linter": { "rules": { diff --git a/flake.lock b/flake.lock index bf8e740574a..05b62f209bd 100644 --- a/flake.lock +++ b/flake.lock @@ -49,11 +49,42 @@ "type": "github" } }, + "quest": { + "inputs": { + "crane": [ + "crane" + ], + "flake-utils": [ + "flake-utils" + ], + "nixpkgs": [ + "nixpkgs" + ], + "rust-overlay": [ + "rust-overlay" + ] + }, + "locked": { + "lastModified": 1790533850, + "narHash": "sha256-6cBgVpfIBVQ9tTXyV7Xj8AAYH+Qtp6aOmFx/dwEUNLw=", + "owner": "kixelated", + "repo": "quest", + "rev": "a4c3debebeacc142dc31b170f3255d1ccf6e4c9b", + "type": "github" + }, + "original": { + "owner": "kixelated", + "repo": "quest", + "rev": "a4c3debebeacc142dc31b170f3255d1ccf6e4c9b", + "type": "github" + } + }, "root": { "inputs": { "crane": "crane", "flake-utils": "flake-utils", "nixpkgs": "nixpkgs", + "quest": "quest", "rust-overlay": "rust-overlay" } }, diff --git a/flake.nix b/flake.nix index 028422fd1b9..24c16850361 100644 --- a/flake.nix +++ b/flake.nix @@ -24,6 +24,15 @@ url = "github:oxalica/rust-overlay"; inputs.nixpkgs.follows = "nixpkgs"; }; + # The quest CLI, which also serves the quest guide and skills the stubs in + # .claude/skills call. Bump the rev to upgrade them. + quest = { + url = "github:kixelated/quest/a4c3debebeacc142dc31b170f3255d1ccf6e4c9b"; + inputs.nixpkgs.follows = "nixpkgs"; + inputs.flake-utils.follows = "flake-utils"; + inputs.crane.follows = "crane"; + inputs.rust-overlay.follows = "rust-overlay"; + }; }; outputs = @@ -33,6 +42,7 @@ flake-utils, crane, rust-overlay, + quest, ... }: let @@ -480,7 +490,8 @@ ++ ktDeps ++ goDeps ++ dartDeps - ++ devTools; + ++ devTools + ++ [ quest.packages.${system}.default ]; # jemalloc's configure uses -O0 test builds, which conflict with # Nix's _FORTIFY_SOURCE hardening (requires -O). diff --git a/justfile b/justfile index 25ec30d6553..af3866c3998 100644 --- a/justfile +++ b/justfile @@ -240,16 +240,6 @@ worktree ACTION="check" $BASE="": echo "recorded: $(git rev-parse --short "$recorded") (STALE; $base has moved since setup)" fi -# Run the quest CLI pinned by the .quest submodule: `just quest ready`. -[positional-arguments] -quest *args: - #!/usr/bin/env bash - set -euo pipefail - # A fresh worktree or CI checkout leaves the submodule empty. Only an empty - # one is initialized, so an unstaged bump under test is left alone. - [[ -e .quest/Cargo.toml ]] || git submodule update --init .quest - cargo run --quiet --locked --manifest-path .quest/Cargo.toml -- "$@" - # Install repo-wide tooling. Per-language deps install on first check. install: bun install @@ -451,7 +441,8 @@ _tools $FILES="": # `_check-common` runs on every invocation, so its tools are unconditional. tools=(actionlint bun jq nix nixfmt shellcheck shfmt taplo python3 nfpm dpkg-deb envsubst rpm) scoped '^(drafts/|doc/\.vitepress/drafts\.ts$)' && tools+=(kramdown-rfc xml2rfc) - scoped '^(bench/|quest/|\.quest$|rs/|Cargo\.(toml|lock)$|rust-toolchain\.toml$)' && tools+=(cargo envsubst) + scoped '^(bench/|rs/|Cargo\.(toml|lock)$|rust-toolchain\.toml$)' && tools+=(cargo envsubst) + scoped '^(quest/|flake\.lock$)' && tools+=(quest) scoped '^(py/|pyproject\.toml$|uv\.lock$|rs/moq-ffi/|doc/lib/py/|doc/lib/samples\.sh$)' && tools+=(uv) scoped '^(kt/|rs/moq-ffi/|doc/lib/kt/|doc/lib/samples\.sh$)' && tools+=(gradle java) # cargo because `go check` builds moq-ffi for the host, and skips on a @@ -552,7 +543,7 @@ _check $BASE $TEST: just rs tokio-features just rs media-features just --justfile bench/justfile check - just quest check + quest check # Not covered by the line above: moq-wasm only exists on the wasm32 target. just rs wasm just py check @@ -575,9 +566,9 @@ _check $BASE $TEST: just drafts check fi # Quest documents form one graph, so validate the whole living tree when - # either a quest or the pinned validator changes. - if echo "$files" | grep -qE '^(quest/|\.quest$)'; then - just quest check + # either a quest or the flake-pinned validator changes. + if echo "$files" | grep -qE '^(quest/|flake\.lock$)'; then + quest check fi just py check "$files" just kt check "$files" diff --git a/quest/AGENTS.md b/quest/AGENTS.md deleted file mode 120000 index 5216dd64086..00000000000 --- a/quest/AGENTS.md +++ /dev/null @@ -1 +0,0 @@ -../.quest/quest/AGENTS.md \ No newline at end of file From 222af2a7764f3a1c9e40f59f9e3340eb48213b7b Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 27 Sep 2026 12:12:49 -0700 Subject: [PATCH 4/4] chore(quest): drop the plan-* skills the main merge restored main's edits to them move upstream: the label timing is kixelated/quest#10 and the merge hand-off is kixelated/quest#12. Co-Authored-By: Claude Opus 5.5 --- .claude/skills/plan-issues/SKILL.md | 7 ----- .claude/skills/plan-quests/SKILL.md | 41 ----------------------------- 2 files changed, 48 deletions(-) delete mode 100644 .claude/skills/plan-issues/SKILL.md delete mode 100644 .claude/skills/plan-quests/SKILL.md diff --git a/.claude/skills/plan-issues/SKILL.md b/.claude/skills/plan-issues/SKILL.md deleted file mode 100644 index d5a88012e93..00000000000 --- a/.claude/skills/plan-issues/SKILL.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -name: plan-issues -description: Plan quests from open GitHub issues without the quest label. ---- - -Call /plan-quests for repository's open GitHub issues without the `quest` label. -Add the `quest` label to these issues once the PR is open, so another planner skips them. diff --git a/.claude/skills/plan-quests/SKILL.md b/.claude/skills/plan-quests/SKILL.md deleted file mode 100644 index 74c233d4d6d..00000000000 --- a/.claude/skills/plan-quests/SKILL.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -name: plan-quests -description: Scope, create, and publish a quest through an interactive grilling interview. Use when the user invokes /plan-quests, asks to plan a quest, or wants unsettled work split into quests. ---- - -Before you begin, read `quest/AGENTS.md` completely. - -Interview the user until you reach a shared understanding. - -Work the tree in **rounds**. -The **frontier** is every decision whose prerequisites are already settled. -Ask the whole frontier in one round, interactively if supported. -Select at least one answer as (recommended) and wait for the user's answers (never guess) before the next round. - -Each round the user answers reshapes the tree: settled decisions push the frontier outward and unblock questions that depended on them. -Recompute the frontier and ask the next round. -A question whose answer depends on another question still open in this round belongs to a *later* round, not this one. - -Finding *facts* is your job, never the user's. -When a frontier question needs a fact from the environment (filesystem, tools, etc.), dispatch a sub-agent to find it. -Don't block on it, ask the rest of the frontier now. -The *decisions* are the user's: put each to them and wait. - -Search other quests and questlines to keep the larger plan consistent. -When the work changes what a user sees (a wire, an API, a flag, a dashboard), ask whether it needs documentation the feature quest cannot carry inline (a new page or guide), and recommend a quest for that; docs a change makes stale stay in that change. -When the frontier disagrees with a settled quest/plan, challenge the user and resolve the conflict. - -Begin the interview by scoping the goal: the observable outcome, why it matters, and its important boundaries and non-goals. -Restate the goal in one sentence and get it confirmed before moving on to implementation decisions. -If the goal contains independently completable outcomes, split them before planning. -Map the implementation plan as a design tree: every material decision branches into the decisions that hang off it. - -The session is done when the frontier is empty. -The result may be one quest or multiple quests and questlines, split based on what can be completed independently. -Prefix each quest title with `[XS]`, `[S]`, `[M]`, `[L]`, or `[XL]`, including implementation, verification, and landing work. -Once complete, create, update, or delete the relevant quests and questlines. -Record each settled decision and its reason in the quest's Plan, so later sessions don't ask it again. -New work joins the milestone matching its priority, at its rank; a questline groups only quests that ship together, and its README holds the work no child owns (the end-to-end test, the docs page). - -When done, commit and create a draft PR following `CONTRIBUTING.md`. -After local checks pass, run `/merge` on it.