Skip to content

docs(quest): plan a sweep that re-checks gates so no quest waits on a cleared one - #4585

Closed
kixelated wants to merge 1 commit into
mainfrom
quest/plan-gate-sweep
Closed

kixelated wants to merge 1 commit into
mainfrom
quest/plan-gate-sweep

Conversation

@kixelated

@kixelated kixelated commented Sep 30, 2026 •

Copy link
Copy Markdown
Collaborator

Problem

quest/m4/README.md promises a re-check that nothing performs:

Each quest states its gate as a plain-text Required bullet. Re-check the
gates periodically; when one clears, remove the bullet and promote the quest to
the milestone its priority belongs in.

quest guide is the source of that promise: "A plain-text bullet names a
condition outside the repository. Periodically check if it has cleared."
quest check validates structure, not freshness, so when a gate clears the
quest stays blocked forever and the work it describes silently never starts.

This is not hypothetical. Two gates have already cleared and nothing noticed:

  • #4428 merged to dev merged 2026-09-29 and was the only gate on
    quest check everywhere, an m0 quest.
    quest ready still reports it blocked, and it is missing from the 225 ready
    quests.
  • #4364 merged to main merged 2026-09-28 and is one of two gates on
    the client-CA quest.

And the convention is not applied where it matters most:
quest/m1/wt-close-upstream.md has no ## Required on main, so quest ready
calls it ready and lists it among the 225 while its web-transport-moq release
has not shipped (no 1.3.3 tag; moq-dev/noq#21 is open). #4520 adds the bullet.
The maintainer decided that quest stays in m1 rather than moving to m4, so its
gate has to be findable from where it is.

Approach

Add one S quest for the outcome: every quest
gated on the outside world states that gate as a plain-text Required bullet,
one dated sweep lists every open gate beside its quest, and a gate whose
condition has cleared is promoted within days. Its Plan records the decisions
below so a later session does not re-ask them. Nothing else changes.

Impact

  • Public API: none. Wire: none.
  • Files: quest/m1/gate-sweep.md (new), quest/m1/README.md (one Required
    bullet, inserted after the Tooling line). No package version bumped.
  • quest check: 449 documents ok before, 450 after.

Alternatives

  • Enforce instead of report: teach quest check to evaluate a gate and fail
    when it is satisfied. Rejected, see decision 3. A plain-text condition is a
    sentence about the world; a checker that guesses is the warn-and-continue the
    repository rules forbid.
  • A Gates section in the quest format carrying a machine-readable predicate and
    a check date. That is the honest end state, but the guide owns the format, so
    it is upstream in kixelated/quest, not here.
  • Do nothing and rely on /quest-audit. It is periodic and human-driven, which
    is the current state of affairs.

Follow-ups

  • kixelated/quest: a quest gates listing. src/ready.rs already models a
    plain-text bullet as a blocker with no path, so the list belongs to the tool
    that parses the tree, and it would serve every repository rather than this one.
    When it ships, bump the flake input and the sweep becomes a one-liner.
  • kixelated/quest: a machine-readable gate predicate, which is what would let a
    cleared release fail instead of being listed.
  • The two cleared gates (Merge main into dev #4428, fix(cli): refuse a client CA under --auth-public on a listener #4364) are promoted inside this quest, as its
    first move.
  • AGENTS.md states one stale-quest rule, "a quest deleted on dev is done, even
    while main still lists it", which is a workaround for the fact that a gate
    has no schedule. The goal-level rule is one sentence covering both: nothing
    stays in a waiting milestone once its condition has cleared, whatever
    cleared it. Per PROMPTING.md an agent-instruction file stays light, so this
    replaces the case rather than adding to it. Not done here, because AGENTS.md
    is not to be edited unprompted.

Decisions

A background agent ran this interview itself, so every option below was chosen
by the agent rather than by the maintainer. Each is marked either
maintainer-settled, safe to proceed or needs the maintainer. The
maintainer can overturn any of them by editing the Plan; nothing has been merged.

Round 0, goal

Q. What is the observable outcome?

  • ✅ A plain-text gate is re-checked on a schedule, a cleared gate is noticed,
    and its quest is promoted, so no work is silently stranded.
    (recommended)
  • ❌ quest check learns to evaluate gate conditions and fails when one is
    satisfied.
  • ❌ An agent skill runs the re-check by hand whenever it starts a quest.
  • ❌ A Gates section in the quest format carrying a predicate and a check date.

maintainer-settled, safe to proceed. The first is the outcome the m3 and m4
READMEs already promise. The second and fourth need a format the guide defines
upstream. The third is what already happens, unreliably, and it is what left
#4428 sitting blocked for a day after it merged.

Round 1, scope split

Q. A quest deleted on dev while main still lists it is a second stale-quest
outcome. Same quest, or separate?

  • ✅ Separate: out of scope here, with the reason recorded, and the fix filed
    upstream beside overlay.
    (recommended)
  • ❌ Merge both into one "the tree is stale" quest.
  • ❌ Two quests in this repository.

maintainer-settled, safe to proceed. Different predicate (an external
condition versus a branch in this repository), different cadence (a day versus a
merge), different tool (overlay already reads questline branches; a nightly
sweep does not). AGENTS.md already states the human rule for it, and #4583 is
removing the one live instance (ts-import-shared-shift, describing a mechanism
#4543 deleted). Whether to file it in kixelated/quest or as a second moq quest
is needs the maintainer (see below).

Round 2, where the code lives

Q. Should the quest CLI own this rather than the moq repository?

  • ✅ Ship the convention and the schedule here; the parser is upstream, named
    as a follow-up, and the flake input moves when it lands.
    (recommended)
  • ❌ Make this quest depend on a quest gates subcommand landing upstream first.
  • ❌ Hand-roll a permanent gate parser in moq.

maintainer-settled, safe to proceed, and flagged prominently. Facts: AGENTS.md
says skills and the guide change upstream in kixelated/quest and the flake input
is bumped. src/ready.rs there already models a plain-text bullet as
Blocker { path: None, text }, so the listing is better served by the tool that
parses the tree, and it would cover every repository. kixelated/quest's own
quest/m0/README.md decides "The CLI stays offline. Anything touching GitHub
... lives in skills", so a checker that resolves an issue or a release cannot be
a subcommand. The moq side keeps the schedule, the pinned issue and the
promotion discipline, which are genuinely this repository's. Blocking this quest
on a release of the tool that reports blocked quests would be the exact failure
it is about. The honest summary: the listing belongs upstream, the outcome
belongs here.
Whether to reverse that call is needs the maintainer.

Round 3, report or fail loud

Q. The sweep cannot evaluate a human statement. Report, or fail?

  • ✅ Report: one dated list per run. Fail only when the tree is malformed or
    the recipe cannot run.
    (recommended)
  • ❌ Fail the nightly while any gate is open.
  • ❌ Fail when a gate is older than N days.
  • ❌ Guess mechanically (issue closed means settled) and fail on the guess.

maintainer-settled, safe to proceed. AGENTS.md's "fail loud and early" covers
input the tool can decide; a plain-text condition is not that, and mis-reading
"msfts#33 settles the ES-level payload unit" as "msfts#33 is closed" would
promote a quest on a condition nobody confirmed. Age is the mirror error: a
Raspberry Pi gate in m3 can wait two years and still be correct, so a deadline
punishes the honest gates and not the stale ones. The mechanical half does fail
loud: a malformed tree or a broken recipe is an error, not an empty list.

Round 4, where the record lands

Q. What makes the report something a human actually reads?

  • ✅ One pinned issue, one dated comment per run. (recommended)
  • ❌ Fail the nightly and let the alert carry it.
  • ❌ A generated Markdown file under quest/.
  • ❌ A page under doc/.

maintainer-settled, safe to proceed. Consecutive comments diff to the gate
that disappeared, and "re-checked on 2026-10-02" becomes evidence rather than a
promise. Failing the nightly instead pages Discord every day for as long as an
m3 hardware gate is open, which is how a page becomes noise. A file under
quest/ is impossible: quest check reads every Markdown document there as a
quest and rejects one with no ## Goal. doc/ is user-facing and this is not.

Round 5, the tree

Q. Is m4 the only milestone where a gate may live?

  • ✅ One convention for the whole tree, with the re-check sentence stated once
    in the root questline's Plan.
    (recommended)
  • ❌ Keep it an m3/m4 convention and add a second list for the rest.

maintainer-settled, safe to proceed. 21 of the tree's 719 Required entries
are plain-text conditions and 11 sit in m0..m2, because "re-check the gates
periodically" is written twice, in the m3 and m4 READMEs, and reads as their
private convention. quest ready has no idea m4 is special, which is why
wt-close-upstream reads as ready.

Round 6, the m4 file names

Q. Do the inconsistent m4 names get normalized in this quest?

  • ✅ Rename quest/m4/video-vaapi.md to quest/m4/vaapi.md. (recommended)
  • ✅ quest/m4/vaapi-codecs.md (alternative name, same change).
  • ❌ Leave the names alone.

Needs the maintainer (naming is the maintainer's, per AGENTS.md). The case
for doing it at all: the sweep prints paths, and one list carrying
video-vaapi.md beside vaapi-resize-pool.md gives the same crate two names,
which is the "cannot tell which is which without opening it" cost the m4 README
bullets exist to avoid. vaapi.md is recommended because it pairs with
vaapi-resize-pool.md as a family and the m4 labels already read as an umbrella
plus its one extra. No PR holds the old quest/m4/video-vaapi branch, so the
rename is free. Splitting it into its own PR is also defensible, since it is
independently completable.

Round 7, placement

Q. Which milestone and rank?

  • ✅ m1, immediately after the Tooling line. (recommended)
  • ❌ m0, first, beside quest check everywhere.
  • ❌ m4, since the subject is upstream work.

maintainer-settled, safe to proceed. Nothing blocks it and no PR is in
flight, so it is the next wave rather than in-flight work; m1's Plan already
separates planning from implementation, and Tooling is its family. m4 would make
it a gate of our own. Rank is one line to move.

Round 8, size

Q. [XS], [S], or [M]?

  • ✅ [S]. (recommended)
  • ❌ [XS]: a script, a test, a nightly step, two promotions, three README
    edits and a rename is past one sitting.
  • ❌ [M]: no risky change and no new subsystem.

maintainer-settled, safe to proceed.

Round 9, first move

Q. What happens to the two gates that have already cleared?

  • ✅ Promote both inside this quest, and make the sweep name them so a sweep
    that finds nothing new is itself evidence.
    (recommended)
  • ❌ Promote them in a separate PR right now.
  • ❌ Leave them and let the sweep find them.

maintainer-settled, safe to proceed. Neither quest changes milestone: the
cleared gate was never what set its rank, and each still has a gate that blocks
it. A drive-by PR for them would be exactly the kind of unrelated change
AGENTS.md tells us to split, and they are the proof the quest exists for, so
they belong in it.


Needs the maintainer

  1. Does the gate listing belong in kixelated/quest rather than moq? The
    agent's answer is no (the schedule and the promotion discipline are moq's,
    the parser is reusable and belongs upstream, and moq's own guide and skill
    changes are upstream by rule), but the call belongs to the maintainer, and
    reversing it moves the work.
  2. video-vaapi.md to vaapi.md, in this quest or its own PR? Naming and
    PR scope.
  3. Pinned issue, or the run log? The repository has no existing
    report-into-a-page pattern, so a daily comment on one issue is new machinery
    (a GH_TOKEN on the nightly job) and the maintainer may prefer the log.
  4. The dev-deletes-while-main-lists case: upstream quest in
    kixelated/quest, or a second moq quest?
    Deliberately out of scope here.
  5. Rank: m1 after Tooling, or m0 beside quest check everywhere? One line.
  6. Replace the stale-quest case in AGENTS.md with the goal-level rule. The
    current line encodes a workaround for gates having no schedule; once this
    quest lands it is the wrong rule to teach. Proposed replacement: "Nothing
    stays in a waiting milestone once its condition has cleared, whatever
    cleared it." Needs prompting, since AGENTS.md is not edited unprompted.

(Written by Space Bunny Free)

A plain-text `Required` bullet is a condition outside the repository, and
`quest guide` says to check periodically whether it has cleared. Nothing
checks. #4428 merged to `dev` on 2026-09-29 and was the only gate on the m0
quest-check-everywhere, which `quest ready` still reports blocked; #4364
merged to `main` on 2026-09-28 and is one of two gates on relay-auth-client-ca.

The quest's Plan records the settled decisions: one convention for the whole
tree stated once in the root questline, a dated sweep that reports rather than
guesses, the record in a pinned issue, the parser left to kixelated/quest, and
the dev-versus-main cross-branch case deliberately out of scope.

Co-Authored-By: Space Bunny Free <noreply@opencode.ai>
@kixelated
kixelated marked this pull request as ready for review September 30, 2026 14:15
@coderabbitai

coderabbitai Bot commented Sep 30, 2026

Copy link
Copy Markdown
Contributor

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 11 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used all 4 included reviews currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 245c590b-b996-4c20-ab0c-927b54abf96c

📥 Commits

Reviewing files that changed from the base of the PR and between 6f1a9e3 and 53b5f7f.

📒 Files selected for processing (2)
  • quest/m1/README.md
  • quest/m1/gate-sweep.md
  • Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.


Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 30, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-09-30T14:21:47.107580Z 53b5f7f Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@kixelated kixelated left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Automated review by review (OpenAI)

Reviewed commit: 53b5f7f

P2: Complete the re-check loop before treating a dated listing as evidence. In quest/m1/gate-sweep.md:62-65, the nightly only republishes the bullets. If an upstream condition clears while its bullet remains, consecutive reports are identical; the gate disappears only after somebody independently notices and edits the tree. This preserves the failure the Goal promises to fix. Add an explicit scheduled human/agent evidence-checking step, with responsibility for recording the outcome and proposing verified gate removal/promotion. Reserve “re-checked” for that step; listing alone is not a check.

Direction: keeping parsing upstream and avoiding guessed predicates is sound. A scheduled evidence-backed audit is the simpler useful first step. Defer the unrelated VAAPI rename (lines 83-89); both that rename and the pinned-issue destination should remain proposals in the Plan while the PR description still asks the maintainer to decide them.

Verification: statically reviewed both changed files, linked quest context, repository instructions, and the pinned quest guide/readiness code; verified #4428 and #4364 merged. The head's Check workflow succeeded, but its Test step was skipped. I did not run quest check locally because quest/Nix are unavailable here. This PR changes only planning docs, with no public API or wire changes.

(Written by OpenAI)

kixelated added a commit that referenced this pull request Sep 30, 2026
A quest waiting on the outside world states its gate as a plain-text
Required bullet in any milestone, re-checked by /quest-audit. Folded in
from #4585, which is abandoned in favor of this.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kixelated

Copy link
Copy Markdown
Collaborator Author

Abandoning this in favor of #4589, per the maintainer.

(Written by Claude Opus 5.5)

@kixelated kixelated closed this Sep 30, 2026
@kixelated
kixelated deleted the quest/plan-gate-sweep branch September 30, 2026 14:19

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 53b5f7f3e2

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread quest/m1/gate-sweep.md
Comment on lines +53 to +58
- **The sweep lists; it does not judge.** A plain-text condition is a sentence
about the world, and the repository rules say to error on malformed input
rather than warn and continue. Guessing is the failure: reading "msfts#33
settles the ES-level payload unit" as "msfts#33 is closed" would promote a
quest on a condition nobody confirmed. So the sweep prints the gates and
fails only when the tree is malformed or the recipe cannot run. A deadline on

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Add a step that actually re-checks each gate

Printing the same plain-text blockers on every scheduled run does not evaluate whether their external conditions have cleared. For example, after a WebKit release ships, the job will keep posting the unchanged Safari gate until someone independently notices and edits the quest; only then can consecutive comments show that it disappeared. The proposed sweep therefore reproduces the failure described in the Goal instead of ensuring cleared gates are noticed and promoted, so it needs an explicit human or machine evaluation step rather than only listing repository state.

Useful? React with 👍 / 👎.

Comment thread quest/m1/gate-sweep.md
Comment on lines +83 to +87
- **Normalize the m4 file names.** The sweep prints paths, and
`quest/m4/video-vaapi.md` beside `quest/m4/vaapi-resize-pool.md` gives one
list two names for the same crate, which is the "cannot tell which is which
without opening it" cost the m4 README bullets exist to avoid. Rename
`video-vaapi.md` to `vaapi.md`; `vaapi-resize-pool.md` is already right. No

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Split the unrelated VAAPI filename cleanup

The sweep can report either pathname, so renaming this quest does not contribute to gate discovery or scheduling. A repo-wide search also finds six other quest documents linking /quest/m4/video-vaapi.md, making this a cross-tree cleanup with its own link-churn and conflict risk; keep this implementation quest focused and handle the rename separately.

AGENTS.md reference: AGENTS.md:L20-L20

Useful? React with 👍 / 👎.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant