@lovek4d/kickflip 0.7.0 → 0.7.2

package/board/headless.mjs

@@ -1,8 +1,8 @@
-var F=Object.defineProperty;var d=(t,e)=>F(t,"name",{value:e,configurable:!0});import Y from"node:os";import S from"node:path";import{fileURLToPath as E}from"node:url";import{launchAgent as H}from"./agents.mjs";import{processStarts as L,ps as G}from"../hub/live.mjs";import{boardAt as K}from"../hub/boards.mjs";import{readHubRules as U}from"../hub/rules.mjs";import{builderRepo as _}from"./worktree.mjs";import{BoardError as V,briefFacts as Q,readBoardRules as X,recordSession as z}from"./store.mjs";import{HELPER as J,plans as Z,VISUAL as ee}from"./domain.mjs";const te=E(new URL("./bin/board.mjs",import.meta.url)),g=d(t=>`node ${te} --site ${t}`,"cli"),P=d(t=>`git -c core.commentChar=';' rebase ${t}`,"rebase"),oe="a draft .md of your own outside the board's data folder (such as in /tmp)",re=d((t,e,s)=>`\`${t} item notes ${e} --heading "${s}" --file <draft.md>\``,"notesCommand"),R=d((t,e="Rules from the hub and this board:")=>t.length?[e,...t.map(s=>`- ${s}`),""]:[],"ruleLines"),T=d(t=>t.length?["Related cards: read their notes for context; don't build their scope.",...t.map(e=>`- ${e.ref} "${e.title}" (${e.relation}, ${e.lane}): ${e.notes?`notes ${e.notes}`:"no notes"}, thread ${e.thread}`),""]:[],"linkLines"),x=d(t=>`The card's thread, which holds the owner's messages (who: love): ${t}. Read it live.`,"threadLine"),W=d(({route:t,key:e,worktree:s,base:h})=>[`- With no unverified calls, done finishes the card itself: it rebases onto ${h}, reruns the full test suite, fast-forwards ${h} and closes the card (on a board with pull requests it pushes the branch and opens a draft PR instead; with Auto-merge off it stops before the fast-forward, and the card waits for the owner's Merge).`,`- On a conflict it undoes its rebase and names the files: run \`${P(h)}\` in ${s}, resolve each conflict keeping both sides' intent, continue with \`git -c core.commentChar=';' rebase --continue\`, rerun the tests, and run done again.`,"- On failing tests, fix them, commit, and run done again.","- While another card is landing, done waits its turn and then lands; leave it running.","- Once a reviewer has the card's PR link, done refuses without `--updated \"<what changed>\"`, which goes in that link's Slack thread, or `--updated none` for a change only to comments, names, docs or tests.",`- Finishing never goes to the orchestrator. If done refuses for a reason you can't fix, record it with \`${g(t)} builder call ${e} "<why>"\` and run done again: with the call it hands the card back.`],"finishSteps"),D=d(({route:t,key:e})=>`\`${g(t)} builder done ${e} --text "<what you checked>"\``,"finishCommand"),ne=d((t,e)=>[`5. To run a separate part of the work in parallel, ask the board for a helper: \`${t} agent launch ${e} --name <short-name> --task "<the whole task, with the files and what to hand back>"\`, adding --writes when it changes code or runs tests (it gets its own worktree off your branch, and waits for a free implementer slot). Then \`${t} agent wait ${e} --name <short-name>\`, which prints its hand-back; it returns within 10 minutes, so run it again while it says still running, and do the task yourself if it says the helper exited. Merge a writing helper's work with \`${t} agent merge ${e} --name <short-name>\` before you test and finish.`],"helperSteps");function se({route:t,key:e,ref:s,title:h,notes:r,thread:l,worktree:a,base:u,rules:c=[],links:p=[]}){const o=g(t);return[`You are the headless builder for card ${s} (${e}, "${h}") on the kickflip board /${t}. The board launched you; nobody watches this session, so never wait on a person. Work only in ${a}. Never restart the hub or a board server, and never push.`,"",`1. Run \`${o} builder start ${e} --kind build\`. If it refuses, stop.`,`2. Report progress with \`${o} builder progress ${e} --phase reading|building|testing|checking|landing "<plain, 80 characters or fewer>"\`, at least every 10 minutes. The board adds the phase word; don't start the text with it. The phases:`,"   - reading: the notes and the code, until the first test is written.","   - building: the tests and the code, the ADR and docs, and the commit.","   - testing: the full suite run before you finish.","   - checking: your own review of the diff before you hand back; the Orchestrator's review of your calls continues on the same 4th bar.","   - landing: set by the finish step itself; you never report it.",`3. Decide, record the call (step 4) and carry on: the orchestrator reviews your calls after the build. Ask it only when you are blocked, meaning every way forward would likely be thrown away: the spec contradicts itself or the code, a rule needs the owner's go before code is written, or the answer is a fact only the orchestrator has. Then run \`${o} builder ask ${e} "<question>"\`, do any work the answer can't change, and wait with \`${o} builder asks ${e} --wait\`, which returns within 10 minutes, so run it again while it says still waiting. If no answer comes in 30 minutes, record the question as a call, "Question: <question>", and hand back.`,`4. Record each judgment call the notes leave open with \`${o} builder call ${e} "<call>"\` instead of guessing silently or asking. A problem you find outside your card is a call "Found: <what>" for the orchestrator to file at review; ask about it at once only when it stalls other cards' builds or lands.`,...ne(o,e),"",r?`Spec: the card's notes, ${r}, all sections, where later sections override earlier ones.`:"The card has no notes file: build from its title, and record what you had to decide as calls.",`${x(l)} Read it with the notes: a message of the owner's is an instruction, but where it contradicts the notes, the notes win; that contradiction counts as blocked (step 3), so ask with \`${o} builder ask ${e} "<question>"\` and wait as step 3 says. Read the thread again in checking, before you finish, for anything the owner wrote during the build.`,"",...T(p),...R(c),"Write tests first, and run the full suite once, in the foreground, at the end. Where the repo keeps ADRs, write one named with a timestamp: docs/adr/YYYY-MM-DD-HHMM-<slug>.md.",`Commit with \`git -c core.commentChar=';' commit -F <file>\`, the subject "${s}: <what the card now does>".`,"",`To finish, run ${D({route:t,key:e})}.`,"- If you recorded a judgment call, it hands the card back for the orchestrator to verify your calls; stop there: the orchestrator's verification finishes the card.",...W({route:t,key:e,worktree:a,base:u}),"","Never push."].join(`
-`)}d(se,"builderBrief");function ae({route:t,key:e,ref:s,title:h,thread:r,worktree:l,base:a,answers:u=[]}){const c=g(t);return[`You are the headless lander for card ${s} (${e}, "${h}") on the kickflip board /${t}. Its build is done and the orchestrator verified its judgment calls; it waits only to land. Nobody watches this session, so never wait on a person. Work only in ${l}, never restart the hub or a board server, and never push.`,"",`1. Run \`${c} builder start ${e} --kind build --label Lander --phase landing --progress "taking up the verified build"\`. If it refuses, stop.`,`2. Report progress with \`${c} builder progress ${e} --phase landing "<plain, 80 characters or fewer>"\`. The board adds the phase word; don't start the text with it.`,...u.length?["3. The owner answered the builder's deferred asks. Where an answer changes the build, change it, with its tests, and commit:",...u.map(p=>`- ${p.ask} "${p.question}": ${p.answer}`)]:[],"",x(r),"",`To finish, run ${D({route:t,key:e})}.`,...W({route:t,key:e,worktree:l,base:a}),"","Never push."].join(`
-`)}d(ae,"landerBrief");function ie({route:t,key:e,ref:s,title:h,thread:r,worktree:l,base:a,pr:u}){const c=g(t);return[`You are the headless rebase run for card ${s} (${e}, "${h}") on the kickflip board /${t}. Its PR #${u} conflicts with ${a}; rebase its branch onto ${a} so the PR is clean again. Nobody watches this session, so never wait on a person. Work only in ${l}, never restart the hub or a board server, and never push.`,"",`1. Run \`${c} builder start ${e} --kind build --label Rebase --phase building --progress "Rebase run started \xB7 fetching ${a}"\`. If it refuses, stop.`,`2. Run \`git fetch origin\`, then \`${P(`origin/${a}`)}\`. Resolve each conflict keeping both sides' intent, \`git add\` it and continue with \`git -c core.commentChar=';' rebase --continue\`. Report each step with \`${c} builder progress ${e} --phase building "<line>"\`, the board adds the phase word, in these words: "Rebasing onto ${a} \xB7 resolving <n> files", then "Rebasing onto ${a} \xB7 suite running".`,"3. Run the full test suite once, in the foreground. Fix what the rebase broke, and commit each fix with `git -c core.commentChar=';' commit -F <file>`. A push with commits of its own is no longer rebase-only, so a merge after an approval won't count it as trivial.",`4. If a conflict or a failing test is past what you can resolve with confidence, run \`git -c core.commentChar=';' rebase --abort\` if a rebase is under way, record it with \`${c} builder call ${e} "Rebase failed in <the files or tests> \xB7 <why>"\`, and run the finish step: with the call it hands the card to the orchestrator.`,"",x(r),"",`To finish, run ${D({route:t,key:e})}, the text saying what you resolved. It reruns the suite and pushes the branch to PR #${u} with --force-with-lease; the PR stays as it is.`,"- If it refuses because someone pushed to the branch since your fetch, fetch and rebase again (step 2), then run done again.","- On failing tests, fix them, commit, and run done again.","","Never push."].join(`
-`)}d(ie,"rebaseBrief");function he({route:t,key:e,ref:s,title:h,notes:r,thread:l,kind:a,repo:u,rules:c=[],links:p=[],text:o,files:i=[],question:n,note:f,choice:m}){const w=g(t),b=a==="grill";return[`You are the headless ${b?"grill":"prototype"} planner for card ${s} (${e}, "${h}") on the kickflip board /${t}. The board launched you; nobody watches this session, so never wait on a person: the owner answers on the board, and a later planner or builder picks up from their answers. Read and run in ${u}; write no output code ${b?"there":`in ${u} itself`}, never restart the hub or a board server, and never push.`,"",`1. Run \`${w} builder start ${e} --kind ${a}\`. If it refuses, stop.`,`2. Gather the context yourself: ${r?`the card's notes, ${r}, all sections, where later sections override earlier ones; `:"the card has no notes file yet; "}its thread, ${l}, the repo's docs/adr and CONTEXT.md, and the cards its notes and thread link.`,`3. Report progress with \`${w} builder progress ${e} "<plain, 80 characters or fewer>"\` at least every 10 minutes.`,b?`4. Find every decision the card leaves open: read the code it touches and answer what the code answers yourself. Post each decision left as a question for the owner with \`${w} question add --file <json>\` on topic item:${e}, one per decision, your recommendation first. Once you finish, the orchestrator screens them before the owner sees them, settling the ones the board already answers and passing the owner the rest. Invoke the grilling skill with the Skill tool and run it as one round: its questions go to the board with question add, never into the chat, and you never wait for an answer; after the round, finish. (With no Skill tool, follow this step as written.) When the code shows the card has separable parts, each a build of its own, propose splitting it into a wave of smaller cards as one question ahead of the prototype question: its options "Split as proposed" and "Keep as one card", your recommendation first, its context listing each proposed card with its title, its scope and the files it touches, and which cards build side by side and which after another; write the same breakdown in your notes section. On Split the orchestrator files the cards when the card stages; never file them yourself. End every grill with one more question, "Prototype round first?", whose options are yes and no, with "prototype_gate": true in its \`question add --file\` entry: once the owner has answered every question the board moves the card to prototyping on yes, or to staging on no, so nothing else moves it. Recommend yes when the card changes the hub's or a board's UI, no otherwise. Ask it even when it is your only question.`:`4. Build the round in situ, in the board's base prototype worktree: run \`${w} prototype base\`, which makes it or moves it to main and prints its path, whether its build script is there and the listener a page loads. When the build script is missing, write one there that serves the app and prints "port <n>" (board/build-script.mjs). Add one page to the worktree, at a path no other round uses, built from the repo's real components, helpers and scripts fed mock data, fully interactive; it reads the take from ?variant= and the state from ?state=, and loads the listener so \`KickflipPrototype.on((take, state) => \u2026)\` re-renders it in place when the viewer switches. Record it with \`${w} prototype add <topic> --card ${e} --served <path> --take <K>:<label> \u2026 --state <key>:<label> \u2026\`, one take per option and one state for each state that matters to the question, then post one question whose url opens prototype-<topic>.html with \`${w} question add --file <json>\` on topic item:${e}, never asking in the chat. Only a repo whose app can't be served as a web page keeps take files: \`${w} prototype add <topic> --card ${e} --take <K>:<label> \u2026\`, one take file per option built from the board's real components fed fake data. Invoke the prototype skill with the Skill tool for this step. (With no Skill tool, follow this step as written.)`,...o?[`   The owner asked for this ${b?"grill":"prototype"}, writing: "${o}"`]:[],...i.length?[`   The owner attached: ${i.map(I=>I.path).join(", ")}.`]:[],...n?[`   The owner asked for prototypes of question ${n}${f?`, noting "${f}"`:""}${m?`, leaning to option ${m}`:""}: draw that question's next round, its question naming round_of ${n}.`]:[],`5. Record what you learned in the card's notes, naming each answered question's id: write it in ${oe}, then run ${re(w,e,`${b?"Grill":"Prototype"} (<MM/DD>)`)}, which appends it as a section. The notes file is read-only; never write into it. Anything you leave open becomes a question with question add, never only a line in the notes, so the card can't go ready past it.`,...b?[`6. Where the owner asked for prototypes, or a rule here wants a UI prototype first, end the card \`${w} item set ${e} --phase prototyping\` instead and skip the prototype question. Otherwise the prototype question is what moves the card on: never set it ready yourself, and never leave a Next that asks the owner to mark it ready.`]:[],"",...T(p),...R(c,"Rules from the hub and this board, written for the orchestrator: where one tells you to push, land, restart the hub or a board server, or do the orchestrator's work, it isn't yours; you never push or restart:"),`To finish, run \`${w} builder done ${e} --text "<what you asked>"\`.`,"","Never push."].join(`
-`)}d(he,"plannerBrief");function de({route:t,key:e,ref:s,title:h,notes:r,thread:l,repo:a,agent:u,rules:c=[],links:p=[],text:o,files:i=[]}){const n=g(t);return[`You are the headless visual agent for card ${s} (${e}, "${h}") on the kickflip board /${t}. The owner asked, in the card's thread, for a visual: one HTML page that answers in a visual way, such as a diagram, a flow or a comparison. It is not a prototype or a grill: no question, no takes. The board launched you; nobody watches this session, so never wait on a person. Read and run in ${a}; write no code there, never restart the hub or a board server, and never push.`,"",`1. Run \`${n} builder start ${e} --kind visual --agent ${u}\`. If it refuses, stop.`,`2. Gather what the page needs: ${r?`the card's notes, ${r}; `:""}its thread, ${l}, and the code or docs it is about.`,o?`   The owner wrote: "${o}"`:"   The owner typed nothing: draw what the thread was last discussing.",...i.length?[`   The owner attached: ${i.map(f=>f.path).join(", ")}.`]:[],"3. Write one HTML file outside the repo, such as in a temporary folder. Keep its own CSS and script inline; it may load a library such as Mermaid or D3 from a CDN. Make it read well at phone width (390px) and on a desktop, in the dark and the light theme (prefers-color-scheme).",`4. Place it with \`${n} visual add ${e} --file <page.html> --title "<what it shows>"\`, which copies it to the board and links it in the thread.`,"","Write nothing else: no notes, questions, card state, Next or progress lines.","",...T(p),...R(c,"Rules from the hub and this board, written for the orchestrator: where one tells you to push, land, restart the hub or a board server, or do the orchestrator's work, it isn't yours; you never push or restart:"),`To finish, run \`${n} builder done ${e} --agent ${u}\`.`,"","Never push."].join(`
-`)}d(de,"visualBrief");function le({route:t,key:e,ref:s,title:h,notes:r,thread:l,agent:a,task:u,writes:c,cwd:p,rules:o=[],links:i=[]}){const n=g(t);return[`You are the headless helper ${a} on card ${s} (${e}, "${h}") on the kickflip board /${t}. Another agent working on the card asked the board for you to do one task beside it, and waits on your hand-back. Nobody watches this session, so never wait on a person. Never restart the hub or a board server, and never push.`,c?`Work only in ${p}, your own worktree, branched from the card's: commit your work there with \`git -c core.commentChar=';' commit -F <file>\`, the subject "${s}: <what it does>". The card's builder merges your branch, so leave nothing uncommitted.`:`Read and run in ${p}; change no files there and commit nothing.`,"","The task:",u,"",`1. Run \`${n} builder start ${e} --kind helper --agent ${a}\`. If it refuses, stop.`,`2. Report progress with \`${n} builder progress ${e} --agent ${a} --phase reading|building|testing|checking "<plain, 80 characters or fewer>"\` at least every 10 minutes; the board adds your name and the phase word.`,"3. Do only the task. Don't ask the orchestrator or the owner, record no judgment calls and post no questions: put any decision you had to make in your hand-back.",r?`   The card's notes, for context: ${r}.`:"",`   ${x(l)}`,"",...T(i),...R(o,"Rules from the hub and this board, written for the orchestrator: where one tells you to push, land, restart the hub or a board server, or do the orchestrator's work, it isn't yours; you never push or restart:"),`To finish, run \`${n} builder done ${e} --agent ${a} --text "<your hand-back: what you did or found, ${c?"what you committed, ":""}and any decision you made>"\`.`,"","Never push."].filter((f,m,w)=>f!==""||w[m-1]!=="").join(`
-`)}d(le,"helperBrief");const ce=6e4;function ue(t,{starts:e=L}={}){const s=t.filter(r=>r.pid&&r.at).map(r=>r.pid),h=s.length&&e(s)||new Map;return t.filter(r=>{const l=h.get(r.pid);return l!==void 0&&l<=Date.parse(r.at)&&l>=Date.parse(r.at)-ce})}d(ue,"launchedAgents");function xe(t,{starts:e=L,kill:s=d((r,l)=>process.kill(-r,l),"kill"),killAfter:h=5e3}={}){const r=ue(t,{starts:e});for(const{pid:l}of r){try{s(l,"SIGTERM")}catch{continue}setTimeout(()=>{try{s(l,"SIGKILL")}catch{}},h).unref()}return r.length}d(xe,"stopAgents");async function Ie(t,{grace:e=5e3}={}){const s=G(["-A","-o","pid=,ppid=,pgid=,args="]);if(s===null)throw new V("ps gave no answer, so nothing was stopped; run it again");const h=s.split(`
-`).map(o=>/^\s*(\d+)\s+(\d+)\s+(\d+)\s+(.*)$/.exec(o)).filter(Boolean).map(([,o,i,n,f])=>({pid:Number(o),ppid:Number(i),pgid:Number(n),args:f})),r=new Set(h.filter(o=>t.includes(o.pgid)).map(o=>o.pid));for(let o=!0;o;){o=!1;for(const i of h)!r.has(i.pid)&&r.has(i.ppid)&&(r.add(i.pid),o=!0)}const l=h.find(o=>o.pid===process.pid)?.pgid,a=h.filter(o=>r.has(o.pid)&&o.pgid>1&&o.pgid!==l),u=[...new Set(a.map(o=>o.pgid))],c=d(o=>{for(const i of u)try{process.kill(-i,o)}catch{}},"signal");c("SIGTERM");const p=Date.now()+e;for(;a.some(o=>j(o.pid))&&Date.now()<p;)await new Promise(o=>setTimeout(o,50));return a.some(o=>j(o.pid))&&c("SIGKILL"),a.map(({pid:o,args:i})=>({pid:o,args:i}))}d(Ie,"stopRuns");const j=d(t=>{try{return process.kill(t,0),!0}catch(e){return e.code==="EPERM"}},"pidAlive");async function qe(t,e,{launch:s,handBack:h,alive:r=j,held:l=d(()=>!1,"held"),stopped:a=new Set,limitedUntil:u=d(()=>null,"limitedUntil"),atLimit:c=d(async()=>{},"atLimit"),now:p=Date.now()}){const o={};for(const[i,n]of Object.entries(t)){if(!e.has(i))continue;if(a.has(i)){o[i]={...n,handedBack:!0};continue}if(n.pid!==null&&r(n.pid)||n.handedBack){o[i]=n;continue}const f={key:i,...n.kind?{kind:n.kind}:{},...n.model?{model:n.model}:{}},m=n.pid!==null?u(n):null;if(m){await c(f,m),o[i]={...n,pid:null,until:m};continue}if(l(n.kind??"claude")||n.until&&p<Date.parse(n.until)){o[i]=n;continue}if(n.pid!==null&&n.relaunched){await h(f),o[i]={...n,handedBack:!0};continue}const{key:w,...b}=f;o[i]={...b,...await s(f),relaunched:n.pid!==null||!!n.relaunched}}return o}d(qe,"reviveBuilders");const pe=d((t,e)=>S.join(Y.homedir(),".claude","kickflip","logs",`${e}-${t}-${new Date().toISOString().replace(/[:.]/g,"-")}.log`),"logFile");async function Se(t,{key:e,kind:s="claude",model:h,agent:r="main",text:l,files:a,question:u,note:c,choice:p,task:o,writes:i,worktree:n},{lander:f=!1}={}){const m=await Q(t,e),w=K(t)?.route??S.basename(t),b=[...U(),...await X(t)].map(O=>O.text),{base:I,repo:q}=_(t),y=Z({kind:s}),v=s===J,A=!y&&!v&&!f&&m.rebasePR!==null,N=s===ee,B=y?q:v?n??m.worktree??q:m.worktree,$={...m,route:w,base:I,repo:q,rules:b,kind:s,agent:r,text:l,files:a,question:u,note:c,choice:p,task:o,writes:i,cwd:B,pr:m.rebasePR},C=N?"Visual agent":v?`Helper ${r}`:y?"Planner":f?"Lander":A?"Rebase run":"Builder",M=N?de($):v?le($):y?he($):f?ae($):A?ie($):se($),k=await H({kind:y||v?"claude":s,model:h,cwd:B,site:t,prompt:M,log:pe(e.split("/")[1],C.split(" ")[0].toLowerCase())});return await z(t,e,k.sessionId,k.pid,r,S.basename(k.log)),k}d(Se,"launchBuilder");export{te as BOARD_CLI,se as builderBrief,le as helperBrief,ae as landerBrief,Se as launchBuilder,ue as launchedAgents,j as pidAlive,he as plannerBrief,ie as rebaseBrief,qe as reviveBuilders,xe as stopAgents,Ie as stopRuns,de as visualBrief};
+var z=Object.defineProperty;var l=(t,e)=>z(t,"name",{value:e,configurable:!0});import Q from"node:os";import{BRIEF_LINE_LIMIT as X}from"./hub-lines.mjs";import T from"node:path";import{fileURLToPath as J}from"node:url";import{launchAgent as P}from"./agents.mjs";import{processStarts as W,ps as Z}from"../hub/live.mjs";import{boardAt as C}from"../hub/boards.mjs";import{readHubRules as ee}from"../hub/rules.mjs";import{builderRepo as M}from"./worktree.mjs";import{appendStatus as te,BoardError as oe,briefFacts as L,readBoardRules as re,recordedSession as ne,recordSession as O}from"./store.mjs";import{HELPER as se,plans as ae,VISUAL as ie}from"./domain.mjs";const he=J(new URL("./bin/board.mjs",import.meta.url)),$=l(t=>`node ${he} --site ${t}`,"cli"),E=l(t=>`git -c core.commentChar=';' rebase ${t}`,"rebase"),de="a draft .md of your own outside the board's data folder (such as in /tmp)",le=l((t,e,r)=>`\`${t} item notes ${e} --heading "${r}" --file <draft.md>\``,"notesCommand"),I=l((t,e="Rules from the hub and this board:")=>t.length?[e,...t.map(r=>`- ${r}`),""]:[],"ruleLines"),q=l(t=>t.length?["Related cards: read their notes for context; don't build their scope.",...t.map(e=>`- ${e.ref} "${e.title}" (${e.relation}, ${e.lane}): ${e.notes?`notes ${e.notes}`:"no notes"}, thread ${e.thread}`),""]:[],"linkLines"),S=l(t=>`The card's thread, which holds the owner's messages (who: love): ${t}. Read it live.`,"threadLine"),F=l(({route:t,key:e,worktree:r,base:h})=>[`- With no unverified calls, done finishes the card itself: it rebases onto ${h}, reruns the full test suite, fast-forwards ${h} and closes the card (on a board with pull requests it pushes the branch and opens a draft PR instead; with Auto-merge off it stops before the fast-forward, and the card waits for the owner's Merge).`,`- On a conflict it undoes its rebase and names the files: run \`${E(h)}\` in ${r}, resolve each conflict keeping both sides' intent, continue with \`git -c core.commentChar=';' rebase --continue\`, rerun the tests, and run done again.`,"- On failing tests, fix them, commit, and run done again.","- While another card is landing, done waits its turn and then lands; leave it running.","- Once a reviewer has the card's PR link, done refuses without `--updated \"<what changed>\"`, which goes in that link's Slack thread, or `--updated none` for a change only to comments, names, docs or tests.",`- Finishing never goes to the orchestrator. If done refuses for a reason you can't fix, record it with \`${$(t)} builder call ${e} "<why>"\` and run done again: with the call it hands the card back.`],"finishSteps"),j=l(({route:t,key:e})=>`\`${$(t)} builder done ${e} --text "<what you checked>"\``,"finishCommand"),ce=l((t,e)=>[`5. To run a separate part of the work in parallel, ask the board for a helper: \`${t} agent launch ${e} --name <short-name> --task "<the whole task, with the files and what to hand back>"\`, adding --writes when it changes code or runs tests (it gets its own worktree off your branch, and waits for a free implementer slot). Then \`${t} agent wait ${e} --name <short-name>\`, which prints its hand-back; it returns within 10 minutes, so run it again while it says still running, and do the task yourself if it says the helper exited. Merge a writing helper's work with \`${t} agent merge ${e} --name <short-name>\` before you test and finish.`],"helperSteps");function ue({route:t,key:e,ref:r,title:h,notes:n,thread:d,worktree:a,base:u,rules:p=[],links:c=[]}){const o=$(t);return[`You are the headless builder for card ${r} (${e}, "${h}") on the kickflip board /${t}. The board launched you; nobody watches this session, so never wait on a person. Work only in ${a}. Never restart the hub or a board server, and never push.`,"",`1. Run \`${o} builder start ${e} --kind build\`. If it refuses, stop.`,`2. Report progress with \`${o} builder progress ${e} --phase reading|building|testing|checking|landing "<plain, 80 characters or fewer>"\`, at least every 10 minutes. The board adds the phase word; don't start the text with it. The phases:`,"   - reading: the notes and the code, until the first test is written.","   - building: the tests and the code, the ADR and docs, and the commit.","   - testing: the full suite run before you finish.","   - checking: your own review of the diff before you hand back; the Orchestrator's review of your calls continues on the same 4th bar.","   - landing: set by the finish step itself; you never report it.",`3. Decide, record the call (step 4) and carry on: the orchestrator reviews your calls after the build. Ask it only when you are blocked, meaning every way forward would likely be thrown away: the spec contradicts itself or the code, a rule needs the owner's go before code is written, or the answer is a fact only the orchestrator has. Then run \`${o} builder ask ${e} "<question>"\`, do any work the answer can't change, and wait with \`${o} builder asks ${e} --wait\`, which returns within 10 minutes, so run it again while it says still waiting. If no answer comes in 30 minutes, record the question as a call, "Question: <question>", and hand back.`,`4. Record each judgment call the notes leave open with \`${o} builder call ${e} "<call>"\` instead of guessing silently or asking. A problem you find outside your card is a call "Found: <what>" for the orchestrator to file at review; ask about it at once only when it stalls other cards' builds or lands.`,...ce(o,e),"",n?`Spec: the card's notes, ${n}, all sections, where later sections override earlier ones.`:"The card has no notes file: build from its title, and record what you had to decide as calls.",`${S(d)} Read it with the notes: a message of the owner's is an instruction, but where it contradicts the notes, the notes win; that contradiction counts as blocked (step 3), so ask with \`${o} builder ask ${e} "<question>"\` and wait as step 3 says. Read the thread again in checking, before you finish, for anything the owner wrote during the build.`,"",...q(c),...I(p),"Write tests first, and run the full suite once, in the foreground, at the end. Where the repo keeps ADRs, write one named with a timestamp: docs/adr/YYYY-MM-DD-HHMM-<slug>.md.",`Commit with \`git -c core.commentChar=';' commit -F <file>\`, the subject "${r}: <what the card now does>".`,"",`To finish, run ${j({route:t,key:e})}.`,"- If you recorded a judgment call, it hands the card back for the orchestrator to verify your calls; stop there: the orchestrator's verification finishes the card.",...F({route:t,key:e,worktree:a,base:u}),"","Never push."].join(`
+`)}l(ue,"builderBrief");function Y({route:t,key:e,ref:r,title:h,thread:n,worktree:d,base:a,answers:u=[],resumed:p=!1,why:c}){const o=$(t);return[p?`The board resumes you, the builder of card ${r} (${e}, "${h}") on the kickflip board /${t}, to land your build: ${c??"the orchestrator verified your judgment calls"}, and it waits only to land. Nobody watches this session, so never wait on a person. Work only in ${d}, never restart the hub or a board server, and never push.`:`You are the headless lander for card ${r} (${e}, "${h}") on the kickflip board /${t}. Its build is done and the orchestrator verified its judgment calls; it waits only to land. Nobody watches this session, so never wait on a person. Work only in ${d}, never restart the hub or a board server, and never push.`,"",`1. Run \`${o} builder start ${e} --kind build --label Lander --phase landing --progress "taking up the verified build"\`. If it refuses, stop.`,`2. Report progress with \`${o} builder progress ${e} --phase landing "<plain, 80 characters or fewer>"\`. The board adds the phase word; don't start the text with it.`,...u.length?["3. The owner answered the builder's deferred asks. Where an answer changes the build, change it, with its tests, and commit:",...u.map(i=>`- ${i.ask} "${i.question}": ${i.answer}`)]:[],"",S(n),"",`To finish, run ${j({route:t,key:e})}.`,...F({route:t,key:e,worktree:d,base:a}),"","Never push."].join(`
+`)}l(Y,"landerBrief");function _({route:t,key:e,ref:r,title:h,thread:n,worktree:d,base:a,pr:u,resumed:p=!1}){const c=$(t);return[...p?[`The board resumes you, the builder of card ${r}, for this run: the lines below are your brief for it.`]:[],`You are the headless rebase run for card ${r} (${e}, "${h}") on the kickflip board /${t}. Its PR #${u} conflicts with ${a}; rebase its branch onto ${a} so the PR is clean again. Nobody watches this session, so never wait on a person. Work only in ${d}, never restart the hub or a board server, and never push.`,"",`1. Run \`${c} builder start ${e} --kind build --label Rebase --phase building --progress "Rebase run started \xB7 fetching ${a}"\`. If it refuses, stop.`,`2. Run \`git fetch origin\`, then \`${E(`origin/${a}`)}\`. Resolve each conflict keeping both sides' intent, \`git add\` it and continue with \`git -c core.commentChar=';' rebase --continue\`. Report each step with \`${c} builder progress ${e} --phase building "<line>"\`, the board adds the phase word, in these words: "Rebasing onto ${a} \xB7 resolving <n> files", then "Rebasing onto ${a} \xB7 suite running".`,"3. Run the full test suite once, in the foreground. Fix what the rebase broke, and commit each fix with `git -c core.commentChar=';' commit -F <file>`. A push with commits of its own is no longer rebase-only, so a merge after an approval won't count it as trivial.",`4. If a conflict or a failing test is past what you can resolve with confidence, run \`git -c core.commentChar=';' rebase --abort\` if a rebase is under way, record it with \`${c} builder call ${e} "Rebase failed in <the files or tests> \xB7 <why>"\`, and run the finish step: with the call it hands the card to the orchestrator.`,"",S(n),"",`To finish, run ${j({route:t,key:e})}, the text saying what you resolved. It reruns the suite and pushes the branch to PR #${u} with --force-with-lease; the PR stays as it is.`,"- If it refuses because someone pushed to the branch since your fetch, fetch and rebase again (step 2), then run done again.","- On failing tests, fix them, commit, and run done again.","","Never push."].join(`
+`)}l(_,"rebaseBrief");function pe({route:t,key:e,ref:r,title:h,notes:n,thread:d,kind:a,repo:u,rules:p=[],links:c=[],text:o,files:i=[],question:s,note:f,choice:w,ticketQuestion:b=!1}){const m=$(t),g=a==="grill";return[`You are the headless ${g?"grill":"prototype"} planner for card ${r} (${e}, "${h}") on the kickflip board /${t}. The board launched you; nobody watches this session, so never wait on a person: the owner answers on the board, and a later planner or builder picks up from their answers. Read and run in ${u}; write no output code ${g?"there":`in ${u} itself`}, never restart the hub or a board server, and never push.`,"",`1. Run \`${m} builder start ${e} --kind ${a}\`. If it refuses, stop.`,`2. Gather the context yourself: ${n?`the card's notes, ${n}, all sections, where later sections override earlier ones; `:"the card has no notes file yet; "}its thread, ${d}, the repo's docs/adr and CONTEXT.md, and the cards its notes and thread link.`,`3. Report progress with \`${m} builder progress ${e} "<plain, 80 characters or fewer>"\` at least every 10 minutes.`,g?`4. Find every decision the card leaves open: read the code it touches and answer what the code answers yourself. Post each decision left as a question for the owner with \`${m} question add --file <json>\` on topic item:${e}, one per decision, your recommendation first. Once you finish, the orchestrator screens them before the owner sees them, settling the ones the board already answers and passing the owner the rest. Invoke the grilling skill with the Skill tool and run it as one round: its questions go to the board with question add, never into the chat, and you never wait for an answer; after the round, finish. (With no Skill tool, follow this step as written.) When the code shows the card has separable parts, each a build of its own, propose splitting it into a wave of smaller cards as one question ahead of the prototype question: its options "Split as proposed" and "Keep as one card", your recommendation first. Slice it as ~/.claude/skills/to-tickets/SKILL.md step 3, "Draft vertical slices", says (read that step; you can't invoke the skill, and skip its quiz and publish steps). The first card is the thinnest end-to-end path. The question's context lists each proposed card with its title, its scope, the files it touches and the earlier proposed cards it waits on, or none: a card waits on an earlier one only when it builds on that card or shares its seam (the same function, component, CLI command or doc paragraph); sharing only a file waits on nothing. Write the same breakdown in your notes section. On Split the orchestrator files the cards when the card stages; never file them yourself.`+(b?' This card is a task, with no ticket yet: just before the prototype question, ask "Create a ticket for this task?", whose options are yes and no, with "ticket_gate": true in its `question add --file` entry; the board makes the ticket from the card\'s title and notes the moment the owner answers yes. Recommend yes when the task lands code, no when it lands nothing (a publish, a setting, a one-off run).':"")+' End every grill with one more question, "Prototype round first?", whose options are yes and no, with "prototype_gate": true in its `question add --file` entry: once the owner has answered every question the board moves the card to prototyping on yes, or to staging on no, so nothing else moves it. Recommend yes when the card changes the hub\'s or a board\'s UI, no otherwise. Ask it even when it is your only question.':`4. Invoke the prototype skill with the Skill tool and build the round as take files, one per option: record them with \`${m} prototype add <topic> --card ${e} --take <K>:<label> \u2026\`, write the take files it prints, built from the repo's existing components, helpers and scripts fed mock data (the prototype template loads the board's scripts, so a take reuses the board's components; a hub-page take reuses them by path or copy), each take showing the states it needs inside itself, then post one question whose url opens prototype-<topic>.html with \`${m} question add --file <json>\` on topic item:${e}, never asking in the chat. Build in situ only where one of the board's rules asks for it: then, run \`${m} prototype base\`, which makes it or moves it to main and prints its path, whether its build script is there and the listener a page loads. When the build script is missing, write one there that serves the app and prints "port <n>" (board/build-script.mjs). Add one page to the worktree, at a path no other round uses, built from the repo's real components, helpers and scripts fed mock data, fully interactive; it reads the take from ?variant= and the state from ?state=, and loads the listener so \`KickflipPrototype.on((take, state) => \u2026)\` re-renders it in place when the viewer switches. Record it with \`${m} prototype add <topic> --card ${e} --served <path> --take <K>:<label> \u2026 --state <key>:<label> \u2026\`, one take per option and one state for each state that matters to the question, then post one question whose url opens prototype-<topic>.html with \`${m} question add --file <json>\` on topic item:${e}, never asking in the chat. (With no Skill tool, follow this step as written.)`,...o?[`   The owner asked for this ${g?"grill":"prototype"}, writing: "${o}"`]:[],...i.length?[`   The owner attached: ${i.map(v=>v.path).join(", ")}.`]:[],...s?[`   The owner asked for prototypes of question ${s}${f?`, noting "${f}"`:""}${w?`, leaning to option ${w}`:""}: draw that question's next round, its question naming round_of ${s}.`]:[],`5. Record what you learned in the card's notes, naming each answered question's id: write it in ${de}, then run ${le(m,e,`${g?"Grill":"Prototype"} (<MM/DD>)`)}, which appends it as a section. The notes file is read-only; never write into it. Anything you leave open becomes a question with question add, never only a line in the notes, so the card can't go ready past it. A question's text is one line of at most ${X} characters (question add refuses a longer one); put the detail in its context and the options' details, which take markdown.`,...g?[`6. Where the owner asked for prototypes, or a rule here wants a UI prototype first, end the card \`${m} item set ${e} --phase prototyping\` instead and skip the prototype question. Otherwise the prototype question is what moves the card on: never set it ready yourself, and never leave a Next that asks the owner to mark it ready.`]:[],"",...q(c),...I(p,"Rules from the hub and this board, written for the orchestrator: where one tells you to push, land, restart the hub or a board server, or do the orchestrator's work, it isn't yours; you never push or restart:"),`To finish, run \`${m} builder done ${e} --text "<what you asked>"\`.`,"","Never push."].join(`
+`)}l(pe,"plannerBrief");function fe({route:t,key:e,ref:r,title:h,notes:n,thread:d,repo:a,agent:u,rules:p=[],links:c=[],text:o,files:i=[]}){const s=$(t);return[`You are the headless visual agent for card ${r} (${e}, "${h}") on the kickflip board /${t}. The owner asked, in the card's thread, for a visual: one HTML page that answers in a visual way, such as a diagram, a flow or a comparison. It is not a prototype or a grill: no question, no takes. The board launched you; nobody watches this session, so never wait on a person. Read and run in ${a}; write no code there, never restart the hub or a board server, and never push.`,"",`1. Run \`${s} builder start ${e} --kind visual --agent ${u}\`. If it refuses, stop.`,`2. Gather what the page needs: ${n?`the card's notes, ${n}; `:""}its thread, ${d}, and the code or docs it is about.`,o?`   The owner wrote: "${o}"`:"   The owner typed nothing: draw what the thread was last discussing.",...i.length?[`   The owner attached: ${i.map(f=>f.path).join(", ")}.`]:[],"3. Write one HTML file outside the repo, such as in a temporary folder. Keep its own CSS and script inline; it may load a library such as Mermaid or D3 from a CDN. Make it read well at phone width (390px) and on a desktop, in the dark and the light theme (prefers-color-scheme).",`4. Place it with \`${s} visual add ${e} --file <page.html> --title "<what it shows>"\`, which copies it to the board and links it in the thread.`,"","Write nothing else: no notes, questions, card state, Next or progress lines.","",...q(c),...I(p,"Rules from the hub and this board, written for the orchestrator: where one tells you to push, land, restart the hub or a board server, or do the orchestrator's work, it isn't yours; you never push or restart:"),`To finish, run \`${s} builder done ${e} --agent ${u}\`.`,"","Never push."].join(`
+`)}l(fe,"visualBrief");function we({route:t,key:e,ref:r,title:h,notes:n,thread:d,agent:a,task:u,writes:p,cwd:c,rules:o=[],links:i=[]}){const s=$(t);return[`You are the headless helper ${a} on card ${r} (${e}, "${h}") on the kickflip board /${t}. Another agent working on the card asked the board for you to do one task beside it, and waits on your hand-back. Nobody watches this session, so never wait on a person. Never restart the hub or a board server, and never push.`,p?`Work only in ${c}, your own worktree, branched from the card's: commit your work there with \`git -c core.commentChar=';' commit -F <file>\`, the subject "${r}: <what it does>". The card's builder merges your branch, so leave nothing uncommitted.`:`Read and run in ${c}; change no files there and commit nothing.`,"","The task:",u,"",`1. Run \`${s} builder start ${e} --kind helper --agent ${a}\`. If it refuses, stop.`,`2. Report progress with \`${s} builder progress ${e} --agent ${a} --phase reading|building|testing|checking "<plain, 80 characters or fewer>"\` at least every 10 minutes; the board adds your name and the phase word.`,"3. Do only the task. Don't ask the orchestrator or the owner, record no judgment calls and post no questions: put any decision you had to make in your hand-back.",n?`   The card's notes, for context: ${n}.`:"",`   ${S(d)}`,"",...q(i),...I(o,"Rules from the hub and this board, written for the orchestrator: where one tells you to push, land, restart the hub or a board server, or do the orchestrator's work, it isn't yours; you never push or restart:"),`To finish, run \`${s} builder done ${e} --agent ${a} --text "<your hand-back: what you did or found, ${p?"what you committed, ":""}and any decision you made>"\`.`,"","Never push."].filter((f,w,b)=>f!==""||b[w-1]!=="").join(`
+`)}l(we,"helperBrief");const me=6e4;function be(t,{starts:e=W}={}){const r=t.filter(n=>n.pid&&n.at).map(n=>n.pid),h=r.length&&e(r)||new Map;return t.filter(n=>{const d=h.get(n.pid);return d!==void 0&&d<=Date.parse(n.at)&&d>=Date.parse(n.at)-me})}l(be,"launchedAgents");function Be(t,{starts:e=W,kill:r=l((n,d)=>process.kill(-n,d),"kill"),killAfter:h=5e3}={}){const n=be(t,{starts:e});for(const{pid:d}of n){try{r(d,"SIGTERM")}catch{continue}setTimeout(()=>{try{r(d,"SIGKILL")}catch{}},h).unref()}return n.length}l(Be,"stopAgents");async function Ne(t,{grace:e=5e3}={}){const r=Z(["-A","-o","pid=,ppid=,pgid=,args="]);if(r===null)throw new oe("ps gave no answer, so nothing was stopped; run it again");const h=r.split(`
+`).map(o=>/^\s*(\d+)\s+(\d+)\s+(\d+)\s+(.*)$/.exec(o)).filter(Boolean).map(([,o,i,s,f])=>({pid:Number(o),ppid:Number(i),pgid:Number(s),args:f})),n=new Set(h.filter(o=>t.includes(o.pgid)).map(o=>o.pid));for(let o=!0;o;){o=!1;for(const i of h)!n.has(i.pid)&&n.has(i.ppid)&&(n.add(i.pid),o=!0)}const d=h.find(o=>o.pid===process.pid)?.pgid,a=h.filter(o=>n.has(o.pid)&&o.pgid>1&&o.pgid!==d),u=[...new Set(a.map(o=>o.pgid))],p=l(o=>{for(const i of u)try{process.kill(-i,o)}catch{}},"signal");p("SIGTERM");const c=Date.now()+e;for(;a.some(o=>B(o.pid))&&Date.now()<c;)await new Promise(o=>setTimeout(o,50));return a.some(o=>B(o.pid))&&p("SIGKILL"),a.map(({pid:o,args:i})=>({pid:o,args:i}))}l(Ne,"stopRuns");const B=l(t=>{try{return process.kill(t,0),!0}catch(e){return e.code==="EPERM"}},"pidAlive");async function Ae(t,e,{launch:r,handBack:h,alive:n=B,held:d=l(()=>!1,"held"),stopped:a=new Set,paused:u=new Set,limitedUntil:p=l(()=>null,"limitedUntil"),atLimit:c=l(async()=>{},"atLimit")}){const o={};for(const[i,s]of Object.entries(t)){if(!e.has(i))continue;if(a.has(i)){o[i]={...s,handedBack:!0};continue}if(u.has(i)||s.pid!==null&&n(s.pid)||s.handedBack){o[i]=s;continue}const f={key:i,...s.kind?{kind:s.kind}:{},...s.model?{model:s.model}:{}},w=s.pid!==null?p(s):null;if(w){await c(f,w),o[i]={...s,pid:null};continue}if(d(s.kind??"claude")){o[i]=s;continue}if(s.pid!==null&&s.relaunched){await h(f),o[i]={...s,handedBack:!0};continue}const{key:b,...m}=f;o[i]={...m,...await r(f),relaunched:s.pid!==null||!!s.relaunched}}return o}l(Ae,"reviveBuilders");const H=l((t,e)=>T.join(Q.homedir(),".claude","kickflip","logs",`${e}-${t}-${new Date().toISOString().replace(/[:.]/g,"-")}.log`),"logFile");async function ge(t,{key:e,kind:r="claude",model:h,agent:n="main",text:d,files:a,question:u,note:p,choice:c,task:o,writes:i,worktree:s},{lander:f=!1}={}){const w=await L(t,e),b=C(t)?.route??T.basename(t),m=[...ee(),...await re(t)].map(V=>V.text),{base:g,repo:v}=M(t),k=ae({kind:r}),R=r===se,N=!k&&!R&&!f&&w.rebasePR!==null,A=r===ie,D=k?v:R?s??w.worktree??v:w.worktree,y={...w,route:b,base:g,repo:v,rules:m,kind:r,agent:n,text:d,files:a,question:u,note:p,choice:c,task:o,writes:i,cwd:D,pr:w.rebasePR},G=A?"Visual agent":R?`Helper ${n}`:k?"Planner":f?"Lander":N?"Rebase run":"Builder",U=A?fe(y):R?we(y):k?pe(y):f?Y(y):N?_(y):ue(y),x=await P({kind:k||R?"claude":r,model:h,cwd:D,site:t,prompt:U,log:H(e.split("/")[1],G.split(" ")[0].toLowerCase())});return await O(t,e,x.sessionId,x.pid,n,T.basename(x.log)),x}l(ge,"launchBuilder");const De=l(({ref:t,worktree:e,cleared:r})=>`The board paused your build of card ${t}, and the pause has cleared: ${r}. Carry on where you stopped, in ${e}, following your brief as before. Your builder record is still open, so don't run builder start again.`,"resumeBrief");async function K(t,{key:e,kind:r="claude",model:h,session:n,brief:d,fresh:a=!1,freshLaunch:u={}}){if(r!=="claude"||!n||a)return{...await ge(t,{key:e,kind:r,model:h},u),resumed:!1};const p=await L(t,e),c=await P({kind:r,model:h,cwd:n.worktree??p.worktree,site:t,prompt:d(p),resume:n.id,log:H(e.split("/")[1],"builder")});return await O(t,e,c.sessionId??n.id,c.pid,"main",T.basename(c.log)),{...c,resumed:!0}}l(K,"resumeBuilder");async function Pe(t,{key:e,kind:r="claude",model:h},{why:n,fresh:d=!1}={}){const a=await ne(t,e),u=await L(t,e),p=u.rebasePR!==null,c=a&&(!p||a.worktree===u.worktree)?a:null,o=C(t)?.route??T.basename(t),{base:i}=M(t),s=l(b=>(p?_:Y)({...b,route:o,base:i,pr:b.rebasePR,why:n,resumed:!0}),"brief"),f={lander:!p};let w;try{w=await K(t,{key:e,kind:r,model:h,session:c,brief:s,fresh:d,freshLaunch:f})}catch(b){if(!c)throw b;w=await K(t,{key:e,kind:r,model:h,session:null,brief:s,freshLaunch:f})}return w.resumed&&await te(t,e,"builder-resumed-to-land",{session:w.sessionId??c.id}),w}l(Pe,"landByBuilder");export{he as BOARD_CLI,ue as builderBrief,we as helperBrief,Pe as landByBuilder,Y as landerBrief,ge as launchBuilder,be as launchedAgents,B as pidAlive,pe as plannerBrief,_ as rebaseBrief,De as resumeBrief,K as resumeBuilder,Ae as reviveBuilders,Be as stopAgents,Ne as stopRuns,fe as visualBrief};

