Study proposals and run pages
How a study’s proposal is stored and accepted, and how a page a run publishes is kept from reaching the board, for people changing that code. How a study is kept from pushing, and its mock folder, are in How a study is kept from pushing. The user guides are Studies and Recipes.
The proposal
propose_project {name, description, cards:[{key, title, notes, depends_on, migration, protected_paths}], questions:[{question, cards}]} writes a project_proposals row through machine_propose_project. The database
refuses a missing name or title, more than 30 cards, a dependency on a card outside the proposal, and a cycle. A card
holds one pending proposal; a later call replaces it. A headless Claude run gets mcp__andon__propose_project
pre-approved when the machine’s allowedToolsCeiling allows it.
Ask for a change calls ask_for_change(card, comment, anchor): it rejects the proposal page with the comment as
its note and reuses the outputs’ reject-and-revise path (into the live session, a resumed one, or a fresh run in the
card’s worktree). The revise prompt carries the current proposal and asks for proposal-vN.html and a new
propose_project. A pinned part is kept in run_outputs.review_anchor. private.study_max_versions() stops at five.
Accept (accept_project_proposal, the study card’s owner, once the study has finished its turn) and Dismiss
(dismiss_project_proposal) are each one statement: if any part fails nothing is left behind. Accept also renders the
project’s plan (project_proposals.plan), which the board proposes to the team’s repository as a plan proposal;
until it merges, runs get it through boardProjectPlan.
Pages in the board
A page is one self-contained .html file, at most 5 MB. The machine refuses a page that loads a script, stylesheet,
image, font, frame or @import from a URL or a neighbouring file, and uploads an accepted one as it is to the private
outputs bucket under <org>/<card>/<run>/<output>/preview.html.
The board shows it in a frame that can’t read the session or call out (apps/board/src/lib/page-frame.ts):
- no cookies or storage, no access to the board, no fetch, XHR, WebSocket, images or beacons from anywhere, no forms, popups or top navigation;
- a script that sends its own frame elsewhere is refused before any request;
- WebRTC, which no browser lets a policy block, is taken from the page’s scripts, and a frame the page adds inside itself is removed before it loads, so a page can’t embed frames;
- links open in a new tab (http, https and mailto);
#sectionlinks scroll within the page.
Selecting text for Ask for a change goes through the page’s guard script, which runs before the page’s own: it posts the selection to the board signed with the frame’s nonce, and only after the person’s own click, key or touch. The board takes the text and nothing else.
A page with dark styles (prefers-color-scheme, a color-scheme meta, or a .dark class or [data-theme] selector)
has its prefers-color-scheme queries answered with the board’s theme, and its root gets a dark or light class and
data-theme.
Where it lives
| Piece | Files |
|---|---|
| The Study recipe and its prompt | db/migrations/20261110075452_study_recipe.sql |
| Study it first | apps/board/src/lib/start-work.ts, apps/board/src/components/start-work/StartWorkDialog.tsx |
| The proposal view, versions, Ask for a change, Accept and Dismiss | apps/board/src/components/card/ProposalView.tsx, apps/board/src/lib/project-proposal.ts |
| Accept, Dismiss and the plan | migrations 20261110172944_accept_project_proposal.sql, 20261110174607_study_plan.sql |
| The plan on the project page | apps/board/src/components/project/ProjectPlan.tsx, ProjectRail.tsx |
| The page frame | apps/board/public/page-frame.html, fed by apps/board/src/lib/page-frame.ts |
| Tests | apps/board/e2e/proposal.spec.ts, start-work.spec.ts; apps/server/test/rls/project-proposals.test.ts, accept-project-proposal.test.ts, study-plan.test.ts |
