docs(quest): plan /quest-afk and the rules agents kept needing

quest/m0/helpers/README.md

@@ -5,7 +5,8 @@
 Agents stop hand-writing `gh`, `jq`, and `sed` loops for routine quest
 workflow steps, because `quest` commands cover them and the skills point at
 those commands: CI results while waiting, a one-shot PR status, claiming
-quests and PRs, moving and deleting quests, and unattended triage.
+quests and PRs, moving and deleting quests, and unattended work. Skill
+rules that remove the maintainer's repeated steering belong here too.
 
 Only generic helpers belong here. Non-goals: the kix.quest UI, a daemon, and
 deciding whose review or which result counts; the agent still decides.
@@ -45,10 +46,22 @@ commands from Sep-Oct. Session counts in each child come from that window.
   without that section.
 - Decided (user): this epic ranks after the worktree and gate quests and
   before the Kix decision UI. Children rank by sessions affected.
+- Decided 2026-10-21 (user), from a month of moq maintainer transcripts:
+  quests that remove the maintainer's repeated steering join this epic.
+  `/quest-afk` and the guide rules rank first, since they save the most
+  maintainer time and change only prose. The complete loop ranks right after
+  the PR state commands, which also rewrite `complete`. Findings that fit an
+  existing child went into it: the merge method and the merged-PR refusal
+  into [PR state commands](/quest/m0/helpers/pr-states.md). Ready at
+  hand-back went into [Guide rules](/quest/m0/helpers/guide-rules.md), since
+  quest start landed without it.
 
 ## Required
 
+- [Unattended work](/quest/m0/helpers/afk.md) - `/quest-afk` replaces the `afk` argument: it skips every decision and keeps starting agreed work; every skill ends with a summary
+- [Guide rules](/quest/m0/helpers/guide-rules.md) - pushing, briefs, ready at hand-back, follow-ups, whose review counts, and user-owned choices
 - [PR state commands](/quest/m0/helpers/pr-states.md) - `quest iterate`, `ready`, `merge`, and `release` label the one owner of a PR
+- [Complete loop](/quest/m0/helpers/complete-loop.md) - `/quest-complete` re-scans PRs, keeps picks and holds, and counts rounds per PR
 - [Headless agents](/quest/m0/helpers/headless-agents.md) - `/quest-spawn api` launches, resumes, and stops billed agents through one command auto mode allows
 
 ## Related

quest/m0/helpers/afk.md

