tinybeeai 0.0.0-stage → 0.16.1

package/docs/STAGES.md

@@ -0,0 +1,619 @@
+# Dot stages: build design
+
+A dot today is one worker that does every QA job for its repo and tracker. This design gives each dot a small team of specialists, one per step from ticket to production, and lets each one pass its notes to the next. Think of a relay race where the baton is the ticket: the analyst reads it, the designer writes the tests, the reviewer runs them on the pull request, the regression runner runs them again after the merge, and the guard reports whether the release is covered.
+
+Scope: Linear KAT-130 (dot stages, the new Test designer) and the use of the KAT-131 stage avatars. No code changes with this document; section 10 lists the work. Code references are to `duonghaijoe/localdost` at `a2f2ece` (2026-10-08). The generated Playwright engine is in PR #9 (`kat-93-playwright-gen`), and the repo sets, links, and traceability design is [MULTI-REPO.md](MULTI-REPO.md) (PR #7). Section numbers such as "MULTI-REPO 4.6" point there. Names from PR #9 (`src/runner/pwgen`, `runner.engine`, `runner.pwgen`, `QaEngine`, `pwgen.maxSpecs`) are contracts of that open PR and are not on `main` yet; the tasks that use them wait for its merge.
+
+## Contents
+
+1. One dot per product area
+2. Stages and the code they wrap
+3. Test designer
+4. Handoff data model
+5. Rules, model, and toggles per stage
+6. Migration from role presets
+7. Ticket timeline on the dot page
+8. Stage avatars
+9. Cost bounds and edge cases
+10. Build tasks
+
+---
+
+## 1. One dot per product area
+
+### 1.1 Decision
+
+Huy asked on 2026-10-08 whether localdost should run one dot per role or one large dot. The recommendation in KAT-130, which stands unless Huy objects, is one dot per product area that runs specialist stages with handoffs.
+
+| Option | What breaks | Decision |
+|---|---|---|
+| One dot per role (six dots for one area) | The ticket, its test cases, the PR, and the results cross four dots. Each dot re-reads the ticket, the user writes six briefs, and the Inbox shows six names for one feature | Rejected |
+| One dot for the whole product | One brief and one rule set must cover checkout and the admin console alike. The dot's status color says nothing about which area is in trouble | Rejected |
+| One dot per product area, with stages | Context stays inside one dot from ticket to production. Each stage has its own rules, model, and on/off switch. Status reads per area | Chosen |
+
+Update 2026-10-22 (KAT-405). Huy chose one dot per job for the QA team: Ticket Reviewer (Ticket analyst and Test designer, tracker `katalon-studio/product`, label `pod:agentic`), PR Reviewer (Change reviewer, the four pod app repos), Regression Runner (Regression runner, the Tests repo and the deploy wait) and Site Watcher (Prod watcher, a site check on the QA tenant). The objection above, that the ticket, its cases, the PR and the results cross dots, is answered by one more dot, the Lead QA dot: it holds no repos, tracker or site of its own and names its member dots, so the context crosses dots through its member list. The lead shows team health, writes one daily team digest, answers questions about every member, lets the members share the test cases of a ticket, keeps one Inbox item for one bug, and gives the release call. Design and build spec: [LEAD-DOT.md](LEAD-DOT.md). A dot per product area with stages stays valid for a team that wants it, and a lead can name those dots too.
+
+### 1.2 What an area is
+
+A dot's area is the union of four scopes it already holds or will hold:
+
+- Repos: the dot's repo set with roles (MULTI-REPO 1.2) and `pathFilters` per repo.
+- Tracker: Jira project keys, Linear team keys, or GitHub Issues repos, labels, issue types, and milestones (`Watch.tracker`, `GithubTracker`).
+- Production: `probes` and `statusPages`.
+- People: the brief (`mission`, `notifyWhen`, `mustNot`) and the Slack channel.
+
+Two dots can share a repo by area: `watchMatches` in `src/webhooks.ts` applies `pathFilters` (KAT-160), so a PR or push matches when one changed file falls inside them.
+
+---
+
+## 2. Stages and the code they wrap
+
+Five of the six stages exist today as flows. A stage is a name, a set of job kinds, an avatar, and a config block on the dot. The flows keep their code; the stage layer adds routing, rules, model choice, and handoffs around them.
+
+| Stage | Avatar | Trigger | Job kind | Code today | Output today |
+|---|---|---|---|---|---|
+| Ticket analyst | lens | `ticket_created`, `ticket_updated` | `ticket_review` | `src/flows/ticketReview.ts`: `llm.score`, `SCORE_FLOOR` 30, code search by `keywords()`, `analyze({ task: 'ticket_review' })`, timeline links through `recordIssueTimeline` | `Verdict` with `openQuestions`, `findings`, `testIdeas`; a `ticket_comment` through the gate; the run report saves as a `test_plan` page (`reportKindForRun`) |
+| Test designer | penn | Handoff from the analyst; on demand | `test_design` (new) | None. Section 3 | Test cases linked to the ticket, a `test_plan` page per ticket |
+| Change reviewer | nit | `pr_opened`, and `ci_failure` on an open PR head | `pr_check`, `ci_failure` | `src/flows/change.ts` `checkChange(job, 'pr_check')`, `src/review/*` (QA review and verifier), `src/flows/ticks.ts` (checklist ticks), `src/runner/aivision`, `src/runner/pwgen` (PR #9), `src/links.ts` `recordPrLinks` | Check run, sticky PR comment, push, `file_defect` drafts (`src/flows/defects.ts`) |
+| Regression runner | echo | `pr_merged`, `push` to the default branch, and `ci_failure` elsewhere | `post_merge`, `ci_failure`, `rerun`, `repo_scan`, `nightly_run` | `checkChange(job, 'post_merge')`: reuses the PR review at the same head (`findReviewedRun`), `scopeSpecs` widens the spec pick; `src/flows/rerun.ts`; `src/flows/nightlyRun.ts` (the scheduled Tests repo run, [SETUP.md](SETUP.md#nightly-test-run)); `src/deploy-wait.ts` holds a merge job until its commit is deployed, when the dot sets `waitForDeploySec` ([SETUP.md](SETUP.md#waiting-for-the-deploy)) | Check run on the merge commit, push, `file_defect` drafts, release-note lines for the digest and the Release notes page ([API-V2.md](API-V2.md#release-notes-kat-391)) |
+| Prod watcher | argus | `probe_down`, `statuspage`, `probe_up` | `outage`, `recovery` | `src/monitor/probes.ts` (third failure queues `outage`), `browser-probe.ts`, `statuspage.ts`, `src/flows/outage.ts` (blames merges of the last 24 h), `src/flows/recovery.ts` | Urgent push, Slack notice, `incident` report page |
+| Release guard | ward | Schedule, milestone due date, on demand | `release_check` (new) | Builds on `links` (`LinkRecord`), per-issue test status and the traceability view (MULTI-REPO 4.6, 4.7), `releaseNotesLines` in `src/flows/digest.ts` | A `readiness` report page per milestone |
+
+The daily digest (`digest`) stays a dot-level job with no stage, since it summarizes every stage. A `rerun` takes the stage of the run it reruns. A `ci_failure` takes the Change reviewer when the failed head is the head of an open PR the dot checked, else the Regression runner.
+
+The stage keys are the ones `client/src/ui/mascotArt.ts` already defines for the avatars: `analyst`, `designer`, `reviewer`, `regression`, `watcher`, `guard`. Task 1 (built, KAT-159) moved `StageKey` into `src/types.ts`; the client imports it from `@shared`.
+
+```ts
+// src/types.ts (add only)
+
+export type StageKey = 'analyst' | 'designer' | 'reviewer' | 'regression' | 'watcher' | 'guard';
+
+export interface RunRecord {
+  // existing fields unchanged
+  /** Stage that ran this job. Unset on runs from before stages and on the digest. */
+  stage?: StageKey;
+}
+```
+
+Built in KAT-159: `src/stages/index.ts` holds the registry (`STAGES`, `STAGE_KEYS`, `stageFor(kind)`, `runStage(run)`; the client reaches it through the `@stages` alias). `stageFor` takes the job kind only and maps `ci_failure` to the Regression runner; the open-PR-head split and `ev`/`rerunOf` arguments below are not built yet. `startRun` copies `stage` from the source run on a rerun. `runStage` falls back to `stageFor(kind)` for rows without `stage`, and `/api/feed` and `/api/runs/:id` return `stage`. The registry design: the stage label, its avatar name, its default config, and `stageFor(kind, ev, rerunOf)`. A fixed map from job kind to stage cannot serve `ci_failure` and `rerun`, so `stageFor` reads the event and the source run: `ci_failure` checks whether `ev.ci.headSha` is the head of an open PR the dot checked, and `rerun` copies `stage` from the run named in `rerunOf`. Every other kind maps one to one. `startRun` sets `stage` from `stageFor`, so every run, approval, and Feed row knows its stage without new queries.
+
+The Lead QA dot (KAT-405) answers "can we release <milestone>?" with `releaseCall` in `src/lead-release.ts`: Ready, Ready with risk or Not ready, built by code from the rows of its members, read only, with readiness words and never "release" or "hold". The Release guard of task 12 stays as planned for a single dot. When it lands, its readiness rules call `releaseCall` for a lead's milestone, so a dot and a lead never give two answers for one milestone, and the rule that the guard never says release or hold stays.
+
+Two new job kinds, `test_design` and `release_check`, join `JobKind` in the tasks that build their flows (tasks 6 and 12), never earlier. `JobKind` has exhaustive maps that must grow in the same PR: `KIND_LABEL` in `src/reports/build.ts` and in `client/src/features/runs/format.ts`, `reportKindForRun`, the queue handler registration, and `AnalyzeRequest['task']` with its prompt when the flow calls `analyze`.
+
+---
+
+## 3. Test designer
+
+### 3.1 Job
+
+The analyst says what to test in a few test ideas. The designer turns that into real test cases a person or a machine can run, links them to the ticket, and keeps them current as the ticket changes. When a PR later names the ticket, the Change reviewer runs those same cases.
+
+### 3.2 Input
+
+- The ticket: title, description, acceptance criteria, type, labels (`Ticket`).
+- The analyst's verdict for the same ticket revision: `testIdeas`, `openQuestions`, `findings`, and the `codeHits` it found.
+- The spec inventory of the dot's repos (`discoverSpecs` today; the profile specs of MULTI-REPO 2.3 once R2 lands), so the designer can point a case at a spec that already covers it.
+- The repo profile area that matches the ticket (MULTI-REPO 2.7, ticket review by area), when profiles exist: routes, flows, glossary.
+- The ticket's current cases, when this is an update.
+
+### 3.3 Output: one case, three forms
+
+Each case has a manual form, which always exists, and up to two executable forms.
+
+| Form | Written when | Runs where | Stored as |
+|---|---|---|---|
+| Manual | At design time | By a person, ticked in the sticky PR checklist or on the case | `TestCase.steps`, `expected`, `data`; rendered on the ticket's `test_plan` page |
+| AI-Vision | At design time for `e2e` cases | `src/runner/aivision` in `pr_check` and `post_merge` when `runner.aivision` is set | `TestCase.aivision` (`AiVisionCase`, `source: 'ticket'`, `itemId` = case id) |
+| Generated Playwright | Planned at design time; generated at the first change review that has a running app | `src/runner/pwgen` (PR #9) | `TestCase.playwright`: status, kept source, and later the repo path |
+
+The Playwright form waits for a running app because pwgen's explore step opens the app and records ARIA snapshots and `data-testid` values before it writes a spec. A new feature has no pages to explore until a PR builds it. The designer therefore writes the case as a plan item in the shape pwgen reads (`QaTestToRun`: scenario, steps, expected, data, priority, type), and generation happens in the first `pr_check` that names the ticket and has a preview URL or `baseUrl` (section 4.4).
+
+One exception: a bug ticket describes behavior that already exists. With `designer.reproduce` on, the designer runs the Playwright form against the dot's `baseUrl` at design time. A kept failing spec confirms the bug, posts a "Reproduced" step on the timeline, and becomes the regression test for the fix. A passing spec adds an open question ("Could not reproduce on <baseUrl>; which data or account shows it?"). Default off, because it runs a model-written spec against a shared environment.
+
+When an existing spec already covers a case, the designer sets `existingTest` to its path and writes no executable form.
+
+### 3.4 Case rules
+
+The designer's output passes script checks before it is stored, the same pattern as `check.ts` in the QA review. A failed check goes back to the model once with the numbered errors, then the case is dropped with the reason on the run.
+
+- Each case names what it covers: an acceptance criterion (quoted) or a test idea from the analyst. A case that covers nothing is dropped.
+- `expected` is observable: a value, a message, a page, a state. "Works correctly" and "no errors" fail the check.
+- No two cases share the same covers entry and the same steps.
+- A case that depends on an open question carries `waitsOn` with the question text and stays `draft` until the ticket changes.
+- At most `designer.maxCases` cases per ticket (default 8), must before should before could.
+- New cases go into a folder per ticket (KAT-382, `ticketFolder` in `src/case-folders.ts`): "PROD-123: Short title" under a top folder named after the tracker project ("PROD"); a GitHub issue gets "#12: Short title" under a folder named "owner/name". The title is cut at a word, at most 50 characters. A re-design finds the folder by its key ("PROD-123:" at the start of the name), wherever a person moved or renamed it, and makes none when it adds no case. The folder of a GitHub issue stores the issue's repo (`repo`, lower case, KAT-398) and is found by repo plus number, so a "#12" folder that a person moved into Archive is never reused for "#12" of another repo. An older folder with no repo is filled at boot from the keys of its cases; one that has no such case is taken only when it is the single candidate and sits in no other repo's folder, and the repo that takes it stamps it. Only the cases the designer stores now get the folder: a case a person moved stays where it is. When the folder cannot be made (the dot's 500 folder limit or the nesting limit), the case is stored unfiled and the design still succeeds.
+- Prompt safety follows the AI-Vision and pwgen rules (docs/SANDBOX.md): ticket text is untrusted, braces and doubled angle brackets in steps are neutralized, start URLs are paths.
+
+Evals (KAT-165): `test/fixtures/designer/<name>/` holds `ticket.json` (with the cases the dot already has), `review.json` (the analyst's handoff), and `expected.json` (the criteria a good set covers and the case limits). `src/review/designer-eval.ts` scores criteria coverage (an expected result names the criterion id or shares enough of its keywords), duplicates (the same normalized steps, or a repeat of an existing case), unobservable expected results (`VAGUE_EXPECTED`), and case count, and reports problems in the style of the dogfood cases. `npm test` scores the mock backend for every fixture with fixed thresholds (coverage at least 80%, no duplicates, no unobservable results) and spends no tokens. `npm run eval:designer -- --backend <name>` runs a real model on the same fixtures and is never part of CI.
+
+### 3.5 Updates
+
+A `ticket_updated` event re-runs the analyst, which hands off to the designer again. The designer receives the current cases and returns a revision: unchanged cases keep their ids, edited cases get a new `revision`, and cases that no longer fit become `retired`. A case with results is never deleted, so the timeline and the guard keep its history. Cases a person added or edited (`origin: 'user'`) are never retired or rewritten by the model; the designer may add a note next to them.
+
+### 3.6 The test plan page
+
+Each ticket gets one `ReportPage` of kind `test_plan`, titled "Test cases: SHOP-12 Guest checkout coupon". The case table is the source of truth and the page is rendered from it on every change. People edit cases in the case drawer on the dot page or through chat, where an edit shows as a proposal card with Apply and Dismiss. Free notes go on a child page (`parentId`). This avoids parsing Markdown edits back into cases.
+
+### 3.7 Rules for its actions
+
+Writing cases and the page stays inside localdost, so it needs no gate. Three outward actions do:
+
+| Action | Default | When |
+|---|---|---|
+| `ticket_comment` | `ask` | `designer.postSummary` on: one comment on the ticket with the case titles and a link to the page. Off by default |
+| `open_pr` | `act_when_asked` | Kept generated specs proposed into the repo, as pwgen does today (PR #9, Proposing specs) |
+| `mcp_tool` | `ask` | Later: sync cases to a test management tool such as Katalon True Platform through an MCP connection |
+
+### 3.8 Impact on existing tests (KAT-304)
+
+A new story can change what a test the team already has should show. The designer in 3.5 only reads the cases linked to the ticket, so it never sees that an old case, written for another ticket, now expects the wrong value. After every ticket review the dot therefore checks the tests it already has, whichever ticket they came from. The check lives in `src/impact/` and `src/flows/impact.ts`, and runs inside the `ticket_review` flow before the review comment is drafted, so the comment can list the specs to update. It is best effort: a failure leaves a warning step and the review goes on.
+
+**1. Find candidates** (`src/impact/find.ts`, no model call). A candidate is a case or a spec that may be about the same behavior as the ticket.
+
+| Signal | Cases | Specs |
+|---|---|---|
+| Shared requirement | The case links the ticket, a ticket its text names, or a ticket linked to it | A spec title or comment names one of those tickets |
+| Folder or suite | The case sits in a folder, or is in a suite, whose name the ticket uses (a folder "Checkout" for a ticket about checkout), and shares a word with the ticket | |
+| Shared words | The title and steps share three words with the ticket, or two when they are a third of the title | The spec title shares two words with the ticket |
+| Trace-map page | The case links a requirement on a page the ticket is about, or names a spec that tests it | The trace map's tests on those pages; the repo scan's specs that open a route the ticket names |
+
+A page counts as "about the ticket" when one of its requirements is the ticket or a ticket related to it, when the ticket names its route, or when its first path segment is a word of the ticket. The spec of every candidate case is a candidate too. Retired cases never count. At most 12 cases and 6 specs go on, best score first. The check counts the cases and specs that matched but were over the cap, keeps the count on the run (`impact.leftOut`), and says it after the summary line: "6 existing tests checked: 2 need an update, 4 are still valid. 3 more matched and were left out." The sentence is absent when nothing was left out.
+
+**2. Classify** (`src/impact/classify.ts`). One model call gets the ticket and all candidates, and answers per candidate:
+
+| Verdict | Meaning | Extra fields |
+|---|---|---|
+| `valid` | The ticket does not change what it checks, or the model cannot tell | `note` |
+| `update` | A value, rule, message, or step changes and the test stays useful | `ticketLine` (the line that causes it), all steps of the new version with expected results, `note` |
+| `obsolete` | The ticket removes or replaces the behavior | `ticketLine`, `note` |
+
+Every answer passes `settle()`, which never guesses: low confidence, a ticket line the ticket does not hold, steps that break the case rules (3.4), steps equal to the old ones, or no answer at all end as `valid` with a note. A spec is never obsolete; it needs an update. The mock backend uses a fixed rule instead of a model: a line that gives an old and a new value ("from 10% to 20%", "20% instead of 10%", "replace 10% with 20%") makes a case `update` when a step holds the old value, and the steps carry the new value. A line with a removal word ("remove", "retire", "replace", "no longer offered") that names most of a case's title words makes it `obsolete`. Anything else is `valid`, with low confidence when the ticket has fewer than 15 meaningful words.
+
+**3. Act** (`src/impact/store.ts`). Nothing is retired or rewritten on its own.
+
+| Verdict | What the dot does | Who decides |
+|---|---|---|
+| `update`, case | Writes a draft case version: the case as it is, with the new steps, linked to the new ticket as well. The case keeps its current version and history; a test run keeps pinning the current version | A person accepts it on the Test cases page or the ticket review (the draft becomes the next version, the old one stays in the history) or rejects it |
+| `obsolete`, case | Puts a `case_retire` draft in the Inbox. The kind always asks, whatever the dot's rules say (`effectiveLevel`); only `hand_off` is kept | A person approves (the case is retired, its results stay) or rejects it |
+| `update`, spec | Lists it under "Automated tests to update" in the ticket comment and the ticket review page | A person changes the spec in the repo, then marks it updated or dismisses it |
+| `valid` | Stores the row with its note | |
+
+A flagged case shows **Needs review** in test runs (run item rows and the item sheet) and in the case table until the draft is decided, or the Inbox draft is rejected or expires. An accepted row is never reopened by a later review of the same ticket. A rejected row stays rejected while the ticket text (title, description, acceptance criteria) hashes the same as the text the row was checked against (`ticketHash`); when the ticket text changed, the next review checks that test again and may draft again. An open flag is not replaced by a later "still valid".
+
+**4. Report.** The ticket comment gets two headings when something is flagged: "Existing test cases to review" and "Automated tests to update" (each spec as a titled link to the file). The run page shows an "Existing tests" section and the Test cases page shows the same list (filtered by the ticket when the requirement filter is set; otherwise the rows that wait for a person). Each row is a status icon and word (Needs update, Obsolete, Still valid, then Accepted, Rejected, Retired, Updated, Dismissed, Not decided), the case or spec and the ticket as titled chips, and the ticket line that causes the change. The PR review lists a spec under Tests to update when a PR for the ticket (a PR that closes or references it, as the traceability links hold) does not change the spec: "Update the test <title> for SHOP-40: ..." with "This PR does not change that test." under it. Ticking it on GitHub records like any other checklist item.
+
+The data is in [DATA-MODEL.md](DATA-MODEL.md) section 2.3 (Impact row). Evals: `test/fixtures/designer/impact/` holds four stories (a coupon rule changes, a feature is removed, an unrelated story, a vague story), run by `test/impact.test.ts`.
+
+---
+
+## 4. Handoff data model
+
+### 4.1 The chain
+
+```text
+Ticket SHOP-12
+   |  tests (source designer)
+   v
+Cases tc_a .. tc_f  ----------------------------+
+   |  PR #58 names SHOP-12 (closes / references)  |
+   v                                              |
+pr_check run  -> case_results (engine, result)    |
+   |  merge                                       |
+   v                                              |
+post_merge run -> case_results                    |
+   |  failed on both retries                      |
+   v                                              |
+Defect SHOP-31  -- defect link (meta caseId) ---->+
+```
+
+Every edge already has a home or gets one small addition:
+
+| Edge | Stored in | Status |
+|---|---|---|
+| PR to ticket | `links`, kinds `closes` and `references` (`recordPrLinks`) | Exists |
+| Issue to issue | `links`, kinds `references`, `parent`, `blocks` (`recordIssueTimeline`) | Exists |
+| Case to ticket | `links`, kind `tests`, new source `designer` | New source value |
+| Run to case | `case_results` table | New |
+| Defect to ticket | `links`, new kind `defect`, `meta: { caseId, runId }` | New kind |
+| Run to stage | `RunRecord.stage` | New field |
+
+Refs follow `LinkRecord`: lower-case `owner/name#N` for GitHub, the key for Jira and Linear. A case ref is `case:<id>`.
+
+### 4.2 Types
+
+```ts
+// src/types.ts (add only)
+
+export interface TestCase {
+  id: string;                    // tc_<12 hex>
+  watchId: string;
+  ticketRef: string;             // same form as LinkRecord refs
+  title: string;
+  type: QaTestType;              // e2e | integration | unit | manual | exploratory
+  priority: QaPriority;          // must | should | could
+  /** Acceptance criteria (quoted) or analyst test ideas this case checks. */
+  covers: string[];
+  preconditions?: string;
+  steps: string[];
+  expected: string;
+  data?: string;
+  /** An existing spec covers it: "path" or "owner/name:path". No executable form is written. */
+  existingTest?: string;
+  aivision?: AiVisionCase;
+  playwright?: {
+    status: 'planned' | 'kept' | 'discarded' | 'proposed' | 'in_repo';
+    /** Kept source, until the spec lives in the repo. */
+    source?: string;
+    /** Repo path once a proposal merged. */
+    path?: string;
+    reason?: string;
+    generatedInRun?: string;
+  };
+  status: 'draft' | 'active' | 'retired';
+  origin: 'designer' | 'user' | 'reviewer';
+  /** The open question this case waits on. */
+  waitsOn?: string;
+  revision: number;
+  /** The ticket's test_plan page. */
+  reportId?: string;
+  designRunId: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface CaseResult {
+  id: string;
+  caseId: string;
+  runId: string;
+  stage: StageKey;
+  /** QaEngine from PR #9 ('spec' | 'playwright' | 'aivision'), or a person's tick. */
+  engine: QaEngine | 'manual';
+  result: 'passed' | 'failed' | 'flaky' | 'skipped' | 'not_run';
+  prRef?: string;
+  sha?: string;
+  at: string;
+}
+
+export interface LinkRecord {
+  kind: /* existing */ | 'defect';
+  source: /* existing */ | 'designer' | 'defect';
+}
+
+export interface QaTestToRun {
+  // existing fields unchanged
+  /** The ticket case this item runs. Set by the reviewer for behavior a case already covers. */
+  caseId?: string;
+}
+```
+
+Tables in `src/db.ts`: `test_cases` (one row per case, latest revision) and `case_results` (append only, indexed by `caseId` and `runId`).
+
+### 4.3 How a handoff happens
+
+A handoff is a queued job with a marker in its payload. `handoff(from, to, subject)` in `src/stages/index.ts`:
+
+1. Skips when the target stage is off for the dot, and writes "Test designer is off; the Change reviewer uses the analyst's test ideas" on the source run.
+2. Enqueues the target job with `payload.handoff = { from, runId, ticketRef, revision }` and dedupe key `handoff:<to>:<ticketRef>:<revision>`, so one ticket revision gets one design.
+3. Adds a step on both runs: "Handed to Test designer" and "From Ticket analyst".
+
+| From | To | When | What passes |
+|---|---|---|---|
+| Ticket analyst | Test designer | The review finished at or above `SCORE_FLOOR` | Ticket ref and revision, the analyst run id (its verdict holds ideas, questions, code hits) |
+| Test designer | Change reviewer | A `pr_check` names the ticket: `ticketKeysIn(ev)` or a `closes` link | Active cases of each named ticket, read from `test_cases` at run time |
+| Change reviewer | Regression runner | The PR merges | The PR review at the same head (`findReviewedRun`, exists) and the cases it ran |
+| Regression runner | Release guard | Every `post_merge` and every defect | `case_results` and `defect` links, read at check time |
+| Prod watcher | Release guard | An outage on a dot with an open milestone | The incident page, listed on the readiness report |
+
+The first handoff queues a job. The others are reads at run time: the Change reviewer looks up cases when a PR names a ticket, and the guard reads results when it runs. This keeps stages independent: turning one off never leaves a queue of handoffs waiting for it.
+
+### 4.4 Change reviewer reuse
+
+When a PR names tickets that have cases:
+
+- The reviewer input gets a `<ticket_cases>` block: id, title, type, steps, expected, and the executable forms. For behavior a case already covers, the reviewer cites the case by `caseId`. A check flags a `whatToTest` item that repeats a case's covers entry without the `caseId`.
+- Cases with `existingTest` or a Playwright form `in_repo` join the spec pick (`selectQaSpecs`).
+- A Playwright form `planned` goes to pwgen as a plan item, ahead of review items, within `pwgen.maxSpecs`. A `kept` form runs from its stored source through pwgen's spec runner without a new model call, after the spec safety checks run again on that source. A kept spec that later fails for its own reason (a locator drifted) gets pwgen's single heal, which may not change expected values.
+- AI-Vision forms replace the ticket's raw test ideas in `planAiVisionCases`. `ticketIdeasFor` stays the fallback for tickets with no cases.
+- Built (KAT-166): for each ticket the event names, `planAiVisionCases` writes one `AiVisionCase` per draft or ready case (never retired), ready before draft, then must before should before could, inside `maxCases`. Each action becomes an `ai` step and each expected result an `aiAssert` step. The case id is the AiVisionCase id and `itemId`, so the result file `aivision/<case id>.yaml` links back through `linkRunResults` as a result with engine `aivision`, and the case shows it as its latest result. A ticket with no draft or ready case keeps its raw ideas.
+- Manual cases appear in the sticky comment checklist under "From SHOP-12". A tick by someone with write access (`applyChecklistEdit`) writes a `manual` case result.
+- `runner.engine` (PR #9) still decides which engine runs an item without an existing spec: `auto`, `playwright`, `aivision`, or `both`.
+- Every result for a case-backed item writes a `case_results` row.
+
+A PR that names several tickets runs their cases up to `reviewer.maxTicketCases` (default 12), must first, spread across tickets.
+
+---
+
+## 5. Rules, model, and toggles per stage
+
+### 5.1 Config
+
+```ts
+// src/types.ts (add only)
+
+export interface StageConfig<O = Record<string, never>> {
+  enabled: boolean;
+  /** Overrides Watch.rules for actions this stage drafts. */
+  rules?: Partial<Record<ActionKind, RuleLevel>>;
+  /** Unset: the workspace backend and the stage's default tier. */
+  model?: { backend?: 'claude-cli' | 'codex-cli' | 'anthropic'; tier?: 'main' | 'fast' };
+  /** Added after the dot's instructions, for this stage only. */
+  instructions?: string;
+  options?: O;
+}
+
+export interface Watch {
+  // existing fields unchanged
+  stages?: {
+    analyst?: StageConfig<{ scoreFloor?: number; maxQuestions?: number }>;
+    designer?: StageConfig<{ maxCases?: number; forms?: ('manual' | 'aivision' | 'playwright')[]; reproduce?: boolean; postSummary?: boolean }>;
+    reviewer?: StageConfig<{ maxTicketCases?: number }>;
+    regression?: StageConfig<{ caseScope?: 'merged_tickets' | 'none' }>;
+    watcher?: StageConfig;
+    guard?: StageConfig<{ milestones?: string[]; daysBeforeDue?: number; hour?: number }>;
+  };
+}
+```
+
+Existing settings stay where they are, because the types contract is add-only: `Watch.review` remains the Change reviewer's review options, `runner.engine`, `runner.pwgen`, and `runner.aivision` remain the run engines, and `probes`, `statusPages`, `probeIntervalSec` remain the Prod watcher's targets. The stage settings UI shows them under their stage.
+
+### 5.2 Toggles
+
+Jobs reach the queue on two paths, and both check the stage. Webhooks and the GitHub, Jira, and Linear pollers go through `dispatchTrigger`, which asks `stageFor` and, when that stage is off for the dot, queues nothing and returns `stage off: reviewer`. Probes and status pages call `enqueue` directly (`src/monitor/probes.ts` for `outage` and `recovery`, `src/monitor/statuspage.ts` for `outage`), so the Prod watcher toggle also lives there: the probe scheduler and the status page poller skip a dot whose watcher is off, and no probe checks run for it. The pollers keep their cursors, so turning a stage back on resumes from the present without replaying old events.
+
+### 5.2.1 Built (KAT-161, server side)
+
+`Watch.stages` is `Partial<Record<StageKey, { on: boolean; rules?: string }>>`, in `src/stages/config.ts`. This first build keeps the stage config to the switch and one block of rules text. The `model`, `instructions`, and `options` fields of 5.1 come with later tasks.
+
+- **Migration.** `migrateStages()` runs at boot after the repo migration. It fills only the keys a dot lacks, so it is safe to run again and never overwrites a saved choice. The derivation: a tracker turns the analyst and the designer on, a repo (or repo set) turns the reviewer and the regression runner on, probes or status pages turn the watcher on, and the guard stays off. A stage with no saved entry (a dot created after boot, before its first save) runs as it did before stages, except the guard, which stays off.
+- **Skip with a reason.** `dispatchTrigger` checks `stageOn` per dot. An off stage queues nothing, adds the reason `stage off: <stage>` to the result (`skipped`, and `reason` when every matching dot skipped), stores the trigger in an `events` row with `skipped` set (one row per delivery), and logs it. The probe scheduler and the status page poller skip a dot whose watcher is off and log it once per dot until the dot is saved again.
+- **Rules.** `renderWatch(watch, stage)` adds `rules for the <label> stage: ...` to the `<watch>` block of the prompt. Without an argument it takes the stage of the job running in that async context (a rerun takes the stage of its source run), so every prompt built inside a job gets its own stage's rules and no other. `mustNot` stays dot-level. Resolving the action level of `gate()` per stage (5.3) is not built.
+- **API.** `PATCH /api/dots/:id` and `POST /api/dots` accept `stages`. Keys must be stage keys, each entry an object with a boolean `on` and optional `rules` text up to 4000 characters; other fields are refused with a 400 and nothing is saved. A patch merges per stage, and a patch that leaves `rules` out keeps the saved rules. An empty `rules` string removes them.
+
+### 5.3 Rules
+
+`gate()` resolves a level in this order: `stages[stage].rules[kind]`, then `Watch.rules[kind]`, then `DEFAULT_RULES[kind]`. The stage comes from the run (`RunRecord.stage`). `mustNot` stays dot-level and binds every stage. Auto-review sees the stage name, so a draft from the guard is judged as a readiness report.
+
+| Stage | Actions it drafts | Defaults that differ from `DEFAULT_RULES` |
+|---|---|---|
+| Ticket analyst | `ticket_comment`, `push_notify`, `report_edit` | None |
+| Test designer | `ticket_comment`, `open_pr`, `mcp_tool` | None |
+| Change reviewer | `run_tests`, `check_run`, `pr_comment`, `push_notify`, `file_defect`, `open_pr` | None |
+| Regression runner | `run_tests`, `check_run`, `push_notify`, `slack_post`, `file_defect`, `revert` | None |
+| Prod watcher | `push_notify`, `slack_post`, `revert` | None |
+| Release guard | `report_edit`, `slack_post`, `push_notify`, `ticket_comment` | `report_edit: act` for its own readiness page |
+
+The guard reports coverage and results per requirement. Its wording follows the QA report style already in force: what was tested, what failed, what has no cases. It never says release or hold.
+
+### 5.4 Model per stage
+
+`getLlmFor(watch, stage)` replaces `getLlm()` in stage flows. It returns a cached instance per backend, so two stages on the same backend share one. The tier maps to the backend's main and fast model settings (`LOCALDOST_MODEL` and `LOCALDOST_FAST_MODEL`, the Claude CLI pair); a backend with one model setting ignores the tier. Demo mode keeps the mock backend for every stage.
+
+| Stage | Model calls | Default tier |
+|---|---|---|
+| Ticket analyst | `score` (fast), `analyze` | main |
+| Test designer | Design, one check round; pwgen generate and heal | main |
+| Change reviewer | QA reviewer, verifier, `analyze`, auto-review (fast) | main |
+| Regression runner | `analyze` | main |
+| Prod watcher | `analyze` for the suspected cause | main |
+| Release guard | One summary over deterministic counts | fast |
+
+`QaReviewPass` already records backend and model per pass; the stage name joins it so the eval and cost views split by stage.
+
+Built in KAT-162. `Watch.stageModels` holds one switcher-list id per stage (`claude-cli`, `codex-cli`, `claude-token`, `anthropic`), validated against the stage keys and those ids by `PATCH /api/dots/:id` (a stage sent as `null` is cleared, other stages stay). `getLlmFor(watch, stage)` in `src/agent/llm.ts` returns the stage's backend when it is set and ready, and the dot's default model (`getLlm()`) otherwise. The stage model never fails a job:
+
+- A model that is not signed in, is not on the list, or waits after a quota, spend cap, rate limit, or sign-in error falls back to the default, with a log line and a "Stage model unavailable" warn step on the run.
+- A stage model that fails with one of those errors in the middle of a call is marked unavailable (the same wait as the model guard) and the call runs again on the default.
+- Demo mode (the mock default) and a stage set to the default's own backend use the default.
+- Chat and the safety review (auto-review) always use the default. A call with no stage is `getLlm()`.
+- Call sites: ticket review, test design (the cases and the impact check), the change reviewer's PR review passes (`qaBackendForStage` in `src/review/run.ts`), the post-merge, CI-failure, and rerun verdicts, generated Playwright specs, and the outage verdict. The stage is the run's (`runStage`). The digest has no stage.
+- `RunRecord.model` holds the model of the last model call of the run as `backend/model` (for example `claude-cli/sonnet`, `anthropic/claude-sonnet-5-5`, `codex-cli/default`, `mock`). A guard fallback to another backend still shows as its own "Model fallback" step. The `model_calls` table (KAT-362, [Daily model cap](SETUP.md#daily-model-cap)) holds one row per answered call with the stage and the tokens a backend reported, which the Model use card of the dot page sums per stage.
+- No tier mapping yet: a stage picks a backend, and the backend uses its main model setting. The stage settings UI is built in KAT-171 (section 5.5).
+
+### 5.5 Built (KAT-171, stage settings UI)
+
+The dot dialog (Settings on the dot page) has a Stages section after Sources. Code: `client/src/features/stages/`.
+
+- **Rows.** One row per stage, in registry order: the stage avatar (64 px, off stages dimmed), the name, one sentence, and a labeled switch that reads On or Off. A visible Settings button opens the panel of the stage. A line under the sentence names the stage's own rules and its own model; a model that is not available on the server says so there too ("Not available. Uses the dot default."), because the stage then runs on the dot default. Nothing is disabled. An off stage keeps its panel editable, and the panel says the settings apply when the stage turns on. The stage names are h3 headings under the dialog's h2 title, and the settings groups inside a panel are h4. On a phone narrower than 381 px the Settings button and the switch move to a row of their own under the avatar and the text, so both keep their labels on one line.
+- **Panel.** Rules (text, up to 4000 characters, saved as `stages[stage].rules`), Model (the model list of Setup, default "Dot default"; saved as `stageModels[stage]`, `null` for the default), and the settings that belong to the stage. A model that is not available on the server shows a hint that the stage uses the dot default until it is, as the server does.
+- **Settings moved under their stage.** Change reviewer: the PR review options (`Watch.review`, saved with the dot; only the options a person changed are sent), the engine for new scenarios (`runner.engine`), and the AI-Vision switch. Prod watcher: probes, the probe interval, and status pages. The base URL moved to the Test runner section. The PR review card on Settings is gone, and the Test engines link on the dot page opens the dialog on the Change reviewer panel.
+- **Role sets the stages.** The Role picker is the only preset picker, because a role preset is a set of stages (6.3). Picking a role sets the six switches and keeps the rules and the model a person wrote for a stage; the note under the picker says when the switches moved. Product area is the first role. A new dot starts on it with all six stages on and an empty brief, and a click on the chosen role fills the brief in a create (an edit never re-applies its saved role). The stage list has one summary line, such as "3 of 6 stages are on: ...", and no picker of its own.
+- **Notice.** `migrateStages` sets `stagesNotice: 'offer'` on every dot that has not answered it and still has the Test designer or the Release guard off. That covers a dot with no stage settings and a dot whose settings the first stage migration (KAT-161) wrote. A dot made after the upgrade, through `POST /api/dots` (the quick New dot dialog, the full form, an API client), `localdost init`, `localdost seed`, or the demo seed, is born with `stagesNotice: 'dismissed'` and is never offered. A save that carries `stages` answers the offer for a dot that never had one, and leaves an open offer to the dialog. The dialog shows "New stages: Test designer and Release guard" (only the ones still off) with a Turn on button for each and Dismiss. Dismiss saves `stagesNotice: 'dismissed'` through `PATCH /api/dots/:id` at once, and shows the error in place when that fails. Turning a stage on changes the form, and the save then sends `dismissed` too, as does a save after the switches or a role left nothing to offer. A client may send only `dismissed`.
+- **Save.** Every stage goes in each save (`stages` with `on` and `rules`, `stageModels` with a model or `null`), through the dot update route and its validation. A save error shows in the dialog's error summary and the changes stay. A field error inside a closed panel opens that panel, and so does a server refusal that names a stage (`stages.<stage>...`, `stageModels.<stage>...`, or a `review:` option, which opens the Change reviewer). A refusal that names no stage opens nothing.
+- **Review options and a new repo.** The dot update route builds the saved review options from the dot as the save leaves it. A repo added in the same save as a changed review option keeps pull request review on (it is on by default for a dot with an app repo).
+
+---
+
+## 6. Migration from role presets
+
+### 6.1 What roles do today
+
+A role preset (`src/routes/roles.ts`: `qa-lead`, `release-guard`, `ticket-reviewer`, `prod-watcher`, `custom`) only seeds the brief, instructions, rules, mascot, and digest hour in the create dialog. Jobs are routed by configuration: any dot with a repo gets `pr_check` and `post_merge`, any dot with a tracker gets `ticket_review`, and any dot with probes gets `outage`. The `release-guard` preset, for example, runs post-merge suites; it has no readiness logic.
+
+### 6.2 Boot migration
+
+`migrateStages()` in `src/stages/index.ts` runs at boot and is safe to repeat. For each dot without `stages`, it writes stages from configuration, so behavior after migration equals behavior before:
+
+| Stage | On when |
+|---|---|
+| Ticket analyst | `tracker` is set |
+| Test designer | Never on migration |
+| Change reviewer | A repo is set |
+| Regression runner | A repo is set |
+| Prod watcher | `probes` or `statusPages` is non-empty |
+| Release guard | Never on migration |
+
+`Watch.role` stays as the preset label. Dots that predate the new stages get a one-time offer of them, built in KAT-171 as a notice in the dot dialog (section 5.5) rather than a row on the dot page. Rollback: an older build ignores `stages` and routes by configuration as before.
+
+### 6.3 Stage presets
+
+Presets become sets of stages with defaults. `RoleKey` has `product-area`, the first option in the create dialog and the default of the quick New dot dialog (its suggestion posts the Product area brief and all six stages on). `GET /api/roles` sends each preset with `defaults.stages`, which names all six stages, so applying a preset also switches the other stages off.
+
+| Preset | Stages on | Mascot |
+|---|---|---|
+| Product area (new) | All six | pip |
+| QA lead | Analyst, designer, reviewer, regression | pip |
+| Release guard | Regression, guard | nova |
+| Ticket reviewer | Analyst, designer | bolt |
+| Prod watcher | Watcher | moss |
+| Custom | None; the user picks | pip |
+
+Each preset keeps today's brief text and rules. Product area reuses the QA lead brief and rules with one more clause for production. Stage-level rules are not built: the stage `rules` field is text for the prompt, and the guard's `report_edit: act` waits for the per-stage action levels of 5.3, so no preset sets a stage's rules yet.
+
+---
+
+## 7. Ticket timeline on the dot page
+
+### 7.1 Tickets table
+
+The dot page gains a Tickets section: one row per ticket in the dot's area, a status indicator, and a drawer. It extends the traceability view of MULTI-REPO 4.7 with the stage columns and works the same for Jira, Linear, and GitHub tickets.
+
+```text
+Tickets   [Milestone: 2026.11 v]  [Status: All v]  [Stage: All v]
+  Ticket                          Stage now            Cases   PRs    Defects   Status
+  SHOP-12 Guest checkout coupon   Regression runner    6       #58    1 closed  (o) Passing
+  SHOP-15 Saved cards             Change reviewer      4       #63    1 open    (!) Failing
+  SHOP-18 Order history filter    Test designer        -       -      -         ( ) Designing
+  SHOP-21 Gift wrap option        Ticket analyst       -       -      -         (?) 2 questions
+```
+
+Statuses extend MULTI-REPO 4.6: Not designed (no active cases), Designing, Waiting on questions, Not tested, Partly tested, Passing, Failing, Out of date. "Stage now" is the stage of the latest event.
+
+### 7.2 Drawer timeline
+
+```text
+SHOP-12 Guest checkout coupon                                        (o) Passing
+  Cases 6 (4 manual, 3 Playwright kept, 2 AI-Vision)   Open test cases   Open ticket
+
+  [lens] Oct 8 09:12   Ticket analyst     Reviewed: 2 questions, 5 test ideas          Open run
+  [penn] Oct 8 09:14   Test designer      Wrote 6 cases, 1 waits on a question         Open cases
+  [nit]  Oct 9 14:03   Change reviewer    PR #58 at 4f1c2a9: 5 passed, 1 failed        Open run
+  [nit]  Oct 9 14:05   Change reviewer    Defect SHOP-31 filed: total off by one cent  Open defect
+  [nit]  Oct 9 17:40   Change reviewer    PR #58 at 9be0d11: 6 passed                   Open run
+  [echo] Oct 10 10:20  Regression runner  Merge 9be0d11: 6 passed                       Open run
+  [ward] Oct 12 08:00  Release guard      2026.11: SHOP-12 passing                      Open report
+```
+
+Entries come from runs with a stage whose trigger names the ticket or whose PR links to it, case revisions, `case_results`, `defect` links, and approvals that wait on a person. Each entry has the stage avatar at 20 px, the time, the stage name, one sentence, and a labeled link. A case row opens the case drawer with its forms, its results per run, and Edit.
+
+### 7.3 API
+
+| Method and path | Purpose |
+|---|---|
+| `GET /api/dots/:id/tickets?milestone=&status=&stage=` | Rows of the Tickets table |
+| `GET /api/dots/:id/tickets/:ref/timeline` | `TimelineEntry[]`, oldest first |
+| `GET /api/dots/:id/cases?ticket=` | Cases of a ticket |
+| `POST /api/dots/:id/cases` | Add a case by hand (`origin: 'user'`) |
+| `PATCH /api/dots/:id/cases/:caseId` | Edit; bumps `revision`. 409 on a stale revision |
+| `POST /api/dots/:id/tickets/:ref/design` | Queue `test_design` on demand. 409 when the designer is off |
+| `POST /api/dots/:id/release-check` body `{ milestone? }` | Queue `release_check` on demand |
+
+```ts
+export interface TimelineEntry {
+  at: string;
+  stage: StageKey;
+  kind: 'review' | 'design' | 'run' | 'defect' | 'approval' | 'readiness' | 'incident';
+  title: string;                 // one sentence
+  status: 'ok' | 'warn' | 'error' | 'info';
+  runId?: string;
+  caseIds?: string[];
+  prRef?: string;
+  url?: string;
+}
+```
+
+Live events: `{ type: 'case'; case: TestCase }` joins `LiveEventV2`, so the drawer updates while the designer writes.
+
+Mobile: at 390 px the table drops the PRs and Defects columns into the drawer, and timeline rows wrap to two lines with the avatar and time on the first. A visual check of both themes at 390x844 and 1280x800 is part of the UI tasks.
+
+---
+
+## 8. Stage avatars
+
+KAT-131 (PR #15) added six characters in the mascot style, mapped in `client/src/ui/mascotArt.ts` `STAGE_MASCOT`:
+
+| Stage | Avatar | Cue |
+|---|---|---|
+| Ticket analyst | lens (sky) | Magnifier |
+| Test designer | penn (pink) | Pencil |
+| Change reviewer | nit (teal) | Diff tag with a green and a red line |
+| Regression runner | echo (clay) | Loop arrow |
+| Prod watcher | argus (slate) | Watching eye |
+| Release guard | ward (indigo) | Shield with a check |
+
+The dot keeps its own mascot (`pip`, `nova`, `bolt`, `moss`) as its identity. A stage avatar shows which specialist did the work:
+
+- Feed rows: the stage avatar at 20 px next to the run title.
+- Run detail header: the stage avatar and name next to the dot name.
+- Inbox cards: the stage that drafted the action.
+- Dot page: the stage list (64 px in settings, 20 px in rows) and the ticket timeline.
+- Chat: tool cards that queue a stage job carry its avatar.
+
+State per stage avatar, from the dot's runs:
+
+| State | When |
+|---|---|
+| `running` | A job of that stage is running |
+| `attention` | Its latest run ended `needs_attention`, `product_failure`, or `test_failure`, or one of its drafts waits in the Inbox |
+| `outage` | Prod watcher: a probe is down. Other stages: the last three runs failed to run (`environment_failure` or `notRun`) |
+| `ok` | Otherwise |
+
+A stage that is off shows its avatar at reduced opacity with the label "Off". The avatar is never the only signal: the stage name and state text sit next to it.
+
+---
+
+## 9. Cost bounds and edge cases
+
+| Item | Bound |
+|---|---|
+| Designer model calls | One per ticket revision, plus one check round. None in demo mode |
+| Designer input | 24 KB: ticket, analyst verdict, matching area, spec titles of that area, current cases |
+| Designer output | `maxCases` cases (default 8, at most 20) as JSON, checked by schema and the rules of section 3.4 |
+| Generated specs per PR run | `pwgen.maxSpecs` (PR #9, default 3), ticket cases first |
+| Ticket cases per PR run | `reviewer.maxTicketCases` (default 12) |
+| Release guard | Deterministic counts plus one fast-tier summary per check |
+
+Edge cases:
+
+- A ticket the analyst scores below the floor gets no design. The timeline says "Too thin to design" and the ticket stays Not designed.
+- A ticket reviewed by two dots gets two case sets, one per dot. Sharing cases across dots is out of scope.
+- A PR that names a ticket outside the dot's tracker scope runs no cases for it; the link is still written.
+- A retired case keeps its results. The guard counts only active cases.
+- The designer off: the Change reviewer falls back to the analyst's test ideas for AI-Vision, as today.
+- The analyst off: the designer runs only on demand from the dot page or chat, and reads the ticket itself.
+- A person edits a case while the designer revises it: the designer's write fails on the revision check and retries once on the new revision; a user-origin case is never overwritten.
+
+---
+
+## 10. Build tasks
+
+Sizes: S is under half a day, M is one to two days, L is three days or more. Each row is one PR that passes review and CI on its own and leaves the product working. Dependencies in brackets.
+
+| # | PR | Size | Notes |
+|---|---|---|---|
+| 1 | Built (KAT-159). Stage contract: `StageKey` moved to `src/types.ts`, `src/stages/index.ts` registry with `stageFor(kind, ev, rerunOf)` (labels, avatars, `ci_failure` by PR head, `rerun` from the source run), `RunRecord.stage` set in `startRun`, `stage` on the runs API. No new job kinds | S | No behavior change |
+| 2 | Area scope: apply `pathFilters` in `watchMatches` for PR and push events | S | Independent. A dot without filters matches as today |
+| 3 | Stage toggles and rules: `Watch.stages`, `migrateStages`, `dispatchTrigger` skips jobs of an off stage, the probe scheduler and status page poller skip dots whose watcher is off, `gate()` resolves stage rules, API validation | M | [1] Migration test on a copy of a real `localdost.db`: same jobs before and after |
+| 4 | Model per stage: `getLlmFor(watch, stage)`, cache per backend, tier mapping, stage on `QaReviewPass` | M | [1] |
+| 5 | Case store: `TestCase`, `CaseResult`, tables, case API, `tests` links with source `designer`, `test_plan` page renderer | M | [1] |
+| 6 | Test designer, manual cases: `test_design` job kind with its labels, report kind, and handler, handoff from the analyst, prompt, schema and script checks, revision and retire rules, mock output, on-demand endpoint | L | [3, 5] |
+| 7 | Designer evals: fixture tickets with expected cases; scores for criterion coverage, duplicates, and unobservable expectations; CI budget | M | [6] |
+| 8 | AI-Vision form: `AiVisionCase` per e2e case; `planAiVisionCases` prefers designed cases over test ideas | S | [6] |
+| 9 | Playwright form: planned items to pwgen at the first change review that names the ticket, kept source on the case, reuse without a new model call, `in_repo` after the proposal merges, `reproduce` for bug tickets | M | [6] and PR #9 merged |
+| 10 | Change reviewer reuse: cases for named tickets, `<ticket_cases>` block, `QaTestToRun.caseId` and its check, manual cases in the sticky checklist, results to `case_results` | M | [6] Re-run `npm run eval:qa-review`; scores must not drop |
+| 11 | Regression runner: `post_merge` runs active cases of the tickets the merge closes; defects carry `caseId` and write `defect` links | S | [10] |
+| 12 | Release guard: `release_check` job kind with its labels, report kind, and handler, schedule and on-demand endpoint, readiness per requirement with the statuses of section 7.1, `readiness` page per milestone, report-only wording | M | [11] and MULTI-REPO A7 |
+| 13 | Built (KAT-171, section 5.5). Stage settings UI: stage list in the dot dialog with toggles, rules, model, and options; stage presets with Product area first; migrated-dot notice | M | [3, 4] Screenshots of both themes at 390x844 and 1280x800 |
+| 14 | Ticket timeline: tickets and timeline API, Tickets table and drawer on the dot page, case drawer, `case` live event | L | [5, 10] Screenshots of both themes |
+| 15 | Stage avatars in Feed rows, run detail, Inbox cards, and chat tool cards, with the state mapping of section 8 | S | [1] |
+| 16 | Chat tools: `design_tests(ticket)` and `list_cases(ticket)`, case edit proposal card | S | [6] and KAT-133 |
+
+Task 11 is built (KAT-169, `src/flows/mergeCases.ts`) for the first half: a `post_merge` finds the active cases of the tickets its PR closes or references, records the results of automated ones through `linkRunResults`, adds manual ones as run items of one manual test run per merge (rerunning the merge adds none), and a defect drafted from the run carries `caseId` and `caseKey` in its meta and a case link in its body when the failing test maps to a case. Writing a `defect` links row on execution is not built yet.
+
+### Order
+
+1. Tasks 1, 2, 3, 4, and 15. After these, every run carries a stage, stages can be switched off, and the Feed shows who did the work.
+2. Tasks 5, 6, 7, 8. First useful release: the designer writes manual and AI-Vision cases per ticket, and the Change reviewer runs the AI-Vision ones.
+3. Tasks 10, 11, then 9 once PR #9 is merged. Second release: ticket cases run on every PR and merge that names the ticket, with generated Playwright specs.
+4. Tasks 13, 14, 16.
+5. Task 12 after MULTI-REPO A7.