From accb7034877ff00fee4e910d346c72beb666953a Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 19 Oct 2026 08:24:05 -0700 Subject: [PATCH] docs(quest): plan the local harness and inbox answer flow Co-Authored-By: Claude Opus 5.5 --- quest/m0/kix/README.md | 2 ++ quest/m0/kix/answer-flow.md | 24 ++++++++++++++++++++++++ quest/m0/kix/harness.md | 36 ++++++++++++++++++++++++++++++++++++ 3 files changed, 62 insertions(+) create mode 100644 quest/m0/kix/answer-flow.md create mode 100644 quest/m0/kix/harness.md diff --git a/quest/m0/kix/README.md b/quest/m0/kix/README.md index 0a107077..94dfd0fc 100644 --- a/quest/m0/kix/README.md +++ b/quest/m0/kix/README.md @@ -89,6 +89,7 @@ operator-paid-hosting decisions: ## Required +- [Local harness](/quest/m0/kix/harness.md) - the Worker served locally with seeded data and mocked GitHub for browser checks - [Deploy kix.quest](/quest/m0/kix/deploy.md) - the operator registers the App and deploys the Worker with GitHub sign-in at kix.quest - [Operator setup](/quest/m0/kix/operator-setup.md) - fork namespace, pilot installations, and a verified test PR - [Runner](/quest/m0/kix/runner.md) - `quest runner` on Linux and macOS with Nix devShells, accounts, and the Claude Code adapter @@ -98,6 +99,7 @@ operator-paid-hosting decisions: - [Webhook reconcile](/quest/m0/kix/reconcile.md) - new issues and PRs arrive in the inbox ready to act on, without a manual refresh - [Inbox merge](/quest/m0/kix/merge.md) - PR items merge the reviewed head through GitHub's rules - [Co-maintainer inbox](/quest/m0/kix/members.md) - every current maintainer sees enrolled projects in their inbox +- [Answer flow](/quest/m0/kix/answer-flow.md) - move to the next decision after an answer, with neutral refusals - [Output retention](/quest/m0/kix/output.md) - raw agent output in R2, kept 30 days and capped at 64 MiB per attempt - [Agent activity](/quest/m0/kix/activity.md) - agent cards and map highlights built from checkpoint summaries - [Mobile web app](/quest/m0/kix/mobile.md) - an installable PWA with Web Push for decisions diff --git a/quest/m0/kix/answer-flow.md b/quest/m0/kix/answer-flow.md new file mode 100644 index 00000000..a1010185 --- /dev/null +++ b/quest/m0/kix/answer-flow.md @@ -0,0 +1,24 @@ +# [XS] Move to the next decision after an answer + +## Goal + +After a maintainer answers a decision in the inbox, the page moves on to the +next active decision with a short "Answer recorded" notice. When an action is +refused, the page has a neutral title and says why, whatever the action was. + +## Plan + +Decided 2026-10-19 as a follow-up of the decision inbox (#144), which stays +on the item just answered, and titles every refusal "Not recorded" even for +a refused "Refresh from GitHub": + +- Redirect to the next active decision, or to the inbox's empty state, and + show the notice there. The answered item stays reachable under its + earlier answers. +- Retitle the refused-action page neutrally (for example "Couldn't do + that"), with the specific reason and a link back to the item. +- Keep the form posts working without JavaScript. Update the inbox tests. + +## Required + +- [Decision inbox](/quest/m0/kix/prompts.md) - the answer and refusal pages this changes diff --git a/quest/m0/kix/harness.md b/quest/m0/kix/harness.md new file mode 100644 index 00000000..b119c526 --- /dev/null +++ b/quest/m0/kix/harness.md @@ -0,0 +1,36 @@ +# [M] Run the Worker locally with seeded data + +## Goal + +One checked-in command, such as `just dev-seeded`, serves the real Worker +locally with representative seeded data, mocked GitHub, and a local sign-in, +so agents and maintainers can check UI changes in a browser at phone and +desktop widths. It works inside sandboxed agent environments, where +`wrangler dev` currently hangs. + +## Plan + +Decided 2026-10-19 as a follow-up of the decision inbox (#144). Its +browser check needed a throwaway harness because `wrangler dev`'s internal +proxy hangs in the agent sandbox on a DNS lookup of "dummy": + +- Check in a seeded harness rather than debugging `wrangler dev` for one + agent environment. Bundle the Worker as `wrangler deploy --dry-run` does, + serve it with Miniflare on local D1 and R2, and apply the checked-in + migrations. +- Mock GitHub's REST API and short-circuit the OAuth redirect so sign-in + completes locally. The mock serves only localhost and never holds real + credentials; it is development tooling, not a production code path. +- Seed representative state: agent prompts with several questions, an + account limit, failed, queued and running jobs, PRs with checks and + reviews, issues including a pointer-only one and a long title, ready + quests, and a paused project. +- Keep the seed and mock reusable as the base for the kix epic's stubbed + end-to-end test, rather than a second fixture set. Share fixtures with + the Worker tests where practical. +- Document the command in `cloudflare/README.md` as the way to check UI + changes in a browser. + +## Required + +- [Decision inbox](/quest/m0/kix/prompts.md) - the inbox state the seed covers