@@ -0,0 +1,56 @@
+# [S] Keep working unattended with /quest-afk
+
+## Goal
+
+`/quest-afk` keeps quest work moving while the user is away and asks
+nothing: it skips every decision instead of choosing one, leaves each skipped
+decision on its PR, and keeps starting agents and PRs for work the user
+already agreed to. Every quest skill ends with a final summary, so returning
+starts with what needs the user. This replaces the steering the user typed in
+about 20 moq sessions ("I'm going to bed", "you don't need to decide
+everything, only when blocked", "I'm back, what decisions need to be made")
+and the one-line global `/afk` and repository `/recommended` skills.
+
+Non-goals: a wind-down mode that stops dispatching ("just make the PRs then
+stop"), and noticing the user's return; the final summary covers it.
+
+## Plan
+
+Decided 2026-10-21 (user), replacing the 2026-10-19 `afk` argument on
+`/quest-complete` and `/quest-spawn`, from an audit of a month of moq
+maintainer transcripts. That argument landed the same day in
+[kixelated/quest#166](https://github.com/kixelated/quest/pull/166) as an
+`## Unattended` section in `assets/skills/complete.md` and
+`assets/skills/spawn.md`, plus a README sentence. It acts on its own
+recommendations, answers simple decisions agents report, and still asks about
+each merge and delete. This quest replaces it:
+
+- A skill of its own, `/quest-afk`, not an argument on two skills. Delete
+  both `## Unattended` sections and the README's `afk` sentence in the same
+  PR. At the user's request the old skills were removed the same day, ahead
+  of this quest, so the user types those instructions by hand until it
+  lands: the global `/afk` link in kixelated/dotfiles, the `afk` skill in
+  [kixelated/skills#8](https://github.com/kixelated/skills/pull/8), and the
+  `/recommended` links in
+  [moq-dev/moq#6200](https://github.com/moq-dev/moq/pull/6200) and
+  moq-dev/moq.pro.
+- It makes no decisions. Every question a quest skill would ask is skipped,
+  not answered with its recommendation: the PR stays a draft listing the
+  decision with a recommendation, a quest that would need asking is left
+  unstarted and listed, and suggested follow-ups wait for `/quest-plan`.
+  Unlike the landed argument, it picks no skip, `/quest-ready`, or
+  `/quest-iterate` for a PR the user has not picked, answers no reported
+  decision, and asks nothing about merges or deletes: it never merges or
+  deletes on its own judgment.
+- It keeps going as far as already agreed work allows: it starts ready
+  quests that `/quest-spawn` starts without asking, and carries on the actions
+  the user already picked, until nothing is left that needs no decision.
+- Decided (user): every quest skill ends with a final summary in sections,
+  such as its PRs and their states, the open decisions, and suggested
+  follow-ups. Don't fix the exact shape. State this once in the guide rather
+  than in each skill.
+- Write `assets/skills/afk.md` following `PROMPTING.md`, reusing the spawn
+  and complete skills' dispatch rules instead of restating them. Register it
+  in `src/cli/skills.ts` and the README's skill table; existing
+  repositories get its `quest-afk` stub by rerunning `quest init`. The user
+  asked for the skill and guide edits through this plan.

quest/m0/helpers/complete-loop.md

@@ -0,0 +1,31 @@
+# [S] Keep /quest-complete current across rounds
+
+## Goal
+
+`/quest-complete` notices new PRs as they appear, keeps the user's picks and
+holds for the whole session, and counts review rounds per PR rather than per
+sub-agent. The maintainer stops asking "any new PRs?" (8+ times in a month of
+moq transcripts) and stops re-stating holds and merge approvals.
+
+## Plan
+
+Decided 2026-10-21 (user), from that audit. The user asked for these skill
+edits through this plan.
+
+- Re-scan the open PR list whenever a sub-agent reports or a merge wait
+  wakes, not only before finishing, and ask about new PRs in scope the same
+  way.
+- An "accept all" or "use your recommendations" answer never covers a
+  merge; each merge needs its own pick. A skip or hold stands across refreshes
+  and re-dispatched sub-agents until the user lifts it.
+- Fresh sub-agents count review rounds from zero, so the merge skill's design
+  checkpoint never fires across re-dispatches. Count rounds from the PR's
+  timeline since its last design change, and apply the same checkpoint in
+  `iterate`, which has none today. Record a design change somewhere the next
+  agent can read it back from the PR, such as the comment recording the
+  decision.
+
+## Related
+
+- [PR state commands](/quest/m0/helpers/pr-states.md) - also rewrites how `complete` dispatches and skips held PRs
+- [Unattended work](/quest/m0/helpers/afk.md) - carries on picks the user already made

quest/m0/helpers/guide-rules.md

@@ -0,0 +1,66 @@
+# [S] Guide and skill rules agents kept needing
+
+## Goal
+
+Agents stop needing the same corrections from the maintainer, because the
+guide and skills state them: who may push to a branch, what a brief carries,
+when a finished quest's PR is marked ready, where follow-ups go, whose review
+counts, which choices are the user's, and searching for duplicates before
+planning. Each rule comes from steering the
+moq maintainer typed repeatedly over a month of transcripts.
+
+Non-goals: CLI changes, and restating repository rules; a repository's own
+instructions keep owning its merge, review, and decision policy.
+
+## Plan
+
+Decided 2026-10-21 (user), from that audit. Each finding was checked against
+the skill text on `main` that day. The user asked for these guide and skill
+edits through this plan; follow `PROMPTING.md` (goals over prescriptions).
+
+- Pushing (guide): never rebase or force-push a branch another session may
+  hold. Before every push to a branch that already has a PR, confirm the PR
+  is still open, because a push after the merge brings the deleted branch
+  back. The claim push `quest start` makes, which comes before its draft PR
+  exists, is exempt.
+- Briefs (`spawn`, `complete`): a sub-agent's brief carries the quest or PR,
+  the user's picks, and the scope, and leaves repository rules to that
+  repository's own instructions instead of restating them.
+- Hand-back (guide, `start`): a complete quest is marked ready even if the
+  agent made choices without asking; it lists those choices in the PR body
+  for review. Only a decision left for the maintainer keeps the PR a draft
+  with `## Decisions needed`. Drop the `start` skill's "the user has settled
+  every decision, including choices you made without asking" gate, which
+  disagrees with the guide's Execution section. "Should I mark it ready?"
+  came up in about 18 moq sessions. Planned for quest start, which landed in
+  [kixelated/quest#167](https://github.com/kixelated/quest/pull/167)
+  without it.
+- Planning (`plan`): search the quest tree, git history for deleted quests,
+  and open PRs touching `quest/` before anything else, and show any overlap in
+  the first round. The maintainer asked "double check we don't already have
+  it" and "I thought I had a probe quest already?".
+- Audit (`audit`): moving a quest between milestones or changing its rank is
+  always the user's decision, never a factual correction. "Apply factual
+  corrections" was read as permission to move quests, and the move was
+  reverted.
+- Follow-ups (guide): a follow-up becomes a quest through `/quest-plan`,
+  never a session task card or a GitHub issue.
+- Reviews (guide): "At least one review is required" defers to the
+  repository's review policy for whose review counts. Where that policy
+  says nothing, a review by the PR's author, or an AI-attributed comment
+  posted from the maintainer's account, does not count. This is guidance
+  for the agent's judgment; the helper commands still never decide whose
+  review counts, as the epic's non-goal says.
+- Decisions (`iterate`): a sub-agent that cannot prompt picks the
+  recommended option only for decisions the repository's instructions don't
+  reserve for the maintainer (moq reserves API shape, naming, and scope);
+  the rest stay open in the PR.
+- Dropped (user): filtering CodeRabbit rate-limit and Codex "review started"
+  notices in `quest wait`. Vendor-specific filters break the core's
+  independence and the helpers' "the agent decides which result counts"
+  non-goal; the merge skill already re-waits on bot notices.
+
+## Related
+
+- [PR state commands](/quest/m0/helpers/pr-states.md) - refuses a merged PR mechanically and carries the merge method
+- [Unattended work](/quest/m0/helpers/afk.md) - the guide's final-summary rule

quest/m0/helpers/pr-states.md

@@ -50,11 +50,16 @@ repositories ("those are in another repo?").
   PR is queued or auto-merging, until it merges. If it leaves the queue
   unmerged, the command that notices removes the label, and the PR is idle
   and waits on the maintainer's pick again.
-- Decided (user): a repository with its own queue, such as moq-dev/moq.pro's
-  `merge` label from
-  [moq-dev/moq.pro#2510](https://github.com/moq-dev/moq.pro/pull/2510), says
-  how to land in its root instructions. The skill follows those instead of
-  `--land`; the label still means "on its way in".
+- Decided 2026-10-21 (user), replacing a carve-out for moq-dev/moq.pro's
+  `merge` label queue, which the user means to remove: `--land` makes a merge
+  commit by default (`gh pr merge --merge`), through GitHub's merge queue
+  when the base has one. `--squash` or `--rebase` selects another method;
+  the command never reads prose, so the merge skill picks the flag from the
+  method a repository's root instructions name for that base. The merge
+  skill named no method, so an agent squashed a PR into moq-dev/moq's
+  `release`, which needs a merge commit.
+- Every command refuses a merged or closed PR, because a push after the merge
+  brings the deleted branch back.
 - A merge pick covers the fixes its own agent pushes for conflicts, CI, and
   review findings. A head moved by anyone else, a design change, or the merge
   skill's design checkpoint asks the user again, as `complete` already says.
@@ -67,5 +72,5 @@ repositories ("those are in another repo?").
 - Test a refused draft its starter still holds, a race for one PR, two
   sessions taking the same state, a release
   with a stale token, a refused swap, landing on a moved head, a PR
-  leaving the queue, and a repository whose root instructions override
-  landing.
+  leaving the queue, a refused merged PR, the default merge commit, and
+  `--squash` and `--rebase`.