@hiver/skills 1.0.7 → 1.0.9

package/collections/qa-skills/skills/qa-kit/knowledge-base/hiver/omni/collaborate.md

@@ -0,0 +1,11 @@
+# Omni · Collaborate With Your Team
+
+> Segment `/collaboration?product=hiver-omni` — 3 articles (note the Omni slug is `/collaboration`).
+> Mechanics match HIG — see [../hig/collaborate.md](../hig/collaborate.md).
+
+**Articles:** Collaborating on conversations in Hiver Omni · Collaborate using Shared Notes · Collaborate on email responses using Shared Drafts
+
+- **Shared Notes & @mentions** and **Shared Drafts** work as in HIG, across Omni conversations/channels.
+- **Roles:** Both. **Connected:** notifications, Collaboration Space, templates.
+- **Note:** the Omni collaborate section surfaced **no Approvals sub-category** (present in HIG). Whether **Approvals** is available in Omni is **(unverified)** — confirm via `hiver-explore`.
+- **Source:** https://help.hiverhq.com/collaboration/collaborate-on-conversations-using-shared-notes?product=hiver-omni · https://help.hiverhq.com/collaboration/shared-drafts?product=hiver-omni

package/collections/qa-skills/skills/qa-kit/knowledge-base/hiver/omni/customer-relationships.md

@@ -0,0 +1,9 @@
+# Omni · Manage Customer Relationships
+
+> Segment `/manage-customer-relationships?product=hiver-omni` — 1 sub-category (Manage customers 1) + CSAT, 2 articles.
+> Mechanics match HIG — see [../hig/customer-relationships.md](../hig/customer-relationships.md).
+
+- **Manage customers** — view/manage customer details (contact directory) in Omni, enriched by CRM apps.
+- **CSAT** — customer satisfaction surveys + CSAT reports; delivered in replies/after close; feeds Analytics.
+- **Roles:** Admin (configure); Agent (view/manual CSAT). **Connected:** CRM apps, CSAT report, replies.
+- **Source:** https://help.hiverhq.com/manage-customer-relationships?product=hiver-omni · https://help.hiverhq.com/manage-customer-relationships/using-customer-satisfaction-surveys-csat

package/collections/qa-skills/skills/qa-kit/knowledge-base/hiver/omni/getting-started.md

@@ -0,0 +1,21 @@
+# Omni · Getting Started
+
+> Segment `/getting-started?product=hiver-omni` — 5 sub-categories, 16 articles.
+> **Provenance:** Omni taxonomy captured live from the Hiver Omni help view (Jul 2026); detail from
+> the search index. **(unverified)** items need a `hiver-explore` live pass.
+> Shared mechanics are documented in [../hig/getting-started.md](../hig/getting-started.md); this file
+> covers the **Omni differences**.
+
+**Sub-categories:** Setting up Hiver Omni (3 cats, 11) · First steps (5)
+
+### Setting up Hiver Omni (key difference vs HIG)
+- **What it is:** Omni onboarding can connect **either a Gmail or an Outlook (Microsoft) email client** — HIG is Gmail-only. Dedicated guides exist for each, including an Outlook step-by-step, connecting an Outlook shared mailbox, and **Microsoft Admin Center approval**.
+- **Key concepts:** connect Gmail **or** Outlook, Shared Mailbox connection, Microsoft Admin Center approval (Outlook), mailbox permissions/scopes, adding team members & roles, `?product=hiver-omni` doc marker.
+- **Roles:** Admin (connect mailbox, approve in Microsoft Admin Center, add members); Agent (onboarded after).
+- **Connected features:** Shared Inbox, team members & roles, mailbox permissions, all Omni channels.
+- **Source:** https://help.hiverhq.com/setting-up-hiver-omni?product=hiver-omni · https://help.hiverhq.com/getting-started/setting-up-hiver-for-outlook-a-step-by-step-guide?product=hiver-omni · https://help.hiverhq.com/for-outlook/connecting-an-outlook-shared-mailbox-to-hiver?product=hiver-omni · https://help.hiverhq.com/for-outlook/approve-hiver-microsoft-admin?product=hiver-omni
+
+### First steps
+- **What it is:** Post-connect setup — sender ID, adding team members & managing roles in Omni, My Settings, mobile app.
+- **Roles:** Admin (members/roles); both (My Settings). **Connected:** Shared Inbox, roles, My Settings.
+- **Source:** https://help.hiverhq.com/first-steps/adding-team-members-and-managing-roles-in-hiver-omni?product=hiver-omni · https://help.hiverhq.com/first-steps/my-settings-in-hiver?product=hiver-omni

package/collections/qa-skills/skills/qa-kit/knowledge-base/hiver/omni/hiver-ai.md

