@asrunjs/asrun 0.2.0 → 0.5.3

package/.claude/skills/exploring-cases/references/user-handoff.md

@@ -1,147 +1,157 @@
-# User handoff: a person works in the browser, the agent waits
-
-Used by `exploring-cases` (and by `making-cases` never: it does not open a browser). `generating-specs` never hands
-off; it replays the `## Inputs` that an exploration recorded.
-
-## The rule
-**An agent never writes data.** Not in staging, not in production. Every step that creates, edits, publishes, shares,
-deletes or otherwise changes data, and every step that needs a human's choice (an existing document, items, a contact
-name), is done by the user in the browser window that Playwright opened. Writing is rare (only while preparing a
-case) and a person succeeds where an agent guesses. The agent drives only what is read-only: open, look, read,
-hover, switch tabs, open and close dialogs and menus.
-
-The runtime permission is a different thing and stays as it is: `writes: [<env>, ...]` in the case front matter says
-where the finished spec may write, and a human confirms a run in any environment except staging.
-
-## When a handoff happens
-Only in an attended run (`--attended`, a person is at the machine, the browser window is visible). A step is a
-handoff when it is marked `[input]` or `[writes]` in the case, or when the agent finds out while exploring that the
-next action would write data or needs a choice.
-
-Without `--attended` the agent does not wait. It writes a `TODO [blocking]` under that step ("a person has to
-perform this step; run /explore-case with --attended") and goes on with the rest. Never wait for a person in a run
-that nobody watches.
-
-## Before the handoff
-1. Say what the user has to do and when it is finished, in one or two sentences ("Fill in the form, pick two
-   items, then press Done"). Name the finish condition first (below).
-2. Put every text the user has to type into `copy` (the `[asrun] ...` name of a document, a title), so it can be
-   copied with one click.
-3. Never ask the user to send email (production: never; other environments: only when `email` is `true` for the
-   profile). Never ask for login or 2FA. Name everything the user creates `[asrun] <something>`.
-4. Start recording with `browser_start_recording` (see "Recording").
-
-## The wait loop
-Run it with one `browser_run_code_unsafe` call. A single call may wait for minutes (verified: 150 s without a
-timeout), so no polling from outside is needed. The loop:
-
-- **Shows a small floating card, not a bar.** It sits in the bottom-left corner and only the card takes clicks, so
-  nothing of the page is covered or blocked. The user can **drag** it by its title bar and **minimize** it to a small
-  pill that still has a Done button. Position and minimized state survive a page reload (kept in `sessionStorage`).
-- **Click to copy.** Every text in `copy` (for example the `[asrun] ...` name the user has to type) is shown on its
-  own line with a copy icon; one click puts it on the clipboard and the icon shows "Copied". Pass only text that the
-  case says to type; leave `copy` empty when there is none.
-- **Resets the flag first**: `window.__handoff = null` on every page it paints. A flag left over from an earlier
-  handoff ends the wait at once.
-- **Paints the card on every open tab** and repaints after navigation (a new page has no card). The document
-  editor opens in a new tab, so the loop looks at `context.pages()`, not only at the first page.
-- **Stops** when one of these happens, whichever is first: the user presses Done or "Cannot do this" on the card
-  (`window.__handoff` is `'done'` or `'skip'`), or the finish condition holds, or the time is up (default 10 minutes).
-- **Ends visibly**: the card turns green and says control is back for two seconds, then it is removed, and the tab
-  titles are restored.
-- The card lives in a Shadow DOM (the site's CSS cannot change it), does not take keyboard focus (the user can keep
-  typing in the page) and works even when the page locks all clicks behind a modal. The icons are inline SVG because
-  the card is injected into the page under test; the web UI's react-feather rule does not apply to it.
-
-**Never write this code yourself and never shorten it.** It lives in `references/handoff-card.js` (next to this
-file) and a rewritten, simplified card has already gone wrong once: it had no drag handle, no minimize button and
-no copy icon. Use the file in two calls:
-
-1. Set the options on the browser context (this call only sets data):
-   ```js
-   async (page) => {
-     page.context().__handoffCfg = {
-       message: '<what the user does, one sentence>',
-       copy: [],                  // texts to type, e.g. ['[asrun] published document']
-       doneText: null,            // text that appears when finished, or null
-       maxMs: 600000,
-     };
-     return 'cfg set';
-   }
-   ```
-2. Run the card and wait: `browser_run_code_unsafe` with `filename` set to the absolute path of
-   `<framework>/.claude/skills/exploring-cases/references/handoff-card.js` (use the absolute path of the repository, a
-   relative one is resolved against the workspace root, which may be the parent folder). It returns `{outcome: 'done' | 'skip' | 'condition' | 'timeout', waitedMs}`.
-
-Check once, after the card shows, that it looks right: take a screenshot and see a title bar with a move icon, a
-chevron button at its right and, when `copy` is not empty, a line per text with a copy icon. If not, stop and report
-it; do not hand off with a broken card.
-
-Tell the user in the chat (the terminal or the UI job log) as well: "Your turn in the browser window: <task>. Press
-Done on the card (bottom-left; drag it if it is in the way) when you finish." When the run was started from the web
-UI, the UI notices the handoff by itself (it sees the `__handoffCfg` call and the `handoff-card.js` call) and shows the
-"Your turn" badge, a count in the tab title and, if the person switched notifications on, a browser notification;
-this is why the message in `__handoffCfg` must be a plain string literal. A macOS notification is a bonus and may
-fail in a sandbox: `osascript -e 'display notification "<task>" with title "AsRun" sound name "Glass"'`. If it
-fails, go on.
-
-## Finish condition
-Pick one that the page can show, before the handoff, and write it into the message of the card:
-- a text that appears (a "Saved" toast, the title of the next step) or one that goes away;
-- a URL that the page reaches;
-- an element that appears or disappears (an editor that closes).
-
-The Done button is always there (also on the minimized card) as the fallback, and "Cannot do this" lets the user give up a step.
-
-## After the handoff
-- The card turns green and says control is back ("Done: control is back with Playwright. Do not touch the page.")
-  for two seconds before it is removed, so the user knows when they may let go.
-- `outcome: 'timeout'` or `'skip'`: do not guess. Write a `TODO [blocking]` under the step and go on with what does
-  not depend on it.
-- Take a snapshot and write down what the user did (see "Recording"), then continue read-only.
-- At the end of the exploration hand off once more when the user created data: "Delete the [asrun] items you
-  created, then press Done". The case must clean up after itself, and so must the exploration.
-
-## Recording
-Between the start and the end of a handoff the agent records what the user does (`browser_start_recording`,
-`browser_stop_recording`). The recorded Playwright code is **raw material, never saved as it is**. It is turned into
-a general recipe and written into the case under `## Inputs` (format below). The recipe holds what the user did in
-words, plus the **labels and roles of the controls** they used ("the textbox 'Title'", "the button 'Next'"),
-because `/gen-spec` cannot write data and so cannot see those controls itself. It never holds selectors, ids or the
-names of data that can change.
-
-Make the recipe as general as possible, because lists and data change:
-- **A choice from a list that can change** (items, search results, a contact list): record the position, never the
-  name or id. "Select items #1 to #3 from the list."
-- **Random is allowed only when the user asks for it** ("pick any 3"). The default is the position, because it can be
-  repeated. A random pick must be written into the test's annotations when the spec runs.
-- **Text the case creates**: `[asrun] <something>`.
-- **A value that has to exist** (an existing name, a search term): write what it must be like ("a name that
-  returns a result") and the observed value as `(observed "<value>", 🔍 to be confirmed by QA)` plus a
-  `[non-blocking]` TODO block. Do not put a brittle literal in as the only truth.
-- **Nothing that depends on the pick** may become an assertion (a total changes with the items). Say so in a
-  TODO when a check would.
-- Settings that the user changed on purpose (a toggle, a template) are recorded as they were set, by label.
-
-If the recording tool fails or returns nothing, describe what the user did from before/after snapshots instead.
-
-## The `## Inputs` section of a case
-One bullet per `[input]` step, in step order. The step number is the key the spec generator uses.
-
-```
-## Inputs
-- Step 3 (start): search for an existing document and pick result #1 (observed search term "...", 🔍 to be confirmed by QA).
-  - ❓ TODO [non-blocking]: Is any result that opens fine as the starting point? (seen on example-staging)
-    - ✍️ Answer:
-- Step 3 (items): select 3 items by position (#1 to #3) from the list.
-- Step 3 (finish): press "Next" until the "Publish" button shows, then publish.
-```
-
-A step that is marked `[input]` and has no bullet here has never been explored. `generating-specs` stops on it.
-
-## Hard rules
-- Never write data yourself, never press a button that writes. In production the same, with no exception.
-- Never wait in an unattended run.
-- Never ask a person to log in, pass 2FA or send email through the handoff.
-- Never save selectors, ids or the names of changing data into a case. Control labels and roles are fine.
-- Never read or print anything under `.auth/`.
+# User handoff: a person works in the browser, the agent waits
+
+Used by `exploring-cases` (and by `making-cases` never: it does not open a browser). `generating-specs` never hands
+off; it replays the step recipes that an exploration recorded.
+
+## The rule
+**An agent never writes data.** Not in staging, not in production. Every step that creates, edits, publishes, shares,
+deletes or otherwise changes data, and every step that needs a human's choice (an existing document, items, a contact
+name), is done by the user in the browser window that Playwright opened. Writing is rare (only while preparing a
+case) and a person succeeds where an agent guesses. The agent drives only what is read-only: open, look, read,
+hover, switch tabs, open and close dialogs and menus.
+
+The runtime permission is a different thing and stays as it is: `writes: [<env>, ...]` in the case front matter says
+where the finished spec may write, and a human confirms a run in any environment except staging.
+
+## When a handoff happens
+Only in an attended run (`--attended`, a person is at the machine, the browser window is visible). A step is a
+handoff when it is marked `[input]` or `[writes]` in the case, or when the agent finds out while exploring that the
+next action would write data or needs a choice.
+
+Without `--attended` the agent does not wait. It writes a `TODO [blocking]` under that step ("a person has to
+perform this step; run /explore-case with --attended") and goes on with the rest. Never wait for a person in a run
+that nobody watches.
+
+## Before the handoff
+1. Say what the user has to do and when it is finished, in one or two sentences ("Fill in the form, pick two
+   items, then press Done"). Name the finish condition first (below).
+2. Put every text the user has to type into `copy` (the `[asrun] ...` name of a document, a title), so it can be
+   copied with one click.
+3. Never ask the user to send email (production: never; other environments: only when `email` is `true` for the
+   profile). Never ask for login or 2FA. Name everything the user creates `[asrun] <something>`.
+4. Start recording with `browser_start_recording` (see "Recording").
+
+## The wait loop
+Run it with one `browser_run_code_unsafe` call. A single call may wait for minutes (verified: 150 s without a
+timeout), so no polling from outside is needed. The loop:
+
+- **Shows a small floating card, not a bar.** It sits in the bottom-left corner and only the card takes clicks, so
+  nothing of the page is covered or blocked. The user can **drag** it by its title bar and **minimize** it to a small
+  pill that still has a Done button. Position and minimized state survive a page reload (kept in `sessionStorage`).
+- **Click to copy.** Every text in `copy` (for example the `[asrun] ...` name the user has to type) is shown on its
+  own line with a copy icon; one click puts it on the clipboard and the icon shows "Copied". Pass only text that the
+  case says to type; leave `copy` empty when there is none.
+- **Resets the flag first**: `window.__handoff = null` on every page it paints. A flag left over from an earlier
+  handoff ends the wait at once.
+- **Paints the card on every open tab** and repaints after navigation (a new page has no card). The document
+  editor opens in a new tab, so the loop looks at `context.pages()`, not only at the first page.
+- **Stops** when one of these happens, whichever is first: the user presses Done or "Cannot do this" on the card
+  (`window.__handoff` is `'done'` or `'skip'`), or the finish condition holds, or the time is up (default 10 minutes).
+- **Ends visibly**: the card turns green and says control is back for two seconds, then it is removed, and the tab
+  titles are restored.
+- The card lives in a Shadow DOM (the site's CSS cannot change it), does not take keyboard focus (the user can keep
+  typing in the page) and works even when the page locks all clicks behind a modal. The icons are inline SVG because
+  the card is injected into the page under test; the web UI's react-feather rule does not apply to it.
+
+**Never write this code yourself and never shorten it.** It lives in `references/handoff-card.js` (next to this
+file) and a rewritten, simplified card has already gone wrong once: it had no drag handle, no minimize button and
+no copy icon. Load that file in two calls:
+
+**Two calls, every time.** Set the options with their own call and only then run the card, for every handoff,
+including a second one later in the same run. Never reuse the options of an earlier handoff and never change them
+inside the call that runs the card: OpenCode reports a tool call only when it ends, so the options call is the only
+way the web UI can see that a person is needed while the card waits. With the card alone there is no "Your turn"
+badge, no count in the tab title and no notification (a HINT in the job log says so).
+
+1. Set the options on the browser context (this call only sets data):
+   ```js
+   async (page) => {
+     page.context().__handoffCfg = {
+       message: '<what the user does, one sentence>',
+       copy: [],                  // texts to type, e.g. ['[asrun] published document']
+       doneText: null,            // text that appears when finished, or null
+       maxMs: 600000,
+     };
+     return 'cfg set';
+   }
+   ```
+2. Run the card and wait: `browser_run_code_unsafe` with `filename` set to the absolute path of
+   `<framework>/.claude/skills/exploring-cases/references/handoff-card.js` (use the absolute path of the repository, a
+   relative one is resolved against the workspace root, which may be the parent folder). It returns `{outcome: 'done' | 'skip' | 'condition' | 'timeout', waitedMs}`.
+
+Check once, after the card shows, that it looks right: take a screenshot and see a title bar with a move icon, a
+chevron button at its right and, when `copy` is not empty, a line per text with a copy icon. If not, stop and report
+it; do not hand off with a broken card.
+
+Tell the user in the chat (the terminal or the UI job log) as well: "Your turn in the browser window: <task>. Press
+Done on the card (bottom-left; drag it if it is in the way) when you finish." When the run was started from the web
+UI, the UI notices the handoff by itself (it sees the `__handoffCfg` call and the `handoff-card.js` call, whether the
+browser tool is called directly or through the CLI's code mode, as OpenCode's `execute` tool does) and shows the
+"Your turn" badge, a count in the tab title and, if the person switched notifications on, a browser notification;
+this is why the message in `__handoffCfg` must be a plain string literal. A macOS notification is a bonus and may
+fail in a sandbox: `osascript -e 'display notification "<task>" with title "AsRun" sound name "Glass"'`. If it
+fails, go on.
+
+## Finish condition
+Pick one that the page can show, before the handoff, and write it into the message of the card:
+- a text that appears (a "Saved" toast, the title of the next step) or one that goes away;
+- a URL that the page reaches;
+- an element that appears or disappears (an editor that closes).
+
+The Done button is always there (also on the minimized card) as the fallback, and "Cannot do this" lets the user give up a step.
+
+## After the handoff
+- The card turns green and says control is back ("Done: control is back with Playwright. Do not touch the page.")
+  for two seconds before it is removed, so the user knows when they may let go.
+- `outcome: 'timeout'` or `'skip'`: do not guess. Write a `TODO [blocking]` under the step and go on with what does
+  not depend on it.
+- Take a snapshot and write down what the user did (see "Recording"), then continue read-only.
+- At the end of the exploration hand off once more when the user created data: "Delete the [asrun] items you
+  created, then press Done". The case must clean up after itself, and so must the exploration.
+
+## Recording
+Between the start and the end of a handoff the agent records what the user does (`browser_start_recording`,
+`browser_stop_recording`). The recorded Playwright code is **raw material, never saved as it is**. It is turned into
+a general recipe and written under the step as `- Recipe (phase): ...` lines (format below). The recipe holds what the
+user did in words, plus the **labels and roles of the controls** they used ("the textbox 'Title'", "the button
+'Next'"), because `/gen-spec` cannot write data and so cannot see those controls itself. It never holds selectors,
+ids or the names of data that can change.
+
+Make the recipe as general as possible, because lists and data change:
+- **A choice from a list that can change** (items, search results, a contact list): record the position, never the
+  name or id. "Select items #1 to #3 from the list."
+- **Random is allowed only when the user asks for it** ("pick any 3"). The default is the position, because it can be
+  repeated. A random pick must be written into the test's annotations when the spec runs.
+- **Text the case creates**: `[asrun] <something>`.
+- **A value that has to exist** (an existing name, a search term): write what it must be like ("a name that
+  returns a result") and the observed value as `(observed "<value>", 🔍 to be confirmed by QA)` plus a
+  `[non-blocking]` TODO block. Do not put a brittle literal in as the only truth.
+- **Nothing that depends on the pick** may become an assertion (a total changes with the items). Say so in a
+  TODO when a check would.
+- Settings that the user changed on purpose (a toggle, a template) are recorded as they were set, by label.
+
+If the recording tool fails or returns nothing, describe what the user did from before/after snapshots instead.
+
+## Recipe lines under a step
+One or more `- Recipe (phase): ...` lines directly under the `[input]` or `[writes]` step they belong to, indented by
+four spaces. The phase is optional (`start`, `items`, `finish`, ...). The step is the key; there is no step number to
+keep in sync.
+
+```
+3. Select an existing document and pick 3 items. [input]
+    - Recipe (start): search for an existing document and pick result #1 (observed search term "...", 🔍 to be confirmed by QA).
+      - ❓ TODO [non-blocking]: Is any result that opens fine as the starting point? (seen on example-staging)
+        - ✍️ Answer:
+    - Recipe (items): select 3 items by position (#1 to #3) from the list.
+    - Recipe (finish): press "Next" until the "Publish" button shows, then publish.
+```
+
+A step that is marked `[input]` or `[writes]` and has no `- Recipe:` line has never been explored. `generating-specs`
+stops on it, and `pnpm case:check` warns about it.
+
+## Hard rules
+- Never write data yourself, never press a button that writes. In production the same, with no exception.
+- Never wait in an unattended run.
+- Never ask a person to log in, pass 2FA or send email through the handoff.
+- Never save selectors, ids or the names of changing data into a case. Control labels and roles are fine.
+- Never read or print anything under `.auth/`.