package/board/hub-lines.mjs

@@ -0,0 +1 @@
+var b=Object.defineProperty;var t=(e,o)=>b(e,"name",{value:o,configurable:!0});import w from"node:os";const h=100,P=2e3,$=/(?:~|\/)[^\s:;,()'"]*\/([^\s:;,()'"/]+)/g;function r(e,o,s=""){const d=h-e.length-s.length;let l=String(o??"").split(w.homedir()).join("~").replace(/\s+/g," ").trim();return l.length>d&&(l=l.replace($,"\u2026/$1")),l.length<=d?e+l+s:`${e}${l.slice(0,d-1).trimEnd()}\u2026${s.replace(/^\./,"")}`}t(r,"fit");const i="Held",c="Resumed",u="Blocked",a="Fault",m="move",g="questions",k="Implementation requested",x="Prototype requested",n="Marked done",y="prototype",f="owner/a-long-repo-name#10000",v="Wed, 11/30, 12:00 PM",p={"host-busy":{mark:i,text:t(()=>"Host is busy, work will resume when the host recovers","text")},"planner-held":{mark:i,text:t(({kind:e})=>`The ${e} waits and starts when the hold lifts.`,"text"),longest:{kind:y}},paused:{mark:i,text:t(({phase:e,words:o,clear:s})=>r(`Paused${e?` at ${e}`:""}: `,o,`. It resumes once ${s}.`),"text"),longest:{phase:"building",clear:"the usage pause lifts"}},"run-stopped":{mark:i,text:t(({words:e})=>e,"text"),longest:{words:"build stopped by orchestrator"}},"land-moved-first":{mark:m,text:t(({words:e})=>e,"text"),longest:{words:"land moved first by orchestrator"}},"builder-stopped":{mark:i,text:t(()=>"Stopped its builder.","text")},"land-waiting":{mark:i,text:t(({card:e})=>r("Waiting for ",e," to land"),"text")},resumed:{mark:c,text:t(({clear:e})=>`Resumed: ${e}.`,"text"),longest:{clear:"the usage pause lifted"}},"hold-ended":{mark:c,text:t(({at:e})=>`Resumed: its hold until ${e} ended.`,"text"),longest:{at:v}},unblocked:{mark:c,text:t(({lifted:e})=>r("Unblocked: ",e,"."),"text")},"unblocked-done":{mark:c,text:t(({card:e})=>r("Unblocked: ",e," is done."),"text")},"blocked-pausing":{mark:u,text:t(({blocked:e})=>r("Blocked ",e,": its builder pauses at its next stopping point and it stays In Progress."),"text")},"blocked-stays":{mark:u,text:t(({blocked:e})=>r("Blocked ",e,": it stays In Progress."),"text")},"cant-start-yet":{mark:u,text:t(({names:e})=>r("Can\u2019t start yet: waits on ",e,". Bumped to the top of Todo."),"text")},"split-moved":{mark:u,text:t(({card:e,to:o})=>r("Split: ",`${e} became ${o}`,", so it waits on those now."),"text")},"merge-blocked":{mark:u,text:t(({blocked:e})=>r("Not merged: blocked ",e,"."),"text")},pulled:{mark:k,text:t(()=>"Pulled in: an implementer slot was free.","text")},"helper-asked":{mark:k,text:t(({agent:e,writes:o})=>r("Asked for helper ",e,o?", which writes code":""),"text"),longest:{writes:!0}},"arch-review":{mark:k,text:t(({card:e})=>r("Started an architecture review of ",e,"; its report becomes the notes"),"text")},"prototype-after":{mark:x,text:t(()=>"Prototype round asked: it moves to prototyping once every question is answered.","text")},"prototype-round":{mark:x,text:t(()=>"You asked for a prototype round, so the board moved the card to prototyping.","text")},"ticket-made":{mark:m,text:t(({ticket:e})=>r("You asked for a ticket, so the board made ",e,"."),"text")},"new-question":{mark:g,text:t(()=>"A new question on it, so it is grilling until you answer.","text")},"screen-timeout":{mark:g,text:t(()=>"Questions passed to you unscreened: the orchestrator didn\u2019t screen them in 15 minutes.","text")},"ask-moved":{mark:m,text:t(({board:e})=>r("Moved to ",e,"."),"text")},"pr-found":{mark:m,text:t(({pr:e,branch:o})=>r(`Found PR #${e} on branch `,o,"."),"text"),longest:{pr:1e5}},"ci-passed":{mark:n,text:t(({pr:e})=>`CI passed, so PR #${e} is marked ready for review.`,"text"),longest:{pr:1e5}},"worktree-remade":{mark:m,text:t(()=>"Remade its leftover worktree: it held no commits or changes.","text")},merged:{mark:n,text:t(({words:e})=>r("",e),"text")},"already-merged":{mark:n,text:t(({prs:e,many:o})=>r(`PR${o?"s":""} `,e,` ${o?"were":"was"} already merged.`),"text"),longest:{many:!0}},"ask-moved-closed":{mark:n,text:t(({board:e})=>r("Closed: its ask moved to ",e,"."),"text")},"check-passed":{mark:n,text:t(({found:e})=>r("Check passed: ",e,". Closed."),"text")},"findings-settled":{mark:n,text:t(({filed:e})=>r("Every finding is settled: ",e?`filed ${e}`:"none filed","."),"text")},"branch-merged":{mark:n,text:t(({branch:e,into:o,host:s})=>r("",`${e} is merged into ${o} on ${s}`,", so this card is Done."),"text")},"branch-gone":{mark:n,text:t(({branch:e,host:o})=>r("",`${e} is gone from ${o}`,", so this card is Done."),"text")},"prs-closed":{mark:n,text:t(({prs:e})=>r("Closed: ",e," closed unmerged."),"text"),longest:{prs:`${f}, ${f}`}},"landed-on-merge":{mark:n,text:t(({base:e})=>r("Landed on ",e," on your Merge."),"text")},"lander-handoff":{mark:k,text:t(({why:e})=>r("Not merged yet: ",e,". Its builder resumes to fix it and land it."),"text")},"builder-resumed-to-land":{mark:k,text:t(({session:e})=>r("Builder resumed to land, session ",e),"text")},"build-refused":{mark:a,fault:!0,text:t(({why:e})=>r("Couldn't start implementing: ",e),"text")},"planner-failed":{mark:a,fault:!0,text:t(({kind:e,error:o})=>r(`Couldn't start the ${e}: `,o),"text"),longest:{kind:"visual agent"}},"helper-failed":{mark:a,fault:!0,text:t(({name:e,error:o})=>r(`Couldn't start helper ${e}: `,o),"text"),longest:{name:"a-helper-name-of-24-char"}},"exited-twice":{mark:a,fault:!0,text:t(()=>"Its builder exited twice unfinished; it reads stopped until the orchestrator takes it up.","text")},"resume-failed":{mark:a,fault:!0,text:t(({error:e})=>r("Couldn't resume the builder headless: ",e),"text")},"relaunch-failed":{mark:a,fault:!0,text:t(({error:e})=>r("Couldn't relaunch the builder headless: ",e),"text")},"lander-failed":{mark:a,fault:!0,text:t(({error:e})=>r("Couldn't launch the lander; land it by hand: ",e),"text")},"rebase-failed":{mark:a,fault:!0,text:t(({pr:e,error:o})=>r(`PR #${e} conflicts, but the rebase run couldn't start: `,o),"text"),longest:{pr:1e5}},"rebase-launch-failed":{mark:a,fault:!0,text:t(({error:e})=>r("Couldn't launch the rebase run; it reads stopped: ",e),"text")},"merge-refused":{mark:a,fault:!0,text:t(({why:e})=>r("Not merged: ",e,"."),"text")},"land-failed":{mark:a,fault:!0,text:t(({why:e})=>r("Not merged: ",e,". Tap Merge again."),"text")},"push-failed":{mark:a,fault:!0,text:t(({base:e,error:o})=>r(`Landed, but ${e} didn't reach origin: `,o),"text"),longest:{base:"a-long-base-branch"}},"answers-failed":{mark:a,fault:!0,text:t(({what:e,error:o})=>r(`Answers recorded, but ${e} failed: `,o),"text"),longest:{what:"writing them into its notes"}},"notes-missing":{mark:a,fault:!0,text:t(()=>"Its notes file was missing, so the board started a new one.","text")},"notes-shared":{mark:a,fault:!0,text:t(({card:e})=>r("It shared its notes file with ",e,", so the board gave it its own copy."),"text")},"check-broken":{mark:a,fault:!0,text:t(({error:e})=>r("The owner step's check can't run, so it stopped: ",e),"text")},"run-failed":{mark:a,fault:!0,text:t(({kind:e,code:o,why:s})=>r(`${e} failed (exit ${o})`,s?`: ${s}`:""),"text"),longest:{kind:"Serve",code:255}}};function C(e,o={}){const s=p[e];if(!s)throw new Error(`no status line kind "${e}"`);const d=s.text(o);if(!d||d.length>h)throw new Error(`the "${e}" status line runs to ${d.length} characters, past ${h}: ${d}`);return d}t(C,"hubText");const T=t(e=>({mark:p[e.line]?.mark||"",fault:!!p[e.line]?.fault}),"hubLineOf"),R="hub";export{h as BRIEF_LINE_LIMIT,R as HUB,p as HUB_LINES,P as MESSAGE_LIMIT,r as fit,T as hubLineOf,C as hubText};

package/board/onboarding.mjs

@@ -1,4 +1,4 @@
-var h=Object.defineProperty;var o=(e,i)=>h(e,"name",{value:i,configurable:!0});import l from"node:fs";import d from"node:path";import{execFileSync as c}from"node:child_process";const p="# Prepare .kickflip/build\n\nThe hub builds and serves a card's version of this repo by running one script, `.kickflip/build <wave>/<id> <worktree>`, in the card's worktree. This board has none on main yet.\n\nContract (docs/adr/2026-11-01-1846-a-boards-build-script-serves-or-builds-each-card-and-main.md):\n- Print exactly `port <n>` on stdout to serve a website on that port.\n- Or exit 0 with no port for an app build, publishing the install with `board.mjs item set --install --install-sha`.\n- The file is a regular file in the repo, executable, writable by no one but its owner.\n\nWhat this card does:\n- Look at the repo for what it builds: a website or server, an iOS or Android app, a CLI, a library with nothing to serve.\n- If it finds one type, write `.kickflip/build` for it.\n- If it finds several, ask the owner which the board should serve, write one `.kickflip/build-<target>` for each type the owner wants (for example `build-web`, `build-ios`), and set this board's Build target in Board Settings to the one picked.\n- If nothing here builds, say so and write nothing.\n",u=`# Write CONTEXT.md and the first ADR
+var l=Object.defineProperty;var r=(e,t)=>l(e,"name",{value:t,configurable:!0});import c from"node:fs";import h from"node:path";import{execFileSync as p}from"node:child_process";const u="# Prepare .kickflip/build\n\nThe hub builds and serves a card's version of this repo by running one script, `.kickflip/build <file>/<id> <worktree>`, in the card's worktree. This board has none on main yet.\n\nContract (docs/adr/2026-11-01-1846-a-boards-build-script-serves-or-builds-each-card-and-main.md):\n- Print exactly `port <n>` on stdout to serve a website on that port.\n- Or exit 0 with no port for an app build, publishing the install with `board.mjs item set --install --install-sha`.\n- The file is a regular file in the repo, executable, writable by no one but its owner.\n\nWhat this card does:\n- Look at the repo for what it builds: a website or server, an iOS or Android app, a CLI, a library with nothing to serve.\n- If it finds one type, write `.kickflip/build` for it.\n- If it finds several, ask the owner which the board should serve, write one `.kickflip/build-<target>` for each type the owner wants (for example `build-web`, `build-ios`), and set this board's Build target in Board Settings to the one picked.\n- If nothing here builds, say so and write nothing.\n",w=`# Write CONTEXT.md and the first ADR
 
 Cards in this repo are grilled and built against its own words and decisions. This card writes them down.
 
@@ -7,5 +7,5 @@ What this card does:
 - Write the first ADR in docs/adr/, named docs/adr/YYYY-MM-DD-HHMM-<slug>.md, for the biggest decision the repo's shape shows: what was chosen and what was considered.
 - Ask the owner what the project is for and which words they use for its parts; their wording goes in verbatim.
 - If the repo already has a CONTEXT.md or ADRs, extend them rather than start again.
-`,b=[{id:"onboard-build",title:"Prepare .kickflip/build",notes:p,needsNoBuild:!0},{id:"onboard-context",title:"Write the repo's CONTEXT.md glossary and first ADR",notes:u}];function T(e,i){try{return c("git",["-C",e,"ls-tree",`${i}:.kickflip`],{encoding:"utf8",stdio:["ignore","pipe","ignore"],timeout:3e3}).split(`
-`).some(r=>/^100755 blob \S+\tbuild(-.+)?$/.test(r))}catch{return!1}}o(T,"hasBuildScript");function y(e,{prefix:i="INT",hasBuild:s,now:r=new Date}){return b.filter(t=>!(t.needsNoBuild&&s)).map((t,a)=>{const n=`${t.id}-notes.md`;return l.writeFileSync(d.join(d.dirname(e),n),t.notes),{id:t.id,title:t.title,created:new Date(r.getTime()+a).toISOString(),phase:"grilling",ticket:`${i}-${a+1}`,plan:n}})}o(y,"onboardingItems");export{T as hasBuildScript,y as onboardingItems};
+`,f=[{title:"Prepare .kickflip/build",notes:u,needsNoBuild:!0},{title:"Write the repo's CONTEXT.md glossary and first ADR",notes:w}];function T(e,t){try{return p("git",["-C",e,"ls-tree",`${t}:.kickflip`],{encoding:"utf8",stdio:["ignore","pipe","ignore"],timeout:3e3}).split(`
+`).some(s=>/^100755 blob \S+\tbuild(-.+)?$/.test(s))}catch{return!1}}r(T,"hasBuildScript");function y(e,{hasBuild:t,now:o=new Date}){return f.filter(i=>!(i.needsNoBuild&&t)).map((i,a)=>{const n=`T-${a+1}`,d=`${n}-notes.md`;return c.writeFileSync(h.join(h.dirname(e),d),i.notes),{id:n,title:i.title,created:new Date(o.getTime()+a).toISOString(),phase:"grilling",plan:d}})}r(y,"onboardingItems");export{T as hasBuildScript,y as onboardingItems};

package/board/public/app-arch.js

@@ -65,7 +65,7 @@ BoardView.part((B) => {
     sheet.showModal();
   });
   B.on(sheet, 'click', (ev) => {
-    if (ev.target === sheet || ev.target.closest('#archClose')) { sheet.close(); return; }
+    if (BoardUI.onBackdrop(ev, sheet) || ev.target.closest('#archClose')) { sheet.close(); return; }
     const open = ev.target.closest('[data-arch-open]');
     if (open) { ev.preventDefault(); openCard(open.dataset.archOpen); return; }
     if (ev.target.closest('[data-arch-run]')) run();

package/board/public/app-cards.js

@@ -76,7 +76,7 @@ BoardView.part((B) => {
     loadMainLog();
   });
   B.on($('#mainLogClose'), 'click', closeMainLog);
-  B.on(mainSheet, 'click', (ev) => { if (ev.target === mainSheet) closeMainLog(); });
+  B.on(mainSheet, 'click', (ev) => { if (BoardUI.onBackdrop(ev, mainSheet)) closeMainLog(); });
   B.on(mainSheet, 'cancel', (ev) => { ev.preventDefault(); closeMainLog(); });
   B.on(mainRetry, 'click', async () => {
     if (mainRetry.disabled) return;
@@ -179,7 +179,7 @@ BoardView.part((B) => {
   }
   B.on($('#holdClose'), 'click', closeHold);
   B.on(holdSheet, 'click', (ev) => {
-    if (ev.target === holdSheet) { closeHold(); return; }
+    if (BoardUI.onBackdrop(ev, holdSheet)) { closeHold(); return; }
     const chip = ev.target.closest('[data-hold-for]');
     if (chip) { hold(chip.dataset.holdFor, chip.value); return; }
     const input = ev.target.closest('[data-hold-at]');
@@ -215,7 +215,7 @@ BoardView.part((B) => {
     const pr = it.pr;
     const ctx = links(it.key);
     const rows = [];
-    rows.push(['Wave', escText(it.waveTitle)]);
+    if (it.wave) rows.push(['Wave', escText(it.wave.title)]);
     if (pr) {
       const ci = pr.checks ? `${pr.checks.state}${pr.checks.fail ? ` (${pr.checks.fail} failing)` : pr.checks.pending ? ` (${pr.checks.pending} running)` : ''}` : 'unknown';
       if (pr.state === 'OPEN') {
@@ -307,7 +307,7 @@ BoardView.part((B) => {
   // Every prototype round is a question on its card, so this button reaches the prototypes too, Done cards included
   // (docs/adr/2026-11-09-1100-needs-you-button-reaches-the-prototypes.md).
   const ACTION_BUTTONS = {
-    [BUTTON.openQuestions]: (it) => `<a${classes(it, BUTTON.openQuestions, 'button')} href="questions.html#${esc(it.questions.first)}">Needs you</a>`,
+    [BUTTON.openQuestions]: (it) => `<a${classes(it, BUTTON.openQuestions, 'button')} href="questions.html#${esc(it.questions.first)}">Questions</a>`,
   };
   const actionButton = (it) => ACTION_BUTTONS[it.actionButton]?.(it) || '';
 
@@ -315,16 +315,15 @@ BoardView.part((B) => {
   // (docs/adr/2026-10-29-1639-a-pending-ask-can-be-deleted-or-bumped.md,
   // docs/adr/2026-11-06-1700-a-bump-marks-the-priority-through-every-lane.md).
   const bumpedAsk = (it) => Boolean(it.isNew && it.bumpedAt);
-  // band {step, actions} draws the card in a wave band (app-lanes.js).
   // Its open questions asked since this browser last opened it are one more unread message: the thread's "N new
   // questions" line (app-threads.js; docs/adr/2026-11-04-2130-a-button-tap-is-a-status-line-or-a-message-footer.md).
-  function card(it, band = {}) {
+  function card(it) {
     const unseen = (times) => (state.openItems.has(it.key) ? 0 : unreadCount(times, seen[it.key]));
     const unread = unseen(it.othersAt) + Math.min(1, unseen(it.questions?.askedAt));
     return `<details class="item" data-key="${esc(it.key)}" ${state.openItems.has(it.key) ? 'open' : ''}>
           <summary class="work">
             <span class="status ${it.lane}"></span>
-            <div class="title-wrap">${workLines(it, { unread, top: bumpedAsk(it), ...band })}</div>
+            <div class="title-wrap">${workLines(it, { unread, top: bumpedAsk(it) })}</div>
           </summary>
           ${state.openItems.has(it.key) ? detail(it) : ''}
         </details>`;

package/board/public/app-header.js

@@ -51,7 +51,7 @@ BoardView.part((B) => {
     linksSheet.showModal();
   });
   B.on($('#linksClose'), 'click', closeLinks);
-  B.on(linksSheet, 'click', (ev) => { if (ev.target === linksSheet) closeLinks(); });
+  B.on(linksSheet, 'click', (ev) => { if (BoardUI.onBackdrop(ev, linksSheet)) closeLinks(); });
   B.on(linksSheet, 'cancel', (ev) => { ev.preventDefault(); closeLinks(); });
   function askGitHub() {
     state.githubPending = Date.now();

package/board/public/app-lanes.js

@@ -1,5 +1,5 @@
-// The board view's lanes and the Auto Review lane leading them: each lane's header and cards, Done's and Asks' Show more,
-// Done's finished-wave folds, and Todo's wave bands with their Implement and card order.
+// The board view's lanes and the Auto Review lane leading them: each lane's header and cards, Done's Show more,
+// Done's finished-item-file folds, and Todo's wave bands with their Implement and card order.
 // Needs app-core.js and app-cards.js.
 BoardView.part((B) => {
   const { $, store, state } = B;
@@ -9,9 +9,8 @@ BoardView.part((B) => {
     { id: 'progress', name: 'In Progress', open: true },
     { id: 'todo', name: 'Todo', open: true },
     { id: 'done', name: 'Done', open: false, capped: true },
-    { id: 'asks', name: 'Asks', open: false, capped: true },
   ];
-  // docs/adr/2026-11-03-0259-answered-asks-have-their-own-section-below-done.md
+  // docs/adr/2026-11-09-1430-answered-asks-fold-into-the-one-done-list.md
   // A capped lane shows STEP cards, and each Show more tap adds STEP more, kept in memory per lane. A card the owner opened
   // this visit stays shown past the cap; one open from before a reload does not (state.restored). Show more says how many are left (docs/adr/2026-10-29-1639-lists-never-cut-silently.md).
   // older is how many cards wait past `cards` in the archive; the tap that would show past `cards` fetches them first.
@@ -52,7 +51,7 @@ BoardView.part((B) => {
   }
 
   // A fold's open state lives in storage, not in setHTML's summary-text match, because its row's count changes.
-  // Fold ids are wave:<slug> (board/domain.mjs waveFold), so any id maps to its own storage key.
+  // Fold ids are file:<slug> (board/domain.mjs fileFold), so any id maps to its own storage key.
   const FOLDS = new Proxy({}, { get: (_, id) => ({ store: `foldOpen:${String(id)}` }) });
   // A fold's header reads like a lane's: its name, then its count.
   function fold(id, list, name) {
@@ -63,12 +62,12 @@ BoardView.part((B) => {
       </details>`;
   }
 
-  // One row per finished wave, newest card first, as Done's items arrive sorted.
-  function waveFolds(d, items) {
-    const slugs = [...new Set(items.filter((i) => i.fold === `wave:${i.wave}`).map((i) => i.wave))];
+  // One row per finished item file, newest card first, as Done's items arrive sorted.
+  function fileFolds(d, items) {
+    const slugs = [...new Set(items.filter((i) => i.fold === `file:${i.file}`).map((i) => i.file))];
     return slugs.map((slug) => {
-      const w = d.waves.find((x) => x.slug === slug);
-      return fold(`wave:${slug}`, items.filter((i) => i.fold === `wave:${slug}`), escText(w.title));
+      const w = d.itemFiles.find((x) => x.slug === slug);
+      return fold(`file:${slug}`, items.filter((i) => i.fold === `file:${slug}`), escText(w.title));
     }).join('');
   }
 
@@ -94,7 +93,7 @@ BoardView.part((B) => {
       const items = shown.filter((i) => i.lane === lane.id);
       const expanded = laneState[lane.id] ?? lane.open;
       const open = items.filter((i) => !i.fold);
-      const rows = lane.id === 'todo' ? todoRows(d, shown, open) : (lane.id === 'done' ? doneRows(d, open) : lane.capped ? cappedRows(lane.id, open) : waveGroups(lane.id, open)) + waveFolds(d, items);
+      const rows = lane.id === 'todo' ? todoRows(d, shown, open) : (lane.id === 'done' ? doneRows(d, open) : lane.capped ? cappedRows(lane.id, open) : waveGroups(lane.id, open)) + fileFolds(d, items);
       return `<details class="lane" data-lane="${lane.id}" ${expanded ? 'open' : ''}>
         <summary><span class="lane-name">${lane.name}</span><span class="count">${lane.id === 'done' ? doneCount(d, items) : items.length}</span>${lane.id === 'review' ? B.githubHeader(d) : ''}</summary>
         <div class="list">${rows || '<div class="empty">Nothing here.</div>'}
@@ -125,22 +124,30 @@ BoardView.part((B) => {
     const grouped = bands.filter((b) => inBand(b).length);
     if (!grouped.length) return cards.map((it) => B.card(it)).join('');
     const loose = cards.filter((i) => !bands.some((b) => b.keys.includes(i.key)));
-    const group = (cls, data, name, n, counts, list) => `<section class="${cls}"${data}><div class="wb-head wb-loosehead">${counts ? BoardUI.WAVE_ICON : ''}<span class="wb-label"><span class="lane-name">${name}</span> <span class="count">${n}</span></span>${counts}</div>${list.map((it) => B.card(it)).join('')}</section>`;
-    return grouped.map((b) => group('wb-lane', ` data-wave="${esc(b.slug)}"`, escText(b.title), inBand(b).length, waveCounts(b, laneId), inBand(b))).join('')
-      + (loose.length ? group('wb-loose', '', 'No wave', loose.length, '', loose) : '');
+    const body = (list) => list.map((it) => B.card(it)).join('');
+    return grouped.map((b) => groupHtml(laneId, b.slug, true, BoardUI.WAVE_ICON + groupLabel(escText(b.title), inBand(b).length) + waveCounts(b, laneId), body(inBand(b)))).join('')
+      + (loose.length ? groupHtml(laneId, NO_WAVE, true, groupLabel('No wave', loose.length), body(loose)) : '');
+  }
+
+  // The one header every lane gives every group, a wave or No wave: a tap on it folds the group, and its open state
+  // lives in storage under the lane and the group's slug. head is the header's content, body the cards under it.
+  const NO_WAVE = 'no-wave';
+  const groupStore = (id) => FOLDS[`band:${id}`].store;
+  const groupLabel = (name, n) => `<span class="wb-label"><span class="lane-name">${name}</span> <span class="count">${n}</span></span>`;
+  function groupHtml(laneId, slug, open, head, body) {
+    const id = `${laneId}/${slug}`;
+    const isOpen = store.get(groupStore(id), open);
+    const header = `<div class="wb-head" data-band-toggle="${esc(id)}" role="button" tabindex="0" aria-expanded="${isOpen}">${head}</div>`;
+    return `<section class="wb" data-band="${esc(slug)}" data-lane="${laneId}"${isOpen ? ' data-open' : ''}>${header}${isOpen ? `<div class="wb-body">${body}</div>` : ''}</section>`;
   }
 
   // docs/adr/2026-11-03-1840-waves-are-bands-in-todo.md
   // Todo's wave bands (domain.mjs waveBandsOf), then its cards in no wave under No wave. A band's open state lives
-  // in storage once the owner taps its head; until then only the first band whose next card is ready (a wave file's:
-  // any Todo card) starts open. A band's name shows its goal as a tooltip, or a popover on a long-press. menu is the
-  // card whose ⋯ menu is open, goalShown the band whose goal popover is open.
-  let menu = null;
+  // in storage once the owner taps its head; until then only the first band whose next card is ready (an item file's:
+  // any Todo card) starts open. A band's name shows its goal as a tooltip, or a popover on a long-press. goalShown is
+  // the band whose goal popover is open.
   let goalShown = null;
-  const bandStore = (slug) => FOLDS[`band:${slug}`].store;
-  const bandOpen = (band, first) => store.get(bandStore(band.slug), band.slug === first);
   const LANE_WORDS = { progress: 'in progress', review: 'in review' };
-  const DOTS = '<svg width="16" height="16" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><circle cx="5" cy="12" r="1.8"/><circle cx="12" cy="12" r="1.8"/><circle cx="19" cy="12" r="1.8"/></svg>';
 
   // Todo's wave bands and loose cards, in the order they arrive (domain.mjs laneOrder).
   function todoRows(d, shown, todo) {
@@ -150,8 +157,8 @@ BoardView.part((B) => {
     const loose = todo.filter((i) => !banded.has(i.key));
     const first = bands.find((b) => (b.next ? b.next.ready : b.keys.some((k) => byKey.get(k)?.ready)))?.slug;
     if (!bands.length) return loose.map((it) => B.card(it)).join('');
-    return bands.map((b) => bandHtml(b, b.keys.map((k) => byKey.get(k)).filter(Boolean), bandOpen(b, first))).join('')
-      + (loose.length ? `<div class="wb-loose"><div class="wb-head wb-loosehead"><span class="lane-name">No wave</span><span class="count">${loose.length}</span></div>${loose.map((it) => B.card(it)).join('')}</div>` : '');
+    return bands.map((b) => bandHtml(b, b.keys.map((k) => byKey.get(k)).filter(Boolean), b.slug === first)).join('')
+      + (loose.length ? groupHtml('todo', NO_WAVE, true, groupLabel('No wave', loose.length),loose.map((it) => B.card(it)).join('')) : '');
   }
 
   function bandHtml(band, cards, open) {
@@ -160,38 +167,23 @@ BoardView.part((B) => {
     const now = cards.filter((i) => LANE_WORDS[i.lane]).map((i) => `${esc(i.ref)} ${LANE_WORDS[i.lane]}`);
     const progress = now.length ? ` <span class="count">· ${now.join(' · ')}</span>` : '';
     const name = `<span class="lane-name wb-name"${band.goal ? ` title="${esc(band.goal)}" data-goal="${esc(band.slug)}"` : ''}>${escText(band.title)}</span>`;
-    const notes = band.kind === 'lineup' ? `<span class="external-link"><a href="notes.html?wave=${encodeURIComponent(band.slug)}">Notes</a></span><span class="external-separator" aria-hidden="true"> · </span>` : '';
+    const notes = band.kind === 'wave' ? `<span class="external-link"><a href="notes.html?wave=${encodeURIComponent(band.slug)}">Notes</a></span><span class="external-separator" aria-hidden="true"> · </span>` : '';
     const next = band.next;
     const go = !next ? '' : next.ready
       ? `<button type="button" class="wv-link" data-confirm="card-build" data-key="${esc(next.key)}">Implement</button>`
       : `<span class="wb-next">next: ${esc(next.ref)} ${esc(next.word)}</span>`;
     const pop = goalShown === band.slug && band.goal ? `<div class="wb-pop" role="tooltip">${esc(band.goal)}</div>` : '';
-    const head = `<div class="wb-head" data-band-toggle="${esc(band.slug)}" role="button" tabindex="0" aria-expanded="${open}">${BoardUI.WAVE_ICON}`
-      + `<span class="wb-label">${name} <span class="count">${todo.length}</span>${progress}</span>`
-      + waveCounts(band, 'todo') + `<span class="wb-end"><span class="wb-links">${notes}</span>${go}</span>${pop}</div>`;
-    if (!open) return `<section class="wb" data-band="${esc(band.slug)}">${head}</section>`;
+    const head = `${BoardUI.WAVE_ICON}<span class="wb-label">${name} <span class="count">${todo.length}</span>${progress}</span>`
+      + waveCounts(band, 'todo') + `<span class="wb-end"><span class="wb-links">${notes}</span>${go}</span>${pop}`;
     const doneRow = done.length ? `<div class="wb-done">${done.length} done · ${done.map((i) => `<a class="card-link" href="#selectedCard=${encodeURIComponent(i.key)}">${esc(i.ref)}</a>`).join(', ')}</div>` : '';
-    const step = (it) => (band.kind === 'lineup' ? band.phases.findIndex((p) => p.includes(it.key)) + 1 : 0);
-    const actions = (it, at) => (band.kind !== 'lineup' ? null : cardMenu(band.slug, it.key, at, todo.length));
-    return `<section class="wb" data-band="${esc(band.slug)}" data-open>${head}<div class="wb-body">${doneRow}${todo.map((it, at) => B.card(it, { step: step(it), actions: actions(it, at) })).join('')}</div></section>`;
-  }
-
-  // A lineup card's ⋯ and, while open, its menu: Move up and Move down among the band's Todo cards. A move waits for
-  // the server (board/server.mjs lineup-move): the tapped move waits and the other is disabled meanwhile.
-  function cardMenu(slug, key, at, count) {
-    const shown = menu === key;
-    const item = (by, label) => {
-      const off = by < 0 ? at === 0 : at === count - 1;
-      return `<button type="button" role="menuitem" data-band-move="${by}" data-band="${esc(slug)}" data-key="${esc(key)}"${off ? ' disabled' : ''}>${label}</button>`;
-    };
-    return `<div class="ask-actions"><button type="button" class="ghost icon wb-dots" data-band-menu="${esc(key)}" aria-label="Card menu" aria-haspopup="menu" aria-expanded="${shown}">${DOTS}</button>`
-      + (shown ? `<div class="wb-menu" role="menu">${item(-1, '↑ Move up')}${item(1, '↓ Move down')}</div>` : '') + '</div>';
+    return groupHtml('todo', band.slug, open, head, doneRow + todo.map((it) => B.card(it)).join(''));
   }
 
   // Opens the band holding card key or named slug, for a #selectedCard= link or a Needs you line.
   function openBand({ key, slug }) {
+    const lane = (key && state.board?.items.find((i) => i.key === key)?.lane) || 'todo';
     const band = (state.board?.waveBands || []).find((b) => b.slug === slug || b.keys.includes(key));
-    if (band) store.set(bandStore(band.slug), true);
+    if (band) store.set(groupStore(`${lane}/${band.slug}`), true);
     return band;
   }
 
@@ -245,11 +237,11 @@ BoardView.part((B) => {
       if (!openBand({ slug: show.dataset.bandShow })) return;
       const s = store.get('lanes', {}); s.todo = true; store.set('lanes', s);
       B.render();
-      $(`.wb[data-band="${CSS.escape(show.dataset.bandShow)}"]`)?.scrollIntoView({ block: 'start' });
+      $(`.wb[data-lane="todo"][data-band="${CSS.escape(show.dataset.bandShow)}"]`)?.scrollIntoView({ block: 'start' });
     }
   });
 
-  // A band's ⋯ menu and its moves, its head's fold and its name's goal popover. A long-press on the name (touch only;
+  // A band's head's fold and its name's goal popover. A long-press on the name (touch only;
   // a mouse has the tooltip) opens the popover, and the click that ends the press neither folds the band nor closes it.
   let press = null;
   let pressed = false;
@@ -272,24 +264,9 @@ BoardView.part((B) => {
     }
     if (pressed) { pressed = false; ev.preventDefault(); return; }
     if (goalShown) { goalShown = null; B.render(); if (ev.target.closest('.wb-head')) return; }
-    const dots = ev.target.closest('button[data-band-menu]');
-    if (dots) { ev.preventDefault(); menu = menu === dots.dataset.bandMenu ? null : dots.dataset.bandMenu; B.render(); return; }
-    const mv = ev.target.closest('button[data-band-move]');
-    if (mv) {
-      ev.preventDefault();
-      if (mv.disabled) return;
-      const { band, key } = mv.dataset;
-      try { await waitOn(mv, B.send('lineup-move', { lineup: band, key, by: Number(mv.dataset.bandMove) }), { group: mv.parentNode.querySelectorAll('button') }); }
-      catch { B.toast('Could not move it. Is the host awake?'); }
-      menu = null;
-      B.render();
-      return;
-    }
-    if (menu && !ev.target.closest('.wb-menu')) { menu = null; B.render(); if (ev.target.closest('summary')) { ev.preventDefault(); return; } }
     const head = ev.target.closest('[data-band-toggle]');
     if (head && !ev.target.closest('a, button')) {
-      const slug = head.dataset.bandToggle;
-      store.set(bandStore(slug), head.getAttribute('aria-expanded') !== 'true');
+      store.set(groupStore(head.dataset.bandToggle), head.getAttribute('aria-expanded') !== 'true');
       B.render();
     }
   });

package/board/public/app-needs.js

@@ -15,7 +15,7 @@
 // Needs app-core.js.
 BoardView.part((B) => {
   const { $, plural, state, toast } = B;
-  const { esc, escText, promptItem, choiceLabel, isPrototype, getDraft, setDraft, noteOf, waitOn } = BoardUI;
+  const { esc, escText, markdown, promptItem, choiceLabel, isPrototype, getDraft, setDraft, noteOf, waitOn } = BoardUI;
 
   const prompts = PromptAnswers.wire(B, {
     list: () => (state.board?.needs || []).filter((line) => line.prompt).map((line) => line.prompt),
@@ -65,6 +65,7 @@ BoardView.part((B) => {
   // order; any other line as itself. → [{id, what, html}]
   function deckOf(d, needs) {
     const items = d.items || [];
+    const links = BoardUI.linkContext(items);
     const owner = (d.owner || []).filter((q) => q.state === 'open');
     const topicOf = (line) => line.topic || items.find((it) => it.key === line.key)?.questions?.topic || null;
     return needs.flatMap((line) => {
@@ -73,7 +74,7 @@ BoardView.part((B) => {
       const topic = line.questions && topicOf(line);
       const order = (d.ownerTopics || []).find((t) => t.id === topic)?.questions || [];
       const asks = topic ? owner.filter((q) => q.topic === topic).sort((a, b) => order.indexOf(a.id) - order.indexOf(b.id)) : [];
-      if (asks.length) return asks.map((q) => ({ id: `q:${q.id}`, what, html: questionHtml(q) }));
+      if (asks.length) return asks.map((q) => ({ id: `q:${q.id}`, what, html: questionHtml(q, links) }));
       const [label, href, attrs] = line.questions ? [`Answer ${plural(line.questions.open, 'question')}`, line.questions.url, '']
         : line.ready ? ['Ready on GitHub', line.ready, ' target="_blank" rel="noopener"']
         : line.action ? [line.action.label, line.action.url, '']
@@ -85,14 +86,14 @@ BoardView.part((B) => {
     });
   }
   // The marked option, the question's drafted pick, reads Send “<label>”.
-  const questionHtml = (q) => {
+  const questionHtml = (q, links) => {
     const marked = getDraft(q.id).choice;
     const optionHtml = (o) => {
       const armed = o.id === marked;
       const label = armed ? `Send “${esc(o.label)}”` : `${esc(choiceLabel(q, o.id))}${o.recommended ? ' <span class="rec-word">recommended</span>' : ''}`;
-      return `<button type="button" class="${[o.recommended && 'rec', armed && 'armed'].filter(Boolean).join(' ')}" aria-pressed="${armed}" data-deck-pick="${esc(o.id)}"><span class="lbl">${label}</span>${o.detail ? `<small>${escText(o.detail)}</small>` : ''}</button>`;
+      return `<button type="button" class="${[o.recommended && 'rec', armed && 'armed'].filter(Boolean).join(' ')}" aria-pressed="${armed}" data-deck-pick="${esc(o.id)}"><span class="lbl">${label}</span>${o.detail ? `<div class="det">${markdown(o.detail, links)}</div>` : ''}</button>`;
     };
-    return `<h3>${escText(q.question)}</h3>${q.context ? `<p class="ctx">${escText(q.context)}</p>` : ''}
+    return `<h3>${escText(q.question)}</h3>${q.context ? `<div class="ctx">${markdown(q.context, links)}</div>` : ''}
     ${isPrototype(q.url) ? `<a class="button deck-proto" href="${esc(q.url)}">View prototypes</a>` : ''}
     <div class="deck-opts" role="group" aria-label="${esc(q.question)}">${q.options.map(optionHtml).join('')}</div>`;
   };
@@ -110,7 +111,7 @@ BoardView.part((B) => {
     showing = now.id;
     const at = deck.indexOf(now);
     const open = (d.owner || []).filter((q) => q.state === 'open').length;
-    const drafted = (d.owner || []).filter((q) => q.state === 'open' && 'choice' in getDraft(q.id)).length;
+    const drafted = (d.owner || []).filter((q) => q.state === 'open' && getDraft(q.id).choice != null).length;
     BoardUI.setHTML(el, `<div class="deck-head"><h2>Needs you</h2><span class="deck-n">${deck.length}</span></div>
       <div class="deck-card" data-deck="${esc(now.id)}"><p class="deck-what">${escText(now.what)}</p>${now.html}</div>
       ${deck.length > 1 ? `<div class="deck-bar"><button type="button" class="ghost" data-deck-prev${at === 0 ? ' disabled' : ''}>← Prev</button><span class="deck-dots" aria-hidden="true">${deck.map((x) => `<i${x === now ? ' class="on"' : ''}></i>`).join('')}</span><button type="button" class="ghost" data-deck-next${at === deck.length - 1 ? ' disabled' : ''}>Next →</button></div>` : ''}
@@ -156,10 +157,10 @@ BoardView.part((B) => {
   // From 900px, Waiting on you in the pane under the Needs you lines, mounted while the width lasts.
   let questions = null;
   // Two taps on a pane pill focus its topic on the board: item:<key> is a card (an ask is one, ask:<id>),
-  // wave:<slug> a band; any other topic, or one the board doesn't show, does nothing.
+  // wave:<slug> or file:<slug> a band; any other topic, or one the board doesn't show, does nothing.
   function openOnBoard(id) {
     if (id.startsWith('item:')) B.focusOnBoard({ key: id.slice(5) });
-    else if (id.startsWith('wave:')) B.focusOnBoard({ slug: id.slice(5) });
+    else if (id.startsWith('wave:') || id.startsWith('file:')) B.focusOnBoard({ slug: id.slice(5) });
   }
   function fitPane() {
     if (wide.matches === Boolean(questions)) return;
@@ -231,9 +232,13 @@ BoardView.part((B) => {
     else viewer.sheet = !viewer.sheet;
     paintViewer();
   });
-  // A push to a card's thread (#item=<key>&reply, board/store.mjs pushUrl), the switcher's for a question already picked
-  // among them, closes the viewer, so the thread it sent the owner to shows.
-  B.on(window, 'hashchange', () => { if (/^#item=[^&]+&reply$/.test(location.hash)) closeViewer(); });
+  // A push to a card's thread (#selectedCard=<key>&reply, board/store.mjs threadUrl), the switcher's for a question
+  // already picked among them, closes the viewer, so the thread it sent the owner to shows. The older #item=<key>&reply
+  // reads the same.
+  B.on(window, 'hashchange', () => {
+    const at = AppRouter.fragmentOf(location.hash);
+    if (at.selectedCard && at.reply) closeViewer();
+  });
 
   fitPane();
   B.on(wide, 'change', fitPane);