tinybeeai 0.0.0-stage → 0.16.1

package/docs/LEAD-DOT.md

@@ -0,0 +1,553 @@
+# Lead QA dot (KAT-405)
+
+Built in 0.15.0. This page is the build spec; [API-V2.md](API-V2.md#lead-qa-dot-kat-405) lists the fields and routes, and [SETUP.md](SETUP.md#lead-qa-dot) says how to make a lead.
+
+The Lead QA dot is a dot with no repos, tracker or site checks of its own. It names member dots and gives the QA team one place for team health, a daily team digest, questions about every member, shared test cases, one bug report per bug, and a release call. Everything it shows is built by code from rows the members already store. The model only words chat answers. The lead files and comments nothing. Its only outward post is the scheduled daily digest to its Slack channel, which is code text like every member's digest. Bug reports, ticket comments and PR comments still go through a member's Inbox.
+
+The build is four pieces in three waves. Piece 1 (the lead dot and team health) comes first. Pieces 2 (team data and the release call) and 4 (one bug, one draft) can then run in parallel. Piece 3 (ask the lead and the daily digest) needs piece 2.
+
+## Decision context
+
+On 2026-10-22 Huy chose one dot per job for the QA team. The four dots already run on the live server:
+
+| Dot | Jobs on (stages) | Scope |
+|---|---|---|
+| Ticket Reviewer | analyst, designer | tracker katalon-studio/product, label pod:agentic |
+| PR Reviewer | reviewer | the 4 pod app repos |
+| Regression Runner | regression | Tests repo duonghaijoe/true-dogfood-tests, deploy wait |
+| Site Watcher | watcher | site check on the QA tenant |
+
+docs/STAGES.md section 1.1 records the older choice of one dot per product area with stages. It rejected one dot per role because the ticket, its cases, the PR and the results crossed dots. The lead dot answers that objection: the context crosses dots through the lead's member list. Piece 1 updates section 1.1 with the 2026-10-22 decision and a link to this spec.
+
+Facts read at origin/main that shape the design:
+
+- Cases are per dot. `casesForTicket(dotId, ref)` in src/flows/testDesign.ts filters `test_cases` by one `dotId`, and so does `linkRunResults` in src/test-runs.ts. Ticket Reviewer designs the cases, so today PR Reviewer (`designedCasesFor` in src/runner/aivision/index.ts) and Regression Runner (`activeCasesOf` in src/flows/mergeCases.ts) never find them or write their results.
+- Links and traceability are per dot. `linksOfWatch(w.id)`, `loadEvidence(w)` and `ticketCatalog(w)` read one watch id. Ticket rows come from Ticket Reviewer's `ticket_review` runs. PR to ticket links and test results come from PR Reviewer and Regression Runner.
+- Ticket refs are per dot. `mentionInScope` in src/review/linked-tickets.ts keeps a GitHub issue ref only when its repo is the dot's tracker repo or one of its own repos. PR Reviewer has no tracker, so `linkedRefs` drops every katalon-studio/product ticket.
+- Bug targets are per dot. `defectTarget` in src/flows/defects.ts files into the dot's tracker, and with no tracker into the repo the bug was found in. PR Reviewer and Regression Runner have no tracker.
+- The defect guard is per dot. `pendingApprovals`, `pendingBySig` and `rejectedFor` in src/flows/defectDraft.ts, and `supersedeOlder` in src/agent/approvals.ts, filter by one `watchId`. Two members that find one bug make two Inbox items.
+- A dot with no repo, tracker or probe matches no event in `watchMatches` (src/webhooks.ts), and its health reads "Not watching: nothing set up" (`notWatchingReason` in src/dot-health.ts). A lead needs its own health branch.
+- The digest scheduler in src/index.ts enqueues a `digest` job per dot at `digestHour`. The lead reuses that job kind, so `JobKind` and its exhaustive maps do not grow.
+- `pickDot` in src/slack/index.ts returns the first dot in table order whose `slackChannel` matches, after the name and thread checks.
+- docs/STAGES.md plans a Release guard (`release_check`, task 12) that writes readiness per milestone and "never says release or hold".
+
+## What the tester sees
+
+Words follow the word map in the word map of the simplicity work (a manual tester is the reader). A member is named by its name. Its job reads as Ticket review, Test cases, PR check, After merge, Site check, or Release check, never as a stage key, and every view uses the same job words. The dot's instructions read as Goal. The team message is the daily digest, the word the app already uses. Status words are Failing, Needs you, Healthy and Not watching, with the dot health icons. In the wireframes `[x]` is the cross, `[!]` the warning, `[v]` the check and `[-]` the clock.
+
+Every line in the wireframes is the text the rules below produce. A row's need is the member's own `statusReason`, so it reads the same as on the member's page.
+
+### Lead page, desktop
+
+The page replaces the dot health panel for a lead. The member table uses rows with dividers and a status icon per row, with no accent stripes. The Release call section sits below it.
+
+```
++------------------------------------------------------------------------------------------+
+|  Lead QA                                                 [Digest now]  [Ask]  [Settings] |
+|  Team of 4 dots. Daily digest at 09:00 in chat and #qa-agentic.                          |
++------------------------------------------------------------------------------------------+
+|  Team health: [x] Failing                                                                |
+|  Regression Runner: the last merge found a bug.                                          |
+|                                                                                          |
+|      Dot               Job                        Status      Needs a person             |
+|  --------------------------------------------------------------------------------------  |
+|  [x] Regression Runner After merge                Failing     The last merge found a     |
+|                                                               bug.                [Open] |
+|  [!] PR Reviewer       PR check                   Needs you   2 items to review.  [Open] |
+|  [!] Ticket Reviewer   Ticket review, Test cases  Needs you   1 ticket with              |
+|                                                               questions.          [Open] |
+|  [v] Site Watcher      Site check                 Healthy     Nothing needs you.  [Open] |
+|                                                                                          |
+|  3 items wait in the Inbox across the team.   [Open the Inbox]                           |
++------------------------------------------------------------------------------------------+
+|  Release call                                                   Milestone [ 2026.11  v ] |
+|  [x] Not ready. 14 of 19 requirements passing, 1 failing, 3 not tested, 1 partly tested  |
+|  [x] #4301 Export results to CSV: the after-merge test "exports all rows" fails.  [Open] |
+|  [x] Bug #4318 is open against #4307 Bulk edit.                                   [Open] |
+|  [!] 3 requirements have no test result yet: #4302, #4305, #4311.                 [Open] |
+|  [!] 1 bug report for #4309 waits in the Inbox of PR Reviewer.                    [Open] |
+|  > Details                                                            [See every ticket] |
++------------------------------------------------------------------------------------------+
+```
+
+- Team health word: the rule in job 1. The line under it names the member that set it, with the member's reason after the colon.
+- Row: member name, its job, its status word, the one thing that needs a person, and Open (the member's page, or the button the member's health answer gives). Long text wraps with no ellipsis.
+- Digest now: makes the team digest now and shows it in this chat only (job 2). Ask: opens the lead chat (job 3).
+- A paused or archived member shows its row with "Paused" or "Archived" in the Needs a person column and does not count toward the team word.
+- Details under the release call: counts per status, the member each reason came from, and the rule that set the answer.
+
+### Lead page, phone
+
+```
++--------------------------------------+
+|  < Dots                      Lead QA |
++--------------------------------------+
+|  [x] Failing                         |
+|  Regression Runner: the last merge   |
+|  found a bug.                        |
+|  [Digest now]                  [Ask] |
++--------------------------------------+
+|  [x] Regression Runner             > |
+|      After merge . The last merge    |
+|      found a bug.                    |
+|  [!] PR Reviewer                   > |
+|      PR check . 2 items to review.   |
+|  [!] Ticket Reviewer               > |
+|      Ticket review, Test cases .     |
+|      1 ticket with questions.        |
+|  [v] Site Watcher                  > |
+|      Site check . Nothing needs you. |
++--------------------------------------+
+|  Release 2026.11            [Change] |
+|  [x] Not ready                       |
+|  14 of 19 requirements passing,      |
+|  1 failing, 3 not tested, 1 partly   |
+|  tested                              |
+|  - #4301 fails after merge           |
+|  - Bug #4318 open on #4307           |
+|  - 3 requirements not tested yet     |
+|                    [See the reasons] |
++--------------------------------------+
+```
+
+A row tap opens the member page. The phone shows three release reasons at most and links to the full list.
+
+### Daily team digest
+
+One message, posted to the lead's web chat and to the lead's Slack channel when `slackChannel` is set. The same text is saved as a digest report page. Every line, the second line included, comes from code.
+
+```
++----------------------------------------------------------------------------------+
+|  Lead QA . daily digest . Thu 23 Oct                                             |
+|  2 things broke and 3 wait for a person. Release 2026.11 is not ready.           |
+|                                                                                  |
+|  What broke                                                                      |
+|  - PR #412 Bulk edit: after merge, the test "exports all rows" fails.            |
+|    A bug report waits. PR author: @dev-an. (Regression Runner)  [Review]         |
+|  - The QA site was down 12 min at 09:40 and is back up. (Site Watcher)           |
+|                                                                                  |
+|  Waits for a person                                                              |
+|  - 2 bug reports in the Inbox of PR Reviewer: PR #412, PR #415.  [Open Inbox]    |
+|  - 4 test cases to test by hand after PR #409, assigned to @qa-sam.  [Open]      |
+|  - #4310 has 2 open questions for its author, @pm-lee. (Ticket Reviewer)         |
+|                                                                                  |
+|  Not tested                                                                      |
+|  - 3 requirements of 2026.11 have no test result: #4302, #4305, #4311. [See them]|
+|                                                                                  |
+|  Release 2026.11: Not ready                                                      |
+|  - #4301 Export results to CSV fails after merge.                                |
+|  - Bug #4318 is open against #4307.  [Open the release call]                     |
+|                                                                                  |
+|  > Details                                                                       |
++----------------------------------------------------------------------------------+
+```
+
+- The second line is a code template: "N things broke and M wait for a person." plus "Release <milestone> is <answer>." when a milestone is open.
+- "Who" is the person a line can name from stored data: the PR author (`TriggerEvent.pr.author`), the ticket author, or the assignee of a manual test run item (`RunItem.assignee`). With no name the line says which member's Inbox holds it.
+- Details holds each member's own tester digest text and the counts.
+
+### Release call in chat
+
+The answer is built by code with no model call. In Slack it is the same text with buttons as links. It uses readiness words only (Ready, Ready with risk, Not ready), so the STAGES.md rule "never says release or hold" still holds.
+
+```
++--------------------------------------------------------------------------+
+|  You: Can we release 2026.11?                                            |
+|                                                                          |
+|  Lead QA: Not ready. 14 of 19 requirements passing, 1 failing,           |
+|  3 not tested, 1 partly tested. 2 things block it.                       |
+|                                                                          |
+|  [x] Not ready                                     Milestone 2026.11     |
+|  Why                                                                     |
+|  [x] #4301 Export results to CSV fails after merge.               [Open] |
+|  [x] Bug #4318 is open against #4307 Bulk edit.                   [Open] |
+|  Also                                                                    |
+|  [!] 3 requirements have no test result yet.                  [See them] |
+|  [!] 1 bug report for #4309 waits in the Inbox.                 [Review] |
+|                                                                          |
+|  > Details: counts per status, the checks each reason comes from         |
++--------------------------------------------------------------------------+
+```
+
+### Merged bug report in the Inbox
+
+```
++--------------------------------------------------------------------------+
+|  Inbox                                                         3 waiting |
++--------------------------------------------------------------------------+
+|  File this bug?                                                          |
+|  Bulk edit drops the last row when you export to CSV                     |
+|                                                                          |
+|  Found by PR Reviewer (PR #412, 10:02) and Regression Runner (after      |
+|  merge of PR #412, 11:47). One bug report: it is filed once.             |
+|  Goes to: katalon-studio/product. Linked to #4307.                       |
+|                                                                          |
+|  Expected: 25 rows in the file.   Actual: 24 rows.                       |
+|                                                                          |
+|  [File the bug]   [Edit]   [Don't file]                                  |
+|  > Details: both checks, both test logs, signature 3f9a1c2e7b04          |
++--------------------------------------------------------------------------+
+```
+
+The Inbox shows the item once, under the member that drafted first. The second member's check says "Same bug as the report PR Reviewer drafted. Added to it." with a link. "Goes to" is the team tracker (job 5).
+
+### Wireframe check (0.16.0)
+
+0.15.0 shipped the lead without laying its screens next to the wireframes above. The 0.16.0 check (KAT-405, screenshots at 1280x800 and 390x844 in light and dark) found these gaps and fixed them:
+
+- The headings of the member table (Dot, Job, Status, Needs a person) sat off their columns, because the last column was `auto` in the rows and empty in the heading. Both now share one column template.
+- The title row had six buttons. It now has the three of the wireframe (Digest now, Ask, Settings) at the right of the title; Pause and Remove dot sit in a row at the foot of the page, and Edit goal is Settings.
+- A phone showed the avatar, the name and six buttons before the status. It now starts with the status word and its reason, then the three buttons, then the members. The top bar names the dot, so the page keeps its heading for a screen reader only.
+- The Release call title and the milestone picker are one row with the label beside the picker. The answer reads "Not ready." with a full stop, as in the wireframe. On a phone a reason is one tap row with a chevron, three show, and the button says See the reasons and opens the rest in place (the trace page lists tickets, not a bug report that waits in an Inbox); once they all show, the button is See every ticket. Save as a report page moved under Details.
+- A chat answer cut its blockers to three in a card narrower than 560 px, while its first line said "4 things block it". The chat block never cuts a reason, and Open stays on the line of its reason down to 480 px.
+- A team that passes every requirement read "No tickets. No milestone is open." It now answers Ready for its newest milestone. The digest still asks for the open milestone only.
+- The header of the lead's chat read "All good" for a failing team. It takes the word of the team.
+- The member digests under Details of the digest page ran together ("Ticket ReviewerNothing needs you."). Each member is a paragraph of its own, and the chat message has the Details fold of the wireframe (`update.details`).
+- The Open button of a team row followed the wireframe only in part: it now goes to the link the member's own health answer gives. The name of the member, and on a phone the whole row, open the member page ("A row tap opens the member page").
+- A bug report in the Inbox asks "File this bug?" above its title and names the tickets it is linked to next to where it files ("Files in katalon-studio/product. Linked to #4307."). A release answer in the chat says See them on a group of tickets and Review on a bug report that waits in an Inbox, as the chat wireframe does.
+
+The second pass of the check (the same screenshots after the fixes, read by a reviewer) found these and fixed them:
+
+- A healthy member read "#4301 is in the release and has no test cases yet" under a team that read Ready. A member judged a ticket from its own rows only, and the check that tests the ticket belongs to PR Reviewer. A member of a lead now reads the tests, PRs and bugs of its whole team for its own tickets, and the cases of the whole team, so the member page, the team row and the release call agree (`withTeamEvidence` in src/dot-health.ts). A member's kept health answer drops when any teammate's drops.
+- The Team health table in the lead's chat ran past its card and, on a phone, showed only Dot and Job. A chat table of up to four text columns now wraps its text and fits the card, and under 520 px each row stacks its Job, Status and Needs a person under the name.
+- A team that is Not watching still showed a green Ready and a main Digest now button. The release call now says the answer is from the last results, reads in a muted colour, and Digest now is a plain button.
+- The card beside the lead's chat said "Nothing to review" while the team held items in its Inboxes. It counts the Inboxes of the members, as the team panel does.
+- The digest page said "risk low, confidence 100%" above "3 things broke". The risk now follows the facts (`riskOf` in src/lead-digest.ts) and a digest shows no confidence figure.
+- Details of the digest has a heading, a heading per member, and the groups (Needs you, For your info) in italics; "Open the release call" stands on its own line; a comment on a GitHub ticket reads "issue #4301", not "PR #4301".
+- The release answer in the chat started with "Lead QA:" under a header that names Lead QA. Only a Slack answer names the dot.
+- The Inbox named a bug report group "github:acme/product", and a linked ticket of another repo as a bare "#4301". It names the repo, and keeps the repo of a ticket that is not in the repo the bug files in. On a phone the main button of a card has a row of its own and the others share the next.
+- On a phone the buttons of the lead page showed only after the team loaded, and the report page of a digest wrapped its bar into four rows and cut its title in the top bar after one line. The buttons show from the first frame, the bar is two rows, and the top bar title wraps to a second line before it is cut.
+
+Where a wireframe differs from the words the app already uses, the words of the app win: the Inbox card says "Files in" where the wireframe says "Goes to", and its buttons say "File in <place>" and "Don't file" where the wireframe says "File the bug". The release reason on the page reads "#4301 Export results to CSV fails after merge." as in the chat and digest wireframes; only the page wireframe adds the test title.
+
+## Data model
+
+### Fields on Watch (src/types.ts)
+
+```ts
+export type DotKind = 'dot' | 'lead';
+
+export interface Watch {
+  // existing fields unchanged
+  /**
+   * 'lead': a Lead QA dot (KAT-405). It holds no repos, tracker, site checks or runner and reads its members' rows.
+   * Unset: 'dot'. Set by POST /api/dots only; a PATCH that changes it is refused.
+   */
+  kind?: DotKind;
+  /** The member dots of a lead, in the order the team panel lists them. Only on a lead. 1 to 8 ids. */
+  memberIds?: string[];
+}
+```
+
+`kind` (text) and `memberIds` (json) join `SCHEMA.watches` in src/db-schema.ts, and `db.ts` adds the columns at boot with its existing `ALTER TABLE ... ADD COLUMN` loop. Both join `WATCH_FIELDS` in src/api.ts.
+
+### New types
+
+```ts
+export interface TeamMemberHealth {
+  id: string;
+  name: string;
+  /** "PR check", "Ticket review, Test cases": the job words of the stages that are on. */
+  job: string;
+  status: HealthStatus;
+  /** Set when a person paused or archived the member. Such a member does not count toward the team word. */
+  away?: 'paused' | 'archived';
+  /** The one thing that needs a person, or "Nothing needs you." */
+  need: string;
+  /** The button for `need`, from the member's health answer; null when nothing needs a person. */
+  action: HealthAction | null;
+}
+
+export interface TeamHealth {
+  status: HealthStatus;
+  /** "Regression Runner: the last merge found a bug." */
+  statusReason: string;
+  members: TeamMemberHealth[];
+  /** Live Inbox items across the members. */
+  inbox: number;
+  builtAt: string;
+}
+
+export type ReleaseAnswer = 'ready' | 'ready_with_risk' | 'not_ready' | 'no_tickets';
+
+export interface ReleaseReason {
+  level: 'blocker' | 'risk';
+  text: string;
+  /** Ticket, bug or PR the reason names. */
+  ref?: string;
+  href?: string;
+  /** The member whose data gave the reason. */
+  memberId: string;
+}
+
+export interface ReleaseCall {
+  milestone: string;
+  answer: ReleaseAnswer;
+  /** "14 of 19 requirements passing, 1 failing, 3 not tested" (readinessSummary, unchanged). */
+  summary: string;
+  counts: ReadinessCounts;
+  reasons: ReleaseReason[];
+  /** Every milestone of the members' trackers, for the picker. */
+  milestones: string[];
+  builtAt: string;
+}
+```
+
+`DotHealth` gains `team?: TeamHealth`. For a lead, `healthOf` returns the team status, team reason and the lead's own pause or archive state, with `team` set, `suggestion` null and the eight tiles as `not_set_up`. The client draws the team panel whenever `team` is set, so the dot list and the sidebar read one status word for every dot.
+
+### Validation
+
+POST /api/dots and PATCH /api/dots/:id run one new check, `leadError(fields, w?)`, in the chain that already holds `stagesError` and `modelCapError`.
+
+| Rule | Error |
+|---|---|
+| `kind` is `dot` or `lead`, and only POST sets it | 400 `kind must be dot or lead.` / 400 `A dot cannot change kind. Make a new lead.` |
+| A lead has 1 to 8 `memberIds`, each a known dot, no repeats | 400 `A lead names 1 to 8 dots.` / 400 `No dot with id <id>.` |
+| A lead cannot be a member, and a lead cannot name itself | 400 `<name> is a lead. A lead cannot be a member of another lead.` |
+| A member has at most one lead | 409 `<name> is already in <lead name>. Remove it there first.` |
+| An archived dot cannot be added | 400 `<name> is archived. Restore it first.` |
+| A lead holds no `repo`, `repos`, `tracker`, `probes`, `statusPages`, `baseUrl`, runner command, `review` or `stages` | 400 `A lead has no repos, tracker or site checks of its own. Set them on a member.` |
+| `memberIds` on a dot of kind `dot` | 400 `Only a lead has members.` |
+
+The at-most-one-lead check scans live and archived leads, so restoring a lead never gives a member two leads. A save of `memberIds` publishes a `dot` event for the lead and for every member added or removed, which drops their kept health answers and the lead index (below).
+
+`memberIds` follows the editor rules of other non-runner fields: an admin or an editor may change it, a member may not.
+
+### Lead index (src/lead.ts, new)
+
+- `leadOf(dotId): Watch | undefined`: the lead whose `memberIds` holds the dot. A map kept in memory, rebuilt on a `dot` event and at boot.
+- `teamIds(dotId): string[]`: the lead's `memberIds` when the dot has a lead, else `[dotId]`. Shared case lookup, ticket scope, the bug target and the defect merge use it.
+- `membersOf(lead): Watch[]`: live member rows in `memberIds` order. Ids of deleted dots drop out.
+- `teamTracker(dotId): Watch | undefined`: the first member in `memberIds` order that has a tracker. Undefined for a dot with no lead.
+- `isLead(w)`: `w.kind === 'lead'`.
+
+### Removing members and leads
+
+- `deleteDot` in src/dot-remove.ts removes the deleted dot's id from its lead's `memberIds`.
+- Deleting the only member of a lead is refused with 409 `<name> is the only dot of <lead name>. Add another dot to the lead, or delete the lead first.` A lead therefore always keeps 1 to 8 `memberIds`.
+- Deleting a member that owns test cases also deletes the `run_items` of the other team members whose `caseId` is one of its cases, and recounts those test runs (piece 2). The delete summary counts these items, so the confirm dialog says "Also removes 6 test run items of Regression Runner."
+- Archiving a member keeps its id, and the row reads Archived. Archiving hands its pending merged bug drafts to the next source (job 5).
+- Deleting or archiving a lead changes no member.
+
+### Lead-only guards
+
+Routes that need a repo, tracker, site or runner answer 409 `<lead name> is a lead. Ask a member for this.` for a lead: POST /api/dots/:id/site-check, PUT and POST /api/dots/:id/review, GET /api/dots/:id/pulls, POST /api/dots/:id/cases (a lead owns no cases), and POST /api/runner/try with a lead's `dotId`. The dot dialog for a lead shows name, members, digest hour, Slack channel, daily model cap, and the Goal (mission, tell me when, never). It hides repos, tracker, site checks, runner, jobs and rules.
+
+## Jobs
+
+### 1. Team health
+
+Reuses: `healthFor(w)` in src/routes/health.ts (30 s cache per dot, dropped on run, approval and dot events), `STATUS_WORD` and `STATUS_ICON` in client/src/features/health/healthModel.ts, `HealthWord`, `useRereadEvery`, the stage registry in src/stages/index.ts for job words, and `liveCount` in src/agent/approvals.ts for the Inbox count.
+
+New code:
+
+- `teamHealth(lead, now)` in src/lead.ts. Pure over the members' `DotHealth` answers and a fixed clock, so each rule has a unit test.
+- Team word rule. The team takes the worst word in this order: Failing, then Needs you, then Not watching, then Healthy. It reads only members with no `away`. The order differs from the single-dot order on purpose: a member that is Not watching for a reason such as an expired AI sign-in, a GitHub limit, or site checks off never hides a Failing or Needs you member. When every member is away, the team is Not watching with "Every dot of the team is paused or archived." With no live member left (a deleted dot that the index has not dropped yet), the team is Not watching with "The team has no dots. Add one in the lead settings."
+- Team reason: `<member name>: <member statusReason>`, with the first letter of the reason lowered, for the first member in `memberIds` order that has the team word. With more than one, "(and N more)" follows. Healthy reads "Nothing needs you."
+- Row `need`: the member's `statusReason` when its word is not Healthy, else its `suggestion.text`, else "Nothing needs you." Row `action`: `statusFix`, else the suggestion's action, else null. The name of the member and a phone row go to `#/dots/<id>`; the Open button goes to the action's link (an app route or a tracker address) when it has one, else to `#/dots/<id>`. A member reads the tests of its team for its own tickets, so a suggestion such as "no test cases yet" never contradicts the release call.
+- `healthOf(lead)` returns the team branch above. GET /api/dots/health includes leads, so the dot list shows the team word with no extra request.
+- The lead's kept answer drops when any member's answer drops: the `subscribe` hook in src/routes/health.ts also deletes `leadOf(watchId)` and every member of that lead from the cache, since a member reads the tests of its team.
+- Dots page header: the "need you", setup-fix and waiting counts in client/src/pages/Dots.tsx skip leads (`d.kind !== 'lead'`). A lead row repeats its members' words, so counting it would show one broken merge as "2 need you".
+- Client: `TeamPanel.tsx` in client/src/features/health, rendered by client/src/pages/DotDetail.tsx when `health.team` is set. It reuses `health.css` row styles and the words of `healthModel.ts`. In the dot list a lead row shows "Team of 4" as its scope line (`scopeSummary` gains a lead branch).
+
+### 2. Daily team digest
+
+Reuses: the scheduler in src/index.ts (`digestDue`, `enqueue({ kind: 'digest' })`, the `digest:<id>:<day>` dedupe key), `testerDigest(area, runs, approvals)` in src/updates/words.ts per member, `mergedWithBugsLines` and `ticketsWithoutCriteriaLines` in src/flows/digest.ts, `saveDigestReport`, the update router in src/updates (chat message, Slack channel or DM, phone push), `redactCode` and `renderVerdictRefs`.
+
+New code:
+
+- The `digest` handler in src/flows/digest.ts branches first: `if (isLead(watch)) return runTeamDigest(job, watch)`. Member digests do not change.
+- `teamDigestFacts(lead, now)` in src/lead-digest.ts builds the sections from member rows, with no model:
+  - What broke: each member's `testerDigest` need lines for bugs and outages in the window, tagged with the member name and the PR author when known.
+  - Waits for a person: live Inbox items per member (count, refs), manual test run items in state `untested` or `retest` and their `assignee`, and ticket reviews with open questions (ticket author when the review stored one).
+  - Not tested: team trace rows (job 6) of the nearest open milestone (`nearestOpenMilestone`) with status Not tested, Partly tested or Out of date, up to 6 keys and a link to the rest.
+  - Release: the release call (job 6) for that milestone, its answer and two reasons at most.
+- The opener is the code template under the digest wireframe. The digest makes no model call, so its text is templated like every member digest and the update router posts it at the same level.
+- Scheduled delivery: one update of kind `daily_digest` through the update router, which posts to the lead's chat and to the lead's Slack target (`slackChannel` or `updates.slack`). Clearing both stops the Slack post. The `digest:<id>:<day>` job key sends it once per day.
+- On demand: POST /api/dots/:id/digest enqueues the same job with an `AskOrigin` of the person who asked and the dedupe key `digest-now:<leadId>:<10-minute slot>`, so a double click makes one digest. `ruleLevel` in src/updates/route.ts gains one rule above the digest rule: a `daily_digest` that carries an `origin` takes the `thread` level. An on-demand digest therefore replies only in the chat or Slack thread where it was asked. It never posts to the lead's channel and never pushes to phones.
+- The digest run is a `digest` run of the lead, so the Activity feed, the report page and `lastDigestAt` work unchanged.
+
+### 3. Ask the lead
+
+Reuses: `runChat`, `CHAT_TOOLS`, `dispatchChatTool`, `resolveWatch`, `plannedFirstTool` and `summarizeToolResult` in src/agent/chat.ts; `requestReview` for PRs and commits; the ticket review and design request paths; `recordAsk` and the update router; `pickDot` and `handleMention` in src/slack/index.ts.
+
+New code:
+
+- Chat context: `ChatToolContext` gains `team?: Watch[]`. `runChat` sets it when the chat's dot is a lead.
+- Read tools for all members. In a lead chat, these tools take `dotId` as a member id or `all`, and `all` is the default: `list_runs`, `get_run`, `list_tickets_reviewed`, `pending_approvals`, `open_prs`, `runs_in_progress`, `recent_defects`, `list_cases`, `pass_rate`, `test_results`, `flaky_by_spec`, `probe_status`, `get_memory`. A wrapper `forTeam(name, input, ctx)` runs the tool once per member, adds `dot: <member name>` to each row, merges newest first, and keeps the existing row limit per call. A `dotId` outside the team returns "That dot is not in <lead name>."
+- External calls in `forTeam`. Every tool above reads the database only, except `open_prs`, which calls GitHub `listPulls` once per repo. In a lead chat `open_prs` collects the repos of all members, drops repeats, and calls at most 12 per tool call. Past 12 the result says "Skipped N repos. Ask about one dot to see them."
+- `get_ticket` does not fan out. In a lead chat it goes to the one member whose tracker holds the ticket (`teamTracker`), so it makes one tracker call.
+- Two new read tools, in the lead chat only. `team_status` returns `TeamHealth`. `release_call { milestone? }` returns `ReleaseCall`, and the chat shows it as a `release_call` block (new kind in src/chat-blocks.ts and the client block renderer).
+- Routing of action requests. In a lead chat, `rerun_tests`, `review_pr`, `review_ticket` and `design_tests` go through `routeToMember(tool, input, lead)`:
+
+  | Request | Member picked |
+  |---|---|
+  | `review_pr` on an open PR | the member with the PR check job whose repos hold the PR's repo |
+  | `review_pr` on a merged PR, a commit or a range | the member with the After merge job for that repo; with none, the PR check member |
+  | `review_ticket` | the member with the Ticket review job whose tracker holds the ticket |
+  | `design_tests` | the member with the Test cases job for that ticket |
+  | `rerun_tests` | the member with the After merge job, else the PR check member |
+
+  A PR number with no repo is matched to the newest member run that names that number. When two repos or two members fit, the tool returns the choices and the model asks which. When no member fits: "No dot in <lead name> does PR checks. Add one in the lead settings."
+- The tool result carries `routedTo` and `ask`. `summarizeToolResult` prints "Asked PR Reviewer to check PR #12 again", and the chat shows that line. The member's own rules, cap and dedupe apply to the job, unchanged.
+- Results come back to the lead chat. `AskOrigin` (web) gains `scope: 'lead'` and `leadId`. `toChat` in src/updates/index.ts writes such an update into the lead's chat with "From PR Reviewer" in front, the same way `scope: 'all'` works today.
+- Slack. `pickDot` keeps its order: a named dot first, then the remembered thread. For the channel match it prefers a lead: when several live dots share the channel, the lead among them wins, else the first in table order as today. A mention of "Lead QA" or an unnamed message in the lead's channel reaches the lead even when a member uses the same channel. A message that names a member still reaches that member. The routed result replies in the same thread through the existing Slack origin.
+- Rule-based paths stay first. `pickChatView` gains a release question rule ("release", "ship" or "go live" with a known milestone title or "next release"), answered by `release_call` with no model call. `plannedFirstTool` routes review requests through `routeToMember`.
+- The lead's `dailyModelCap` counts the lead chat's model calls. Routed jobs count toward the member's cap, as today.
+
+### 4. Shared test cases
+
+Reuses: `casesForTicket`, `designedCasesFor`, `activeCasesOf`, `caseForTest`, `linkRunResults`, `caseDetail`, `linkedRefs`.
+
+New code:
+
+- `casesForTicket(dotIds: string | string[], ref)` runs `WHERE dotId IN (...)`. Callers that look up cases for a check pass `teamIds(watch.id)`: `designedCasesFor` (PR check AI-Vision cases), `activeCasesOf` (after-merge cases), and the lookups in src/agent/chat.ts. `designTestCases` writes new cases under its own dot id and checks for existing ones over `teamIds`, so Ticket Reviewer never writes a second copy of a case the team already has. Within the team, the first case per key wins.
+- `linkRunResults` loads cases over `teamIds(run.watchId)`, with the run's own dot's cases first, so a key that two members use maps to the run's own case. Results of automated and AI-Vision tests that map to a team case are written on that case.
+- Ticket scope. `mentionInScope` in src/review/linked-tickets.ts also accepts a ref whose repo is a tracker repo of any dot in `teamIds(watch.id)`. `linkedRefs` applies it to mentions and stored "closes" links alike, so PR Reviewer keeps katalon-studio/product tickets.
+- PR Reviewer: a PR that closes or names a ticket of the team (`linkedRefs`) gets Ticket Reviewer's designed cases as AI-Vision cases, and the PR report lists them as "Test cases from Ticket Reviewer".
+- Regression Runner: a merge that closes or names the ticket adds Ticket Reviewer's manual cases to its "After merge" test run (`mergeRun`). Automated cases with a spec get their results through `linkRunResults`.
+- A run item keeps the dot id of its test run and points at a case of another member. Test run routes accept an item whose case belongs to a dot in `teamIds(item.dotId)`; today they assume one dot. Results are written on the case, so Ticket Reviewer's case page shows manual, automated and AI-Vision results from PR Reviewer and Regression Runner.
+- Deleting a member that owns cases removes the other members' run items that point at those cases (see Removing members and leads).
+- A bug report that maps a failing test to a case names the case and its owner dot.
+
+### 5. One bug, one draft
+
+Reuses: `defectSig`, `bugSignature`, `bugSignatureAlts`, the three-layer guard in src/flows/defectDraft.ts, `draftDefects` and `defectTarget` in src/flows/defects.ts, `closeApproval`, `closePendingApprovals` in src/dot-remove.ts, and the Inbox approval card.
+
+New code:
+
+- `teamDraftFor(watch, candidate, now)` in src/lead-defects.ts. It looks at pending `issue_create` and `file_defect` drafts of the other members of `teamIds(watch.id)` created in the last 24 hours. A draft matches when either holds:
+  1. the same `sig` or `bugSig`, alternates included; or
+  2. the same failing test title (normalized with `normalizeScenario`, exported from src/review/render.ts) and at least one shared ticket ref in `meta.relates`.
+- New meta on bug drafts: `testTitle`, written by both draft paths, so rule 2 can match.
+- Both draft paths call `teamDraftFor` right after their own layer 1. On a match the member drafts nothing. It appends itself to the found draft's `meta.sources` (`{ watchId, runId, at, pr?, head?, bugKey, sig, bugSig }`), adds a "Seen again" line with its check link to the draft body under Details, publishes the approval event, and records the bug link as `drafted` with the Inbox URL. Its check gets the step "Same bug as the report PR Reviewer drafted. Added to it."
+- Team bug target. `defectTarget(watch, repo)` for a member with a lead and no tracker of its own uses the tracker of `teamTracker(watch.id)`, so PR Reviewer and Regression Runner bugs go to katalon-studio/product with Ticket Reviewer's GitHub access. A member with its own tracker keeps it. A dot with no lead files as before.
+- The first draft is the one that files. Approving it files once, into the team target. Rejecting it counts as a rejection for every source: `rejectedFor` also reads the `bugKey` of each entry in `meta.sources` across `teamIds`. Only a person's rejection counts. A draft closed by archiving carries `meta.closedBy: 'archive'`, and `rejectedFor` skips it.
+- Archiving a drafter. `closePendingApprovals` hands a merged draft to the next source in `meta.sources` whose dot is live: the draft's `watchId` becomes that dot's id and the Inbox shows it under that member. Only a draft with no other live source closes, with `meta.closedBy: 'archive'`. No member loses a bug because another member was archived.
+- A draft that already went out: `filedKeyFor` and `priorDefect` read across `teamIds`, so a later member's find becomes a "Seen again" ticket comment draft on the filed issue through the existing layer 3.
+- The Inbox card shows "Found by A (PR #412, 10:02) and B (after merge of PR #412, 11:47)" from `meta.sources`. The draft's dot shows the first live member's name.
+- No model call. The match reads the approvals table by `watchId IN (...)` and `status = 'pending'`.
+
+### 6. Release call
+
+Reuses: `buildAll`, `testStatuses`, `readinessOf`, `readinessSummary`, `nearestOpenMilestone`, `milestoneDate`, `testStats` (flaky tests), and the readiness page (`saveReadinessReport`).
+
+New code:
+
+- Team trace scope. `ticketCatalog`, `indexLinks`, `loadEvidence` and `confirmedKey` take a list of watch ids. `buildAll(w)` passes `[w.id]` for a dot and `memberIds` for a lead. A ticket is classified with the tracker of the member whose ticket review read it. Defect links of every member join the rows, so a bug PR Reviewer filed into the team tracker counts as an open bug on its ticket. GET /api/dots/:id/traceability then works for a lead with no other change.
+- `releaseCall(lead, milestone?)` in src/lead-release.ts, read-only and with no model. The milestone defaults to `nearestOpenMilestone` over the team rows. Rules, first match wins:
+
+  | Answer | When |
+  |---|---|
+  | No tickets | no requirement row has this milestone |
+  | Not ready | a row of the milestone is Failing; or an open bug is linked to a row of the milestone; or the latest after-merge check of a member found a bug (main is broken) |
+  | Ready with risk | a row is Not tested, Partly tested or Out of date; or a bug report for a row waits in an Inbox; or a test of the milestone's rows was flaky 3 or more times this week (`FLAKY_SUGGEST_AT`); or a member is Not watching, so its data may be old |
+  | Ready | none of the above |
+
+- Reasons: one per row or bug, blockers first, each naming the ticket, the member it came from, and a link. The page shows six, the phone three, and "See every ticket" opens the team traceability filtered to the milestone.
+- Shown on the lead page (Release call section with a milestone picker), in the digest, and in chat through `release_call` and the release question view.
+- Never posts. "Save as a report page" reuses `saveReadinessReport` with the team scope and writes a local page only.
+- Release guard. The release call answers a person's question with readiness words and does not replace the planned Release guard. Task 12 in docs/STAGES.md stays as planned for a single dot. When it lands, its readiness rules call `releaseCall` so a dot and a lead never give two answers for one milestone. Piece 1's STAGES.md update records this and keeps the rule "never says release or hold".
+
+## API routes
+
+| Route | Change |
+|---|---|
+| POST /api/dots | accepts `kind: 'lead'` and `memberIds`; runs `leadError` |
+| PATCH /api/dots/:id | accepts `memberIds` on a lead; refuses a change of `kind` |
+| DELETE /api/dots/:id | 409 for the only member of a lead; the summary counts other members' run items it removes |
+| GET /api/dots, GET /api/dots/:id | `dotView` includes `kind` and `memberIds`, and for a member `leadId` |
+| GET /api/dots/:id/health | a lead returns team status with `team: TeamHealth` |
+| GET /api/dots/health | leads included, each with `team` |
+| GET /api/dots/:id/team | new: `TeamHealth` alone, for the team panel's minute reread |
+| POST /api/dots/:id/digest | new: makes the team digest now and replies where it was asked. 202 `{ jobId }`, or 200 `{ duplicate: true }` inside the same 10-minute slot. 409 for a dot that is not a lead |
+| GET /api/dots/:id/release?milestone= | new: `ReleaseCall`. 409 for a dot that is not a lead |
+| GET /api/dots/:id/traceability, /readiness, POST /readiness/report | work for a lead over the team scope |
+| POST /api/chat with a lead's `dotId` | lead chat: team read tools, routing, `release_call` |
+| Routes listed under Lead-only guards | 409 for a lead |
+
+A paired phone may call the GET routes and POST /api/dots/:id/digest. src/phone/auth.ts gains the digest route in its list of allowed writes. The digest costs no model call and replies only to the phone that asked.
+
+## Limits
+
+| What | Limit |
+|---|---|
+| Members per lead | 1 to 8. The only member cannot be deleted |
+| Leads per member | 1 |
+| Team health | no model call, no tracker call. Reuses each member's 30 s answer; the lead answer is kept 30 s and dropped on any member event |
+| Team digest | no model call |
+| Team digest jobs | 1 scheduled per day per lead by `digest:<id>:<day>`, the only one that posts to Slack. On demand at most 1 per 10-minute slot, replied only where asked |
+| Lead chat | each turn counts on the lead's cap. `forTeam` runs at most 8 member reads per tool call. Its only external calls are `open_prs`, at most 12 GitHub `listPulls` per tool call. `get_ticket` makes 1 tracker call through one member |
+| Routed actions | 3 per chat turn. Each is a member job under the member's rules, cap, dedupe and deploy wait |
+| Bug merge window | 24 h, the same as `APPROVAL_TTL_MS` by default |
+| Release call | no model call. Kept 30 s per lead and milestone |
+| Queue | no new job kind. The digest is a `digest` job of the lead, under `LOCALDOST_QUEUE_CONCURRENCY` |
+
+## Migration
+
+None for existing dots. A dot with no `kind` is a `dot`, and nothing reads `memberIds` on it. The new columns are added at boot by the existing column loop in src/db.ts. `migrateStages` leaves a lead with every stage off, because it has nothing to derive them from. The four live dots change only when Huy makes the lead and names them. They keep their own digests, rules and Slack channels. Once they are members, PR Reviewer and Regression Runner file new bugs into the team tracker (job 5).
+
+## Build pieces
+
+Dependency waves for parallel agents. Each piece is one PR with a changelog entry, under the localdost versioning rule.
+
+| Wave | Piece | Contents | Needs |
+|---|---|---|---|
+| 1 | 1. Lead dot and team health | `kind`, `memberIds`, schema, `leadError`, src/lead.ts index with `teamTracker`, lead-only guards, `deleteDot` member and only-member rules, team health (server and `TeamPanel`), Dots header counts skip leads, dot list and dialog for a lead, STAGES.md 1.1 and Release guard update | none |
+| 2 | 2. Team data and release call | `teamIds` case lookup and `linkRunResults` (job 4), team ticket scope in `mentionInScope`, run item cleanup on member delete, team trace scope, `releaseCall`, GET release route, Release call section on the lead page and phone | 1 |
+| 2 | 4. One bug, one draft | `teamDraftFor`, `meta.testTitle`, `meta.sources`, team bug target in `defectTarget`, cross-team `rejectedFor` that skips archive closes, hand-off in `closePendingApprovals`, `filedKeyFor` and `priorDefect`, Inbox card sources line | 1 |
+| 3 | 3. Ask the lead and team digest | `ctx.team`, `forTeam` with the `open_prs` cap, `get_ticket` routing, `team_status`, `release_call` tool and block, `routeToMember`, `AskOrigin` lead scope, `pickDot` lead preference, release question view, `runTeamDigest`, `ruleLevel` origin rule for `daily_digest`, POST digest route | 1, 2 |
+
+## Tests
+
+Unit tests over fixed inputs, route tests through Fastify `inject`, and client tests with the existing health test setup. Each piece ships its own rows.
+
+Piece 1:
+
+- `leadError`: every row of the validation table, including a lead named as a member, a member already in another lead (archived lead too), and a lead that sends `repos`.
+- PATCH that changes `kind` returns 400. A PATCH from a member role that changes `memberIds` returns 403.
+- `teamHealth`: one case per team word; a Failing member beats a member that is Not watching for an expired sign-in; a Needs you member beats a member that is Not watching for a GitHub limit; a paused member left out of the word; all members away gives Not watching; no live member gives "The team has no dots."; reason picks the first member in `memberIds` order, lowers the first letter, and adds "(and 1 more)"; `need` falls back to the suggestion, then to "Nothing needs you."
+- The lead's cached answer drops when a member's run changes status.
+- GET /api/dots/health includes a lead with `team` set. A lead never reads "Not watching: nothing set up".
+- Deleting a member removes its id from the lead. Deleting the only member returns 409. Archiving keeps the id and the row reads Archived.
+- Each lead-only guard route returns 409 for a lead.
+- Client: `TeamPanel` renders the four status words with icons, the Open buttons, and an away row; a long member name and a long need wrap with no ellipsis; the phone layout at 375 px wide has no side scroll. The Dots header counts one Failing member with its lead as "1 need you". Screenshot both widths and compare them with the wireframes in this spec.
+
+Piece 2:
+
+- `casesForTicket` with a list finds Ticket Reviewer's case from PR Reviewer and Regression Runner of the same lead. A dot with no lead finds only its own cases. A dot in another lead finds none.
+- `linkRunResults`: an AI-Vision result of PR Reviewer and an automated spec result of Regression Runner on a Ticket Reviewer case each write a result row on that case. A key both members use maps to the run's own case.
+- `linkedRefs` on PR Reviewer keeps a katalon-studio/product ref that the PR closes or names. The same PR on a dot with no lead drops it, as today.
+- An after-merge check of a merge that closes the ticket adds Ticket Reviewer's manual cases to its test run, and the item route accepts the case.
+- Deleting Ticket Reviewer removes Regression Runner's run items that point at its cases, recounts that test run, and the summary counts them.
+- `designTestCases` still writes under Ticket Reviewer and does not copy a case that exists in the team.
+- Team `buildAll`: a ticket from Ticket Reviewer, a PR link from PR Reviewer and a post-merge result from Regression Runner join into one row with the right status.
+- `releaseCall`: one case per answer and per rule line; blockers come before risks; the milestone defaults to the nearest open one; No tickets for an unknown milestone.
+- GET /api/dots/:id/release returns 409 for a dot that is not a lead.
+
+Piece 4:
+
+- Same `bugSig` from two members within 24 h: one Inbox item with two `sources`, and the second check records `drafted` with the Inbox link.
+- Same test title and shared ticket with different signatures: merged. Same test title with no shared ticket: two drafts. Beyond 24 h: two drafts.
+- Same signature in one member keeps the existing layer 1 behavior.
+- `defectTarget` of PR Reviewer in a lead returns `github:katalon-studio/product`. With no lead it returns the app repo, as today.
+- Approving the merged draft files one issue into the team tracker. Rejecting it stops both members from drafting that bug again.
+- Archiving the first drafter hands the merged draft to the second source: one pending item remains, under the second member, and neither member is blocked from drafting the bug. Archiving a dot whose draft has no other source closes it, and `rejectedFor` ignores that close.
+- A sibling's draft already filed: the later find becomes a "Seen again" comment draft.
+- A dot with no lead drafts exactly as before (regression guard over the existing defect tests).
+
+Piece 3:
+
+- `forTeam` merges `list_runs` and `pending_approvals` across members with a `dot` column and keeps the row limit. A `dotId` outside the team is refused.
+- `open_prs` in a lead chat with 14 repos across members calls `listPulls` 12 times and says "Skipped 2 repos". `get_ticket` calls the tracker once, through Ticket Reviewer.
+- `routeToMember`: each row of the routing table; PR #12 found in one repo; PR #12 in two repos returns choices; no fitting member returns the "Add one" line.
+- "check PR #12 again" in the lead chat queues a review on PR Reviewer, shows "Asked PR Reviewer to check PR #12 again", and the result posts in the lead chat with "From PR Reviewer".
+- A Slack mention of Lead QA answers in its thread and routes the same way. An unnamed message in a channel the lead shares with a member reaches the lead; a message that names the member reaches the member.
+- "Can we release 2026.11?" answers through the view with zero model calls (model usage rows unchanged).
+- Digest: facts built from fixture rows of four members; the opener is the code template; zero model usage rows; one message to chat and one Slack post per scheduled day. POST digest twice in one slot queues once. An on-demand digest replies in the asker's chat only: no Slack post and no phone push.
+- Chat eval (docs/CHAT-EVAL.md): add lead questions for team status, a release question, and a routed rerun.
+
+## Open questions for Huy
+
+- Name. The role preset `qa-lead` in src/routes/roles.ts is labeled "QA lead" and makes one dot that does everything. A new dot type called "Lead QA" next to it in the New dot dialog reads as the same thing. Proposal: keep "Lead QA" for the team dot and rename the preset to "All-in-one QA".
+- Member digests. The four members keep their own daily digests, so the team gets five messages a day. Changing members' posting is out of scope here. Huy can set the members to weekly digests by hand once the lead digest runs.