@@ -0,0 +1,13 @@
+# Omni · Hiver AI
+
+> Segment `/ai-features?product=hiver-omni` — 2 sub-categories (AI Agents 3, AI Copilot 4), 7 articles.
+> (Note the Omni slug is `/ai-features`.) Feature detail matches HIG — see
+> [../hig/hiver-ai.md](../hig/hiver-ai.md). Omni surfaces a smaller documented set than HIG.
+
+**Sub-categories:** AI Agents (3) · AI Copilot (4)
+
+- **AI Copilot** — Ask AI (grounded in knowledge sources), AI Compose, AI Summarizer, suggested replies. See [../hig/hiver-ai.md](../hig/hiver-ai.md#ai-copilot).
+- **AI Agents** — autonomous classify/prioritize/route; AI Suggested Responses, AI Tagging, AI Thank-you Detector. See [../hig/hiver-ai.md](../hig/hiver-ai.md#ai-agents-autonomous).
+- **AI in Automations** — **AI Tasks** and AI Extract are exposed in Omni automations (see [omni/automate-workflows.md](automate-workflows.md)).
+- **Roles:** Admin (enable/config); Agent (assistive use). All gated by the Hiver AI add-on.
+- **Source:** https://help.hiverhq.com/ai-features?product=hiver-omni · https://help.hiverhq.com/ai-copilot/introducing-ask-ai?product=hiver-omni

package/collections/qa-skills/skills/qa-kit/knowledge-base/hiver/omni/identity-access.md

@@ -0,0 +1,23 @@
+# Omni · Identity & Access  (Omni-only segment)
+
+> Segment `/identity-access?product=hiver-omni` — 2 sub-categories, 15 articles.
+> **This segment does not exist in the HIG product** — it's an Omni/enterprise differentiator for
+> controlling how users log in and are provisioned. Taxonomy captured live (Jul 2026); provider
+> breadth from the live nav, detail from the search index (thin — much is **(unverified)**, resolve
+> via `hiver-explore`).
+
+**Sub-categories:** Single Sign-On (SSO) — 7 categories, 14 articles · User provisioning (SCIM) — 1 article
+
+### Single Sign-On (SSO)
+- **What it is:** One login for the team via an existing **identity provider (IdP)** — no separate Hiver passwords. The **7 sub-categories** strongly imply multiple IdPs (e.g. Okta, Google, Azure AD/Entra, OneLogin, etc.), each with its own SAML setup guide. Only the Okta path was grounded in search; the specific other IdPs and the generic SAML flow are **(unverified)** — enumerate them live.
+- **Key concepts:** SSO, IdP, SAML, no separate passwords, per-IdP configuration, enforce-SSO.
+- **Roles:** Admin (configures SSO). **Connected:** User management, roles & permissions, SCIM.
+- **Source:** https://help.hiverhq.com/identity-access?product=hiver-omni · https://help.hiverhq.com/okta-integration/configuration-of-okta-integration
+
+### User provisioning (SCIM)
+- **What it is:** Automatically add, update, and remove Hiver users through your directory provider (e.g. Okta) — directory-driven user lifecycle so joiners/movers/leavers sync into Hiver without manual admin.
+- **Key concepts:** SCIM, directory provider, auto create/update/deactivate users, provisioning.
+- **Roles:** Admin. **Connected:** SSO, user/account management, roles & permissions.
+- **Source:** https://help.hiverhq.com/identity-access?product=hiver-omni · https://help.hiverhq.com/okta-integration/configuration-of-okta-integration
+
+> **QA note:** SSO/SCIM is high-risk enterprise surface — test enforce-SSO, IdP-initiated vs SP-initiated login, deprovisioning (a removed directory user must lose Hiver access), role mapping, and fallback/lockout paths. Confirm which IdPs are actually supported via `hiver-explore` before scoping.

package/collections/qa-skills/skills/qa-kit/knowledge-base/hiver/omni/multichannel-support.md

@@ -0,0 +1,47 @@
+# Omni · Offer Multi-Channel Support
+
+> Segment `/offer-multi-channel-support?product=hiver-omni` — 8 sub-categories, 24 articles.
+> **This is where Omni diverges most from HIG.** Taxonomy captured live (Jul 2026); detail from the
+> search index. **(unverified)** items need a `hiver-explore` live pass.
+
+**Sub-categories & items:** Manage emails (2 cats, 9) · Manage live chat (4) · **Manage Slack messages (5)** · Manage voice calls (2) · **Manage Tickets (1)** · **Create Web Forms (1)** · Using omnichannel search · Managing work with **My Work**
+
+### Manage emails
+- Same core email mechanics as HIG — assignment, status (Open/Pending/Closed), tags, views, split, templates, managing emails. See [../hig/multichannel-support.md](../hig/multichannel-support.md#manage-emails). Omni email works on **Gmail or Outlook** clients.
+- **Source:** https://help.hiverhq.com/working-with-emails/manage-emails-in-hiver-shared-inbox?product=hiver-omni
+
+### Manage live chat messages
+- Real-time chat channel — embeddable widget, Chat Inbox, chat auto-assignment, chatbots, chat templates, chat CSAT, collision alerts. See [../hig/multichannel-support.md](../hig/multichannel-support.md#manage-live-chat-messages).
+- **Roles:** Admin (setup); Agent (reply). **Source:** https://help.hiverhq.com/hiver-chat/setting-up-live-chat
+
+### Manage Slack messages (Omni-only channel)
+- **What it is:** In Omni, **Slack is a support channel** — handle Slack activity from within Hiver (hub at `/slack?product=hiver-omni`). Distinct from the Slack *notification* integration (which only pushes Hiver events into Slack). Exact channel setup steps **(unverified)**.
+- **Key concepts:** Slack channel vs Slack notification integration, Slack Inbox.
+- **Roles:** Admin (setup **— unverified**); Agent (handle). **Connected:** Shared Inbox, Slack analytics, automations.
+- **Source:** https://help.hiverhq.com/slack?product=hiver-omni
+
+### Manage voice calls (Voice Inbox — Aircall)
+- **What it is:** Admins create a **Voice Inbox** (powered by Aircall) to manage customer calls like a shared inbox; Hiver logs incoming, outgoing, missed calls and voicemails, with Voice Inbox views and settings.
+- **Roles:** Admin (create/configure); Agent (handle/log calls). **Connected:** Aircall, Views, analytics.
+- **Source:** https://help.hiverhq.com/voice-channel/setup-a-voice-inbox · https://help.hiverhq.com/voice-channel/voice-inbox-views-and-call-management
+
+### Manage Tickets (Omni-only)
+- **What it is:** Create and manage **tickets** in Omni. Incoming conversations across channels behave as tickets — land in **Unassigned**, get assigned (manual/auto), carry status (Open/Pending/Closed), and are filterable as Views. A distinct ticket-creation article was thin in search — **(depth unverified)** but the "Manage Tickets" area exists live.
+- **Key concepts:** ticket, Unassigned/Mine/Team/Pending/Closed, assignee, status, auto-assignment.
+- **Roles:** Both. **Connected:** Shared Inbox, Views, auto-assignment, automations, SLA.
+- **Source:** https://help.hiverhq.com/offer-multi-channel-support?product=hiver-omni (Manage Tickets)
+
+### Create Web Forms (Omni-only)
+- **What it is:** Build **web forms** to collect customer details and requests, feeding conversations/tickets into Hiver. Exists live in the Omni nav; a dedicated article was not grounded in search — **(depth unverified)**. Related self-service intake: Customer Portal.
+- **Key concepts:** web form, request intake, custom fields, form → ticket.
+- **Roles:** Admin (build form); customers (submit). **Connected:** Tickets, Customer Portal, custom fields.
+- **Source:** https://help.hiverhq.com/offer-multi-channel-support?product=hiver-omni (Create Web Forms)
+
+### Omnichannel search & My Work (Omni-only surfaces)
+- **Omnichannel search** — search/locate conversations **across all channels** (email, chat, Slack, voice) in one interface; filter by assignee/tags/status, save as Views.
+- **My Work** — a unified personal work surface aggregating what's assigned to you across channels (related to the **Mine** view + My Settings). Dedicated article thin in search — **(depth unverified)**.
+- **Roles:** Agent (personal). **Connected:** Views, all channels, notifications.
+- **Source:** https://help.hiverhq.com/offer-multi-channel-support?product=hiver-omni (Using omnichannel search · Managing work with My Work)
+
+### Manage WhatsApp
+- WhatsApp channel (WhatsApp Inbox; Meta Developer Portal setup). See [../hig/multichannel-support.md](../hig/multichannel-support.md#manage-whatsapp-messages). **Source:** https://help.hiverhq.com/whatsapp-channel/setup-your-whatsapp-inbox

package/collections/qa-skills/skills/qa-kit/knowledge-base/hiver/omni/reporting-analytics.md

@@ -0,0 +1,13 @@
+# Omni · Reporting & Analytics
+
+> Segment `/reporting-and-analytics?product=hiver-omni` — 3 sub-categories, 11 articles.
+> Omni adds **per-channel analytics**. Core mechanics match HIG — see
+> [../hig/reporting-analytics.md](../hig/reporting-analytics.md).
+
+**Sub-categories:** Slack analytics (1) · Email analytics (4) · Chat analytics (3) · + overview, Custom dashboards, FAQs
+
+- **Per-channel analytics (Omni difference):** separate **Slack analytics**, **Email analytics**, and **Chat analytics** — vs HIG's email-only analytics + live-chat. Track workload/performance per channel.
+- **Custom Dashboards** — monitor across inboxes; publish read-only links. (As in HIG, dashboards historically cover email inboxes — verify chat/Slack inclusion in Omni via `hiver-explore`.)
+- **Report types** — Conversations, Users, Tags, Contacts, SLA, CSAT, Sentiment; CSV export (plan-dependent columns; scheduled exports Enterprise-only).
+- **Roles:** Admin. **Connected:** all channels, Tags, SLA, CSAT, AI Sentiment.
+- **Source:** https://help.hiverhq.com/reporting-and-analytics?product=hiver-omni · https://help.hiverhq.com/reporting-analytics/custom-dashboards

package/collections/qa-skills/skills/qa-kit/knowledge-base/hiver/omni/self-service.md

@@ -0,0 +1,11 @@
+# Omni · Enable Self-Service
+
+> Segment `/enable-self-service?product=hiver-omni` — 2 sub-categories, 5 articles.
+> Mechanics match HIG — see [../hig/self-service.md](../hig/self-service.md).
+
+**Sub-categories:** Help Center (4) · Customer Portal (1)
+
+- **Help Center** — publish customer-facing help articles/FAQs; articles can surface in the Live Chat widget and feed Ask AI knowledge sources.
+- **Customer Portal** — web self-service space where customers submit and track requests (related to Omni **Web Forms** and **Tickets**).
+- **Roles:** Admin (manage). **Connected:** Live Chat, Ask AI, Web Forms, Tickets.
+- **Source:** https://help.hiverhq.com/knowledge-base/setting-up-your-knowledge-base · https://help.hiverhq.com/customer-portal/how-to-set-up-a-customer-portal-in-hiver

package/collections/qa-skills/skills/qa-kit/knowledge-base/hiver/omni/sla-policies.md

@@ -0,0 +1,12 @@
+# Omni · Manage SLA Policies
+
+> Segment `/manage-sla-policies?product=hiver-omni` — 3 articles.
+> Mechanics match HIG — see [../hig/sla-policies.md](../hig/sla-policies.md). Omni applies SLAs across
+> its channels (email, chat, voice, Slack), not email only.
+
+**Articles:** Creating SLA Policies · Monitoring and managing SLAs · How SLA timers and breach alerts work (Agent view)
+
+- **What it is:** SLA policies define response/resolution targets; timers and breach alerts show on conversations; Overdue/Due Soon views surface at-risk items. In Omni these apply across channels.
+- **Roles:** Admin (create/manage/permissions); Agent (sees timers/alerts).
+- **Connected features:** Business Hours, Automations (escalation), Views, SLA report, all channels.
+- **Source:** https://help.hiverhq.com/working-with-slas/creating-sla-policies · https://help.hiverhq.com/manage-sla-policies?product=hiver-omni

package/collections/qa-skills/skills/qa-kit/references/clickup-ticket.md

@@ -0,0 +1,163 @@
+# ClickUp Bug Ticket Template
+
+Use this template when generating bug tickets for a confirmed bug. **Every bug ticket must carry its
+screenshot/evidence** — a bug without visual evidence is not ready to file.
+
+## How to file (two modes)
+
+**Preferred — create the ticket and attach the screenshot automatically (ClickUp MCP connected):**
+
+1. Check the ClickUp MCP is available (search for `clickup_*` tools; a quick
+   `clickup_get_workspace_hierarchy` confirms the connection). If it isn't, use the fallback below.
+2. Confirm the target **List** with the user once (e.g. "the Bugs list in the QA space") — don't
+   guess where tickets go.
+3. Create the task with `clickup_create_task` using the fields in the template below (name =
+   `[TC ID] — [Test Case Name]`, description = the body, priority, tags/labels).
+4. **Attach the screenshot(s)** to the created task with `clickup_attach_task_file`, passing the
+   screenshot file path(s) captured during testing. Do this for **every** ❌/⚠️ bug.
+5. Report the created task URL back to the user, and note in the tracker: Status → `Bug`, Notes →
+   the ClickUp link.
+
+**Fallback — copy-paste (ClickUp MCP not connected):** generate one markdown code block per bug so
+the user can paste it into ClickUp, and **explicitly tell them to attach the listed screenshot
+file(s)** to the ticket after pasting. List the exact file paths in the Screenshots section so they
+know what to drag in.
+
+---
+
+## Template
+
+```markdown
+## Bug: [TC ID] — [Test Case Name]
+
+**Priority:** [P0 / P1 / P2]
+**Environment:** Hiver Extension v[version] | Gmail | Plan: [HIG / Omni / Both]
+**SM:** [SM name used during testing]
+**Assignee:** [leave blank — QA to fill]
+**Labels:** bug, [feature-area]
+
+---
+
+### Summary
+[One sentence: what fails and what the user sees. Example: "When admin saves the CRM sync
+configuration with Salesforce, the success message does not appear and the modal stays open."]
+
+---
+
+### Steps to Reproduce
+
+1. [Exact step — name the button, field, or menu path]
+2. [Continue until the bug is triggered]
+3. [Be specific enough that a dev can reproduce without guessing]
+
+**Test Data used:** [any specific values, account emails, field values, etc.]
+
+---
+
+### Expected Behaviour
+[Copy from the Expected Result column of the test case. Number each expected outcome.]
+
+---
+
+### Actual Behaviour
+[Copy from the "Initial Behaviour – Testing 1" column. Describe exactly what happened: exact
+error text, what was visible, what was missing, what state the UI ended up in.]
+
+---
+
+### Screenshots / Evidence
+**Required.** List the screenshot file path(s) captured during testing — these get **attached to
+the ClickUp ticket** (via `clickup_attach_task_file` in the preferred flow, or dragged in manually
+in the fallback). For UI/design bugs attach the screenshot of the failing state (design bugs:
+attach the Figma-vs-build comparison); for API bugs attach the request/response evidence
+(a saved response snippet or screenshot). If no screenshot was captured, re-run the case to capture
+the bug before filing — don't file a bug without evidence.
+
+---
+
+### Additional Context
+[Any relevant spec section, system rule, or Figma node this relates to. Example: "Spec states
+'On failure: Error displayed with specific reason. Admin can retry.' — error is not displayed."]
+```
+
+---
+
+## Priority Guide for Bugs
+
+| Priority | When to use |
+|---|---|
+| P0 | Core functionality is broken. Feature cannot be used. Blocks release. |
+| P1 | Feature works but with significant issue. Workaround exists. Should fix before release. |
+| P2 | Minor issue, cosmetic, or edge case. Can be deferred. |
+
+## Labels to add
+
+Always add: `bug`
+
+Add feature-area label based on what section the TC is in:
+- Section A → `admin-config`
+- Section B → `agent-experience`
+- Section C → `[feature-specific]` (e.g. `crm-sync`, `automation`, `app-actions`)
+- Section D → `analytics`
+- Section E → `regression`
+
+## Example Ticket
+
+```markdown
+## Bug: A-04 — Admin saves CRM sync config but success message does not appear
+
+**Priority:** P0
+**Environment:** Hiver Extension v7.5.6 | Gmail | Plan: HIG
+**SM:** test-support-sm
+**Assignee:** 
+**Labels:** bug, admin-config, crm-sync
+
+---
+
+### Summary
+When admin completes the Salesforce CRM sync setup and clicks Save, the success toast is not
+shown and the modal remains open. The Custom Object is created in the background, but admin
+receives no confirmation.
+
+---
+
+### Steps to Reproduce
+
+1. Log in to Gmail with admin account (tony@test.com)
+2. Go to Settings → Integrations → Custom Objects
+3. Click "Create Custom Object"
+4. Enter CO name: "Test CRM Object"
+5. Select "Salesforce" as the import source
+6. Complete Salesforce OAuth (use test Salesforce account)
+7. Select record type: Contacts
+8. Select 3 fields: Name, Email, Company
+9. Click "Save"
+
+**Test Data used:** Salesforce test account: sf-test@hiver.com | 3 fields selected
+
+---
+
+### Expected Behaviour
+1. Success toast appears: "Custom Object created successfully"
+2. Modal closes
+3. New Custom Object appears in the Custom Objects list
+
+---
+
+### Actual Behaviour
+- Modal remained open after clicking Save
+- No success or error message appeared
+- After refreshing the page, the Custom Object was visible in the list (created in background)
+- No way for admin to know the save succeeded without manually refreshing
+
+---
+
+### Screenshots / Evidence
+screenshot-A04-step9.png
+
+---
+
+### Additional Context
+Spec states: "On success: Custom Object is ready to use." and the test plan notes the success
+message should be visible. The object IS created but the confirmation UI is missing.
+```

package/collections/qa-skills/skills/qa-kit/references/eval.md

@@ -0,0 +1,117 @@
+# Output-Quality Eval — step records, rubrics, and the qa-eval judge
+
+**Phase 1 foundation.** "Performance" in this suite means **the quality/correctness of the output an
+agent produced**, NOT how fast it ran. This file defines how each agent records what it produced and
+how `qa-eval` grades it, so that when the workflow produces a bad result we know **exactly which agent
+produced it**.
+
+---
+
+## 1. Step record — what each agent writes
+
+When an agent finishes an action (a phase that produces an artefact or a decision), it appends a step
+record at `<run>/steps/<skill>-<phase>.json`:
+
+```json
+{
+  "run_id": "hiver-notes-20260709-1530",
+  "skill": "qa-ui-author",
+  "phase": "tracker",
+  "input":  { "spec": "spec.md", "handoff": "handoff.json", "effort": "standard" },
+  "output": { "artifact": "tracker.xlsx", "summary": "38 cases A12/B8/C14/D4" },
+  "self_check": { "passed": true, "notes": "no unfilled placeholders; all sections present" },
+  "verdict": null
+}
+```
+
+- `output.artifact` points at the real file the judge will open.
+- `self_check` is a **hint from the agent about itself** — never the verdict.
+- `verdict` is left `null`. **Only `qa-eval` fills it.** An agent does not grade its own work as truth.
+
+### Step record vs action log — two different things
+There are **two** trails per agent, and they answer different questions:
+- **Step record** (`steps/<skill>-<phase>.json`, above) = *what the agent produced* — the output
+  artefact + summary. This is what `qa-eval` grades.
+- **Action log** (`logs/<skill>.jsonl`) = *what the agent did* — one appended line per meaningful
+  action (tool called, page navigated, script run, decision made, file written):
+  `{"ts":"<iso>","skill":"qa-ui-run","action":"click","detail":"Add-note trigger, TC-14"}`.
+  This is the forensic trace. When `qa-eval` returns a FAIL, the action log is where you read
+  *why* it broke — the exact action before things went wrong.
+
+---
+
+## 2. Rubrics — what "good output" means, per agent
+
+Rubrics live in this file so all agents share one definition. Each rubric item is tagged **[B]locking**
+(its violation → FAIL) or **[Q]uality** (its violation → at most DEGRADED).
+
+| Agent | Judged artefact | Rubric |
+|---|---|---|
+| **hiver-explore** | `spec.md` | [B] no unfilled `<placeholders>` · [B] every claim tagged [D]/[L] · [Q] selectors captured · [Q] doc-vs-live noted |
+| **qa-kit** | `handoff.json` triage | [B] classification matches the diff · [B] product (HIG/Omni) set · [Q] impacted services listed · [Q] key risks surfaced |
+| **qa-ui-author** | `tracker.xlsx` | [B] matches `tracker-format.md` columns · [B] zero unfilled placeholders · [B] every case has Priority + Expected · [Q] covers areas A–D for the feature · [Q] case count fits effort · [Q] preconditions name SM + extension version |
+| **qa-api-author** | `tracker.xlsx` | [B] API column block present + correct · [B] each case has method/endpoint/expected status · [Q] auth + error-contract cases present · [Q] count fits effort |
+| **qa-ui-run** | tracker Testing-1 + screenshots | [B] every non-⏭️ case has a Testing-1 verdict · [B] no case silently dropped · [B] a screenshot exists for each ❌/⚠️ · [Q] observations are concrete, not vague |
+| **qa-api-run** | tracker results | [B] ran against staging (not prod) · [B] status+body recorded per executed case · [B] destructive calls were gated · [Q] response snippets included |
+| **qa-bugs** | ClickUp ticket | [B] repro + expected + actual present · [B] maps to a real failing TC · [B] screenshot/evidence attached · [Q] priority + labels set |
+| **playwright-gen** | spec + run result | [B] spec compiles and runs · [B] no hallucinated page-object methods · [Q] assertions map to Expected · [Q] self-heal attempts logged with reasons |
+
+Feature-specific coverage (the [Q] "covers the feature" items) is judged against the `spec.md` /
+handoff scope, not a fixed list.
+
+---
+
+## 3. Verdicts — PASS / DEGRADED / FAIL
+
+`qa-eval` returns exactly one verdict per step, judging the **output artefact** against the rubric:
+
+- **PASS** — every [B] item satisfied and most [Q] items too. The output is correct and usable
+  downstream as-is.
+- **DEGRADED** — every [B] item satisfied, but one or more [Q] items missed. The output is **usable
+  but weaker than it should be** (e.g. vague observations, a thin risk register, a missing P2 edge
+  case). Downstream can proceed; the gap is noted for improvement.
+- **FAIL** — **one or more [B] (blocking) items violated.** The output is missing, malformed, or wrong
+  in a way that makes it unsound to build on. Examples:
+  - a tracker missing required columns, or with unfilled `<placeholders>`
+  - execution results where cases have **no recorded verdict** (we don't actually know if they passed)
+  - a triage that **misclassified** the change (UI vs API)
+  - a bug ticket with no reproduction steps or no evidence
+  - a generated spec that **doesn't compile / run**, or that calls page-object methods that don't exist
+
+  FAIL is about the **deliverable being unsound** — not about a crash or a slow run.
+
+### FAIL policy: **warn and continue**
+A FAIL does **not** halt the pipeline. `qa-eval` flags it loudly in the report and the human decides
+whether to re-run that stage, patch by hand, or accept it. Rationale: the pipeline is human-supervised;
+a false-FAIL should never block a QA who can see the artefact is actually fine. (This policy is
+configurable later; for now: warn, never block.)
+
+---
+
+## 4. qa-eval — the judge
+
+- **Runs automatically at the end of every pipeline** (after the last agent), and can also be invoked
+  on demand.
+- Resolves the run via `.current-run`, reads every `steps/*.json`, opens each referenced artefact, and
+  grades it against its rubric.
+- **Independence:** the judge is a separate agent from the one being judged; it re-derives the verdict
+  from the artefact itself, using `self_check` only as a hint to double-check.
+- **Two check types:**
+  - **Deterministic** (a small script, not the model): placeholder scan, tracker column conformance,
+    case-count vs effort, "does the spec compile/run", screenshot-exists. Exact and cheap.
+  - **Judgement** (LLM-as-judge): classification correctness, coverage adequacy, observation quality,
+    assertion↔Expected mapping. Model reserved for the subjective calls.
+- **Output:** `<run>/trace/report.md` — a per-agent table (agent · phase · verdict · defect) plus a
+  rollup naming the **first FAIL** as where the workflow's output quality broke.
+
+Example report:
+```
+Run hiver-notes-20260709-1530 — output quality
+  hiver-explore  spec      PASS
+  qa-kit         triage    PASS
+  qa-ui-author   tracker   PASS
+  qa-ui-run      execute   FAIL   6/38 cases have no Testing-1 verdict   ← broke here
+  qa-bugs        tickets   DEGRADED  ticket TC-14 missing labels
+Rollup: output quality broke at qa-ui-run (execute). Missing verdicts: TC-14,17,19,22,30,33.
+Policy: warn-and-continue — pipeline was not halted.
+```

package/collections/qa-skills/skills/qa-kit/references/flow-capture.md

@@ -0,0 +1,147 @@
+# flow-capture — API tests from real UI user flows
+
+**What this is.** An opt-in add-on that turns a **round-1 UI user-flow run** into **api-shield API
+tests**. While the UI flow is exercised in the browser, the real API traffic it fires is captured,
+cleaned, and — only after a human approves — turned into a draft PR on the api-shield framework.
+
+This add-on is used by two skills:
+- **`qa-ui-run`** — captures traffic during its browser first pass (Phase 5).
+- **`qa-api-run`** — turns an approved recording into api-shield tests + a draft PR.
+
+It exists because the round-1 click-through already drives the real app; the traffic it produces is
+ground-truth for the API contract (real payload + real response) that we would otherwise have to
+guess. See also `hiver-context.md` (Hiver concepts) and `tracker-format.md` (the API column block).
+
+---
+
+## Repos involved (keep these straight)
+
+| Purpose | Repo | Local clone | Branch |
+|---|---|---|---|
+| UI user-flow automation (the *source* of the traffic) | `GrexIt/playwright-hig-automation` | `~/Documents/poc-playwright` | `feature/remblebee` |
+| API test framework (where generated tests + PR land) | api-shield | `~/Documents/api-s.h.i.e.l.d` | a **new** branch per flow, e.g. `qa/<flow>-api-tests` |
+
+The api-shield PR is a **separate branch on the api-shield repo** — it is *not* pushed to
+`feature/remblebee`. `feature/remblebee` is only the UI-flow source.
+
+---
+
+## Pipeline and the two human gates
+
+```
+STAGE 1 — CAPTURE   (qa-ui-run Phase 5, opt-in)
+  Run the UI user flow → capture network via read_network_requests → tag each request with the
+  UI action that fired it → normalize → emit  qa-output/<feature>/flow-recording-<date>.json
+
+        ── GATE A ──  the UI flow must have PASSED Testing 1 (✅). A ❌/⚠️ flow is NOT eligible —
+                      we never codify a broken flow as an API baseline.
+
+        ── GATE B ──  a human reads the recorded flow (endpoints, payloads, responses, in order)
+                      and confirms the behaviour is correct.
+
+STAGE 2 — GENERATE  (qa-api-run, opt-in — HUMAN IN THE LOOP)
+  Ask explicitly: "Create the api-shield PR for this flow? (yes / no)"
+    • no  → stop. Leave the recording in qa-output for later. Nothing is written to api-shield.
+    • yes → generate spec + payload fixture → open a DRAFT PR on api-shield → dev verifies.
+  Never auto-merge. The PR is always a draft requiring dev sign-off.
+```
+
+The principle mirrors `playwright-gen`: **we only codify what is green.** Capture is cheap and can
+run on any pass; *promotion to an api-shield PR* is the gated, human-approved step.
+
+---
+
+## The recording (the intermediate artefact)
+
+The recording decouples capture from generation — inspect and fix it before any code is written.
+
+```jsonc
+{
+  "feature": "conversation-assignment",
+  "product": "HIG",                 // or Omni
+  "env": "staging",                 // hard gate — capture must be against staging, never prod
+  "ui_flow_status": "PASS",         // Gate A: only PASS recordings are promotable
+  "source": {                       // where the UI flow came from
+    "repo": "playwright-hig-automation",
+    "branch": "feature/remblebee",
+    "spec": "specs/<flow>.spec.ts"  // if driven by a Playwright spec; else "manual"
+  },
+  "recorded_flow": [
+    {
+      "action": "Assign conversation to Agent B",   // the UI intent = the user flow
+      "calls": [
+        {
+          "method": "PATCH",
+          "path_template": "/gx/api/sm/{sm_id}/conversations/{conv_id}",
+          "request_body": { "assignee_id": "{agent_id}" },   // parameterized, no real IDs
+          "response_status": 200,
+          "assert_fields": { "assignee_id": "{agent_id}", "status": "assigned" },
+          "variables_used": ["sm_id", "conv_id", "agent_id"]
+        }
+      ]
+    }
+  ],
+  "variables": { "sm_id": "…", "conv_id": "…", "agent_id": "…" }  // resolved from config, redacted
+}
+```
+
+---
+
+## Normalization rules (deterministic — run these before writing the recording)
+
+Apply in order. If any step cannot guarantee its invariant, **stop and surface it** — do not write.
+
+1. **Allowlist filter.** Keep only Hiver API hosts/paths (the v2 / approvals / `*.hiverhq.com/api`
+   endpoints). Drop analytics, Gainsight, static assets, polling/heartbeat. One click fires ~30
+   requests; keep the few that matter.
+2. **Redact.** Strip `Authorization`, `Cookie`, csrf, `set-cookie`. Replace, never persist. Run a
+   final self-check: if any secret-shaped value survives, **refuse to write the recording**.
+3. **Parameterize.** Detect volatile values (IDs in path, emails, SM IDs, timestamps) → named
+   placeholders + a `variables` map. This is heuristic and **will misfire** — surface every guess
+   for human confirmation at Gate B; do not commit them silently.
+4. **Path-template + dedup key.** `…/conversations/12345` → `…/conversations/{conv_id}`. The key
+   `(method + path_template + action)` decides update-existing-spec vs new-spec.
+
+---
+
+## Generating api-shield tests (Stage 2, on "yes" at the human gate)
+
+Match the api-shield pattern exactly (read a sibling spec first — e.g.
+`tests/incredibles/specs/test_approvals_creation.py` — don't invent structure):
+
+- **Payload** → `tests/<domain>/helpers/payloads/<flow>.json`
+- **Spec** → `tests/<domain>/specs/test_<flow>.py`, reusing `hiver_login` / `get_token` /
+  `RequestUtility` and loading the payload via `read_json`.
+- **Domain** — pick from the impacted services / triage; ask if ambiguous.
+- **Auth translation (the crux).** The captured `Authorization: Bearer …` is **never** replayed.
+  The generated test authenticates itself via the framework's `hiver_login` → `get_token()` flow,
+  and maps the captured user email → `get_incredibles_email` / config.
+- **Assertions.** Assert the captured status + a **small set of stable response fields** (like the
+  existing specs assert `error` / `message`). Never assert the whole body — it's brittle.
+- **Marker.** Add a header comment
+  `# GENERATED FROM RECORDING <id> — happy-path characterization, review before merge`
+  and a `@pytest.mark.recorded` marker.
+- **Draft PR.** Branch `qa/<flow>-api-tests` on api-shield → commit → `gh pr create --draft`. The PR
+  body links the source recording, lists the endpoints covered, and includes a dev-review checklist.
+
+---
+
+## What this add-on does and does NOT do (state these in the PR)
+
+- **Capture = happy path only.** It cannot produce 401/403/422/boundary cases — `qa-api-run`'s normal
+  generator still owns those. Recording *complements* generated cases; it does not replace them.
+- **Capture ≠ correct.** A recording is what the API *did*, not what it *should* do. So the PR is a
+  **regression/characterization** baseline and always a **draft requiring dev sign-off**.
+- **Async flows.** Some actions fire background jobs; the immediate response may not reflect final
+  state. Flag these rather than asserting the transient body.
+
+---
+
+## Safety gates (all must hold)
+
+1. Capture is **opt-in** (until redaction + parameterization are trusted; flip to auto later).
+2. Capture runs against **staging only** — never production.
+3. **Gate A**: only PASS (✅) UI flows are promotable.
+4. **Gate B**: a human confirms the recorded flow is correct.
+5. **Human-in-the-loop generation**: explicit yes/no before any api-shield write or PR.
+6. The api-shield PR is always a **draft**; a dev verifies before merge. Never auto-merge.