@piwitests/reporter 0.45.0 → 0.46.0

package/dist/internal/capture/pick-on-failure.js

@@ -335,6 +335,17 @@ function installPickerOverlay(arg) {
     return;
   }
   const Z = 2147483600;
+  const testIdAttr = arg.testIdAttribute || "data-testid";
+  const words = {
+    banner: "Piwi inspector \u2014 click any element to generate locators for it",
+    keys: "\u2191 parent \xB7 \u2193 child \xB7 Esc skip",
+    keysHovering: "click to pick \xB7 \u2191 parent \xB7 \u2193 child \xB7 Esc skip",
+    analyzing: "Analyzing element\u2026"
+  };
+  for (const key of Object.keys(words)) {
+    const given = arg.strings?.[key];
+    if (typeof given === "string" && given) words[key] = given;
+  }
   const highlight = doc.createElement("div");
   highlight.id = "__piwi_picker_highlight";
   highlight.style.cssText = `position:fixed;pointer-events:none;z-index:${Z};display:none;box-sizing:border-box;border:2px solid #a855f7;background:rgba(168,85,247,.14);border-radius:4px;box-shadow:0 0 0 1px rgba(255,255,255,.9),0 0 0 3px rgba(59,7,100,.55),inset 0 0 0 1px rgba(255,255,255,.5);`;
@@ -359,27 +370,53 @@ function installPickerOverlay(arg) {
   const MONO = "ui-monospace,SFMono-Regular,Menlo,Consolas,monospace";
   const hlLocator = (expr) => `<code style="font-family:${MONO}">${hlTokens(expr)}</code>`;
   const head = doc.createElement("div");
-  head.innerHTML = arg.transport === "postMessage" ? "Click an element to generate locators" : arg.failing ? `Piwi locator picker \u2014 click the element that should replace ${hlLocator(arg.failing)}` : "Piwi inspector \u2014 click any element to generate locators for it";
+  if (arg.transport === "postMessage") head.textContent = "Click an element to generate locators";
+  else if (arg.failing)
+    head.innerHTML = `Piwi locator picker \u2014 click the element that should replace ${hlLocator(arg.failing)}`;
+  else head.textContent = words.banner;
   const locatorLine = doc.createElement("div");
   locatorLine.id = "__piwi_picker_locator";
   locatorLine.style.cssText = `display:none;margin-top:7px;padding:5px 9px;border-radius:7px;background:#0b1120;border:1px solid #4c1d95;font:13.5px/1.55 ${MONO};word-break:break-word;overflow-wrap:anywhere;`;
   const foot = doc.createElement("div");
   foot.id = "__piwi_picker_foot";
   foot.style.cssText = "color:#9ca3af;margin-top:6px;font-size:12px;";
-  foot.textContent = "\u2191 parent \xB7 \u2193 child \xB7 Esc skip";
+  foot.textContent = words.keys;
   banner.appendChild(head);
   banner.appendChild(locatorLine);
   banner.appendChild(foot);
   const label = doc.createElement("div");
   label.id = "__piwi_picker_label";
   label.style.cssText = `position:fixed;pointer-events:none;z-index:${Z + 1};display:none;box-sizing:border-box;max-width:min(620px,92vw);background:#0b1120;color:#f9fafb;border:1px solid #7c3aed;border-radius:7px;padding:4px 8px;font:12.5px/1.45 ${MONO};white-space:nowrap;overflow:hidden;text-overflow:ellipsis;box-shadow:0 4px 18px rgba(0,0,0,.5);`;
-  doc.body.appendChild(highlight);
-  doc.body.appendChild(label);
-  doc.body.appendChild(banner);
+  const mountParent = () => {
+    let modal = null;
+    try {
+      modal = doc.querySelector("dialog:modal");
+    } catch {
+      modal = null;
+    }
+    if (!modal) return doc.body;
+    const s = g.getComputedStyle(modal);
+    const holdsFixed = s.transform !== "none" || s.perspective !== "none" || s.filter !== "none" || /\b(paint|layout|strict|content)\b/.test(s.contain) || /\b(transform|perspective|filter)\b/.test(s.willChange);
+    return holdsFixed ? doc.body : modal;
+  };
+  const mount = (...nodes) => {
+    const parent = mountParent();
+    for (const node of nodes) parent.appendChild(node);
+    if (parent !== doc.body) {
+      parent.addEventListener(
+        "close",
+        () => {
+          for (const node of nodes) if (node.parentNode === parent) doc.body.appendChild(node);
+        },
+        { once: true }
+      );
+    }
+  };
+  mount(highlight, label, banner);
   const escJs = (s) => s.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
   const describe = (el) => {
     const tag = (el.tagName || "?").toLowerCase();
-    const testId = el.getAttribute && el.getAttribute("data-testid");
+    const testId = el.getAttribute && el.getAttribute(testIdAttr);
     if (testId) return `getByTestId('${escJs(testId)}')`;
     if (el.labels && el.labels.length > 0) {
       const labelText = (el.labels[0].textContent || "").replace(/\s+/g, " ").trim().slice(0, 80);
@@ -414,7 +451,7 @@ function installPickerOverlay(arg) {
       const el = chain2[i];
       const tag = (el.tagName || "").toLowerCase();
       if (ACTIONABLE_TAGS.includes(tag)) return i;
-      if (el.getAttribute && (el.getAttribute("role") || el.getAttribute("data-testid"))) return i;
+      if (el.getAttribute && (el.getAttribute("role") || el.getAttribute(testIdAttr))) return i;
     }
     return 0;
   };
@@ -470,7 +507,7 @@ function installPickerOverlay(arg) {
       locatorLine.style.display = "block";
     }
     placeLabel(r);
-    foot.textContent = "click to pick \xB7 \u2191 parent \xB7 \u2193 child \xB7 Esc skip";
+    foot.textContent = words.keysHovering;
   };
   const redescribe = () => {
     labeled = null;
@@ -533,6 +570,13 @@ function installPickerOverlay(arg) {
     banner.remove();
     if (g.__piwiRedescribe === redescribe) delete g.__piwiRedescribe;
   };
+  const teardown = () => {
+    removePickingListeners();
+    removeSuppressed();
+    doc.removeEventListener("click", stop, true);
+    doc.removeEventListener("keydown", stop, true);
+    cleanup();
+  };
   const reportPicked = (el) => {
     removePickingListeners();
     highlight.style.display = "none";
@@ -543,13 +587,13 @@ function installPickerOverlay(arg) {
       g.__piwiSnapshotExtras?.onPick?.();
       doc.addEventListener("click", stop, true);
       doc.addEventListener("keydown", stop, true);
-      foot.textContent = "Analyzing element\u2026";
+      foot.textContent = words.analyzing;
       g.parent.postMessage({ type: "elementPicked", attrs }, "*");
     } else {
       removeSuppressed();
       g.__piwiPickedElement = el;
       g.__piwiPickState = "picked";
-      foot.textContent = "Analyzing element\u2026";
+      foot.textContent = words.analyzing;
     }
   };
   const reportSkipped = () => {
@@ -597,7 +641,7 @@ function installPickerOverlay(arg) {
       }
     });
   };
-  g.__piwiPickCleanup = cleanup;
+  g.__piwiPickCleanup = teardown;
   doc.addEventListener("mousemove", onMove, true);
   doc.addEventListener("click", onClick, true);
   doc.addEventListener("keydown", onKey, true);
@@ -619,6 +663,26 @@ function showAnchorPicker(arg) {
   }
   const Z = 2147483600;
   const { tagRoles, inputRoles, roleSources, leafRole, leafLevel, leafTestId } = arg;
+  const testIdAttr = arg.testIdAttribute || "data-testid";
+  const words = {
+    title: "Scope to stable parents (optional)",
+    hint: "Pick one or more parents to anchor the locator to. Hover a row to see the parent.",
+    noneSelected: "No parents selected \u2014 standard alternatives only.",
+    matchesOne: "\u2713 Selection matches exactly 1 element",
+    matchesMany: "\u2717 Selection matches {count} elements",
+    countUnavailable: "Match count unavailable",
+    containsOne: "contains exactly 1 matching element",
+    containsMany: "contains {count} matching elements",
+    needsTestId: `add a ${testIdAttr} to make this usable`,
+    noHook: "no stable hook",
+    use: "Use selected parents",
+    skip: "Skip (Esc)"
+  };
+  for (const key of Object.keys(words)) {
+    const given = arg.strings?.[key];
+    if (typeof given === "string" && given) words[key] = given;
+  }
+  const counted = (template, n) => template.replace("{count}", String(n));
   const roleOf = (n) => {
     const explicit = n.getAttribute && n.getAttribute("role");
     if (explicit) return explicit;
@@ -634,9 +698,11 @@ function showAnchorPicker(arg) {
     const al = n.getAttribute && n.getAttribute("aria-level");
     return al && /^\d+$/.test(al) ? Number(al) : null;
   };
+  const leafCountable = !!leafTestId || roleOf(el) === leafRole;
   const leafMatches = (scope) => {
     try {
-      if (leafTestId) return scope.querySelectorAll(`[data-testid=${JSON.stringify(leafTestId)}]`).length;
+      if (leafTestId) return scope.querySelectorAll(`[${testIdAttr}=${JSON.stringify(leafTestId)}]`).length;
+      if (!leafCountable) return -1;
       const nodes = scope.querySelectorAll(roleSources);
       if (nodes.length > 2e3) return -1;
       let matched = 0;
@@ -672,12 +738,12 @@ function showAnchorPicker(arg) {
     depth++;
     const tag = (node.tagName || "").toLowerCase();
     if (tag === "body" || tag === "html") break;
-    const testId = node.getAttribute("data-testid");
+    const testId = node.getAttribute(testIdAttr);
     const id = node.getAttribute("id");
     const ariaLabel = node.getAttribute("aria-label");
     const role = roleOf(node);
     const info = { tag, depth, testId: testId || null, id: id || null, ariaLabel: ariaLabel || null, role };
-    if (testId) info.testIdCount = count(`[data-testid=${JSON.stringify(testId)}]`);
+    if (testId) info.testIdCount = count(`[${testIdAttr}=${JSON.stringify(testId)}]`);
     if (id) {
       try {
         info.idCount = count(`#${doc.defaultView.CSS.escape(id)}`);
@@ -696,7 +762,7 @@ function showAnchorPicker(arg) {
       if (ariaLabel) info.labeledRoleCount = labeledCount;
     }
     info.scopedLeafCount = leafMatches(node);
-    const hookLabel = testId ? `data-testid="${testId}"` : id ? `#${id}` : ariaLabel && role ? `${role} "${ariaLabel}"` : role ? `role ${role}` : "no stable hook";
+    const hookLabel = testId ? `${testIdAttr}="${testId}"` : id ? `#${id}` : ariaLabel && role ? `${role} "${ariaLabel}"` : role ? `role ${role}` : words.noHook;
     rows.push({
       node,
       info,
@@ -718,13 +784,13 @@ function showAnchorPicker(arg) {
   const pr = el.getBoundingClientRect();
   pickedOutline.style.cssText = `position:fixed;pointer-events:none;z-index:${Z};box-sizing:border-box;border:2px solid #a855f7;background:rgba(168,85,247,.14);border-radius:4px;box-shadow:0 0 0 1px rgba(255,255,255,.9),0 0 0 3px rgba(59,7,100,.55);left:${pr.left}px;top:${pr.top}px;width:${pr.width}px;height:${pr.height}px;`;
   const panel = doc.createElement("div");
-  panel.style.cssText = `position:fixed;top:12px;right:12px;z-index:${Z + 3};width:340px;max-height:82vh;overflow:auto;background:#111827;color:#f9fafb;border-radius:10px;padding:16px;font:12px/1.5 system-ui,sans-serif;box-shadow:0 8px 40px rgba(0,0,0,.5);`;
+  panel.style.cssText = `position:fixed;top:12px;right:12px;z-index:${Z + 3};width:min(340px,calc(100vw - 56px));max-height:82vh;overflow:auto;background:#111827;color:#f9fafb;border-radius:10px;padding:16px;font:12px/1.5 system-ui,sans-serif;box-shadow:0 8px 40px rgba(0,0,0,.5);`;
   const title = doc.createElement("div");
   title.style.cssText = "font-weight:600;font-size:13px;margin-bottom:2px;";
-  title.textContent = "Scope to stable parents (optional)";
+  title.textContent = words.title;
   const sub = doc.createElement("div");
   sub.style.cssText = "color:#9ca3af;margin-bottom:10px;";
-  sub.textContent = "Pick one or more parents to anchor the locator to. Hover a row to see the parent.";
+  sub.textContent = words.hint;
   panel.appendChild(title);
   panel.appendChild(sub);
   const selected = /* @__PURE__ */ new Set();
@@ -732,7 +798,7 @@ function showAnchorPicker(arg) {
   footer.style.cssText = "margin:10px 0;font-weight:600;";
   const segMatches = (scope, info) => {
     try {
-      if (info.testId) return Array.from(scope.querySelectorAll(`[data-testid=${JSON.stringify(info.testId)}]`));
+      if (info.testId) return Array.from(scope.querySelectorAll(`[${testIdAttr}=${JSON.stringify(info.testId)}]`));
       if (info.id) return Array.from(scope.querySelectorAll(`#${doc.defaultView.CSS.escape(info.id)}`));
       const nodes = Array.from(scope.querySelectorAll(roleSources));
       if (nodes.length > 2e3) return [];
@@ -756,14 +822,15 @@ function showAnchorPicker(arg) {
     let total = 0;
     for (const s of scopes) {
       const c = leafMatches(s);
-      if (c > 0) total += c;
+      if (c < 0) return -1;
+      total += c;
       if (total > 50) return total;
     }
     return total;
   };
   const refreshFooter = () => {
     if (selected.size === 0) {
-      footer.textContent = "No parents selected \u2014 standard alternatives only.";
+      footer.textContent = words.noneSelected;
       footer.style.color = "#9ca3af";
       g.__piwiPickChainCount = void 0;
       return;
@@ -771,10 +838,10 @@ function showAnchorPicker(arg) {
     const c = chainCount();
     g.__piwiPickChainCount = c;
     if (c === 1) {
-      footer.textContent = "\u2713 Selection matches exactly 1 element";
+      footer.textContent = words.matchesOne;
       footer.style.color = "#4ade80";
     } else {
-      footer.textContent = c < 0 ? "Match count unavailable" : `\u2717 Selection matches ${c} elements`;
+      footer.textContent = c < 0 ? words.countUnavailable : counted(words.matchesMany, c);
       footer.style.color = "#fbbf24";
     }
   };
@@ -791,7 +858,8 @@ function showAnchorPicker(arg) {
     code.textContent = `<${row.info.tag}> ${row.hookLabel}`;
     const hint = doc.createElement("span");
     hint.style.cssText = "color:#9ca3af;";
-    hint.textContent = row.selectable ? row.info.scopedLeafCount === 1 ? "contains exactly 1 matching element" : `contains ${row.info.scopedLeafCount ?? "?"} matching elements` : "add a data-testid to make this usable";
+    const inside = row.info.scopedLeafCount ?? -1;
+    hint.textContent = row.selectable ? inside === 1 ? words.containsOne : inside < 0 ? words.countUnavailable : counted(words.containsMany, inside) : words.needsTestId;
     text.appendChild(code);
     text.appendChild(hint);
     line.appendChild(box);
@@ -829,6 +897,7 @@ function showAnchorPicker(arg) {
     outline.remove();
     outlineLabel.remove();
     pickedOutline.remove();
+    if (g.__piwiAnchorCleanup === cleanup) delete g.__piwiAnchorCleanup;
   };
   const done = (state) => {
     g.__piwiPickAnchors = state === "done" ? rows.filter((_, i) => selected.has(i)).map((r) => r.info) : [];
@@ -845,7 +914,7 @@ function showAnchorPicker(arg) {
   buttonRow.style.cssText = "display:flex;gap:8px;margin-top:4px;";
   const useBtn = doc.createElement("button");
   useBtn.style.cssText = "flex:1;background:#7c3aed;color:#fff;border:none;border-radius:6px;padding:8px;cursor:pointer;font:600 12px system-ui;";
-  useBtn.textContent = "Use selected parents";
+  useBtn.textContent = words.use;
   useBtn.addEventListener("click", (e) => {
     e.preventDefault();
     e.stopImmediatePropagation();
@@ -853,7 +922,7 @@ function showAnchorPicker(arg) {
   });
   const skipBtn = doc.createElement("button");
   skipBtn.style.cssText = "background:none;border:1px solid #374151;color:#9ca3af;border-radius:6px;padding:8px 10px;cursor:pointer;font:12px system-ui;";
-  skipBtn.textContent = "Skip (Esc)";
+  skipBtn.textContent = words.skip;
   skipBtn.addEventListener("click", (e) => {
     e.preventDefault();
     e.stopImmediatePropagation();
@@ -865,10 +934,32 @@ function showAnchorPicker(arg) {
   refreshFooter();
   g.__piwiAnchorCleanup = cleanup;
   doc.addEventListener("keydown", onKey, true);
-  doc.body.appendChild(pickedOutline);
-  doc.body.appendChild(outline);
-  doc.body.appendChild(outlineLabel);
-  doc.body.appendChild(panel);
+  const mountParent = () => {
+    let modal = null;
+    try {
+      modal = doc.querySelector("dialog:modal");
+    } catch {
+      modal = null;
+    }
+    if (!modal) return doc.body;
+    const s = g.getComputedStyle(modal);
+    const holdsFixed = s.transform !== "none" || s.perspective !== "none" || s.filter !== "none" || /\b(paint|layout|strict|content)\b/.test(s.contain) || /\b(transform|perspective|filter)\b/.test(s.willChange);
+    return holdsFixed ? doc.body : modal;
+  };
+  const mount = (...nodes) => {
+    const parent = mountParent();
+    for (const node2 of nodes) parent.appendChild(node2);
+    if (parent !== doc.body) {
+      parent.addEventListener(
+        "close",
+        () => {
+          for (const node2 of nodes) if (node2.parentNode === parent) doc.body.appendChild(node2);
+        },
+        { once: true }
+      );
+    }
+  };
+  mount(pickedOutline, outline, outlineLabel, panel);
 }
 
 // ../picker-dom/src/overlay-confirm.ts
@@ -1068,7 +1159,7 @@ function isAutoGenerated(value) {
   return false;
 }
 var TEST_DATA_ATTRS = /* @__PURE__ */ new Set(["data-test", "data-test-id", "data-qa", "data-qa-id", "data-cy", "data-e2e"]);
-function generateAlternatives(attrs) {
+function generateAlternatives(attrs, options = {}) {
   const alts = [];
   const seen = /* @__PURE__ */ new Set();
   const add = (loc) => {
@@ -1079,12 +1170,14 @@ function generateAlternatives(attrs) {
   };
   const { accessibleName } = attrs;
   const tag = attrs.tagName;
-  const role = resolveAriaRole(attrs);
+  const role = options.role !== void 0 ? options.role : resolveAriaRole(attrs);
   const counts = attrs.selectorCounts;
   const isUnique = (n) => n == null || n <= 1;
   const ambiguityPenalty = (n) => n != null && n > 1 ? 45 : 0;
   const text = attrs.textContent ? attrs.textContent.replace(/\s+/g, " ").trim() : null;
-  const testId = attr(attrs, "data-testid");
+  const testIdAttribute = options.testIdAttribute || "data-testid";
+  const selectable = (name2) => name2.toLowerCase() !== testIdAttribute.toLowerCase();
+  const testId = attr(attrs, testIdAttribute);
   if (testId && isUnique(counts?.testId)) {
     add({
       locator: `getByTestId('${esc(testId)}')`,
@@ -1143,7 +1236,7 @@ function generateAlternatives(attrs) {
     });
   }
   const id = attr(attrs, "id");
-  if (id && !isAutoGenerated(id) && isUnique(counts?.id)) {
+  if (id && selectable("id") && !isAutoGenerated(id) && isUnique(counts?.id)) {
     const selector = isCssSafeId(id) ? `#${id}` : `[id="${escCssAttrValue(id)}"]`;
     add({
       locator: `locator('${esc(selector)}')`,
@@ -1153,7 +1246,7 @@ function generateAlternatives(attrs) {
     });
   }
   const name = attr(attrs, "name");
-  if (name && isUnique(counts?.name)) {
+  if (name && selectable("name") && isUnique(counts?.name)) {
     const selector = `[name="${escCssAttrValue(name)}"]`;
     add({
       locator: `locator('${esc(selector)}')`,
@@ -1198,7 +1291,7 @@ function generateAlternatives(attrs) {
           score: scores.testId
         });
       }
-      if (!idAnchorDone && anc.id && !isAutoGenerated(anc.id) && anc.idCount === 1) {
+      if (!idAnchorDone && anc.id && selectable("id") && !isAutoGenerated(anc.id) && anc.idCount === 1) {
         idAnchorDone = true;
         const anchorSelector = isCssSafeId(anc.id) ? `#${anc.id}` : `[id="${escCssAttrValue(anc.id)}"]`;
         add({
@@ -1208,7 +1301,7 @@ function generateAlternatives(attrs) {
           score: scores.id
         });
       }
-      if (!dataAnchorDone && anc.dataAttr && anc.dataAttrCount === 1) {
+      if (!dataAnchorDone && anc.dataAttr && selectable(anc.dataAttr.name) && anc.dataAttrCount === 1) {
         dataAnchorDone = true;
         const { name: name2, value } = anc.dataAttr;
         const anchorSelector = `[${name2}="${escCssAttrValue(value)}"]`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piwitests/reporter",
-  "version": "0.45.0",
+  "version": "0.46.0",
   "description": "Playwright reporter that streams results, traces and HTML reports to a Piwi Dashboard instance",
   "url": "https://github.com/PiwiTests/platform",
   "homepage": "https://piwitests.dev",

package/templates/skills/apply-locator-healing/SKILL.md

@@ -25,6 +25,8 @@ Prefer the **Piwi MCP server** if it is connected (`get_locator_healing`, `expla
 
 6. **Report.** Show the before/after locator, the file and line, and the verifying result. If several tests shared the selector, list every place you changed.
 
+7. **Report back to Piwi.** Commit with the trailer `Piwi-Cluster: <clusterId>` as the last line of the message (the cluster of the failing case; `get_fix_plan` returns the line in `verify.commitTrailer`), then call `report_fix_attempt` with that cluster, `kind: "locator-edit"`, the commit or the branch, and the `edit` (`filePath`, `line`, `from`: the old locator, `to`: the one you applied). Do it once per call site you changed. Piwi records the attempt verified when the test passes on that commit, and counts the healing suggestion as adopted.
+
 ## Guardrails
 
 - Change the **locator**, not the assertion's intent — if a test checked for "Sign in" and the button is now "Log in", that is a copy change to confirm with the user, not a locator to heal.

package/templates/skills/investigate-failure/SKILL.md

@@ -27,7 +27,11 @@ Prefer the **Piwi MCP server** if it is connected to this agent (tools named `li
 
 7. **Verify.** Re-run the affected spec(s): `npx playwright test <file>`. Confirm they pass and the new run is green in the dashboard (`get_run_insights` compares against the last green run: regressions cleared, nothing new broken).
 
-8. **Close the loop (optional).** With reporter or admin access, `set_cluster_status` marks the cluster resolved with a note so it drops off the triage queue.
+8. **Report back.** Piwi learns from what you tell it, so end every investigation with these calls (they need reporter or admin access; each is logged with your API key):
+   - **Your diagnosis.** If the cluster had no diagnosis, or yours differs, record it with `record_diagnosis`: the model you run on and the diagnosis in the schema the tool describes (summary, confidenceScore, severity, ranked hypotheses with their evidence, suggestedFix with the unified-diff `patch`). Piwi validates the patch against the source that failed and shows the diagnosis as written by an agent.
+   - **Your rating of Piwi's diagnosis.** If you read one with `get_cluster_diagnosis`, rate it with `submit_diagnosis_feedback`: `up` when it pointed at the real cause, `down` with a one-line note on what it got wrong when it did not. A `down` keeps the next diagnosis from repeating it.
+   - **Your fix.** Commit the change with the trailer `get_fix_plan` returns in `verify.commitTrailer` (`Piwi-Cluster: <clusterId>`) as the last line of the commit message, then call `report_fix_attempt` with the cluster, the kind (`patch`, `locator-edit` or `fix-plan`), the commit or the branch, the patch you applied and the `diagnosisId` you followed. When the tests pass on that commit, Piwi records the attempt verified and shows it on the cluster's activity.
+   - Leave the cluster's status alone: the run that passes on your commit records the fix.
 
 ## Guardrails
 

package/templates/skills/write-the-missing-test/SKILL.md

@@ -14,7 +14,7 @@ drafts it from the graph, and opens it in the same change.
 ## How you reach Piwi
 
 Prefer the **Piwi MCP server** if it is connected (`list_scenario_gaps`,
-`draft_scenario`, `get_change_coverage`). Otherwise use the dashboard's **Gaps**
+`draft_scenario`, `get_change_coverage`, `triage_gap`). Otherwise use the dashboard's **Gaps**
 view, or the reporter CLI with `PIWI_DASHBOARD_URL` / `PIWI_API_KEY` /
 `PIWI_PROJECT_NAME` set.
 
@@ -55,11 +55,18 @@ view, or the reporter CLI with `PIWI_DASHBOARD_URL` / `PIWI_API_KEY` /
    test asserts the missing behavior. If the gap had no reachable path, say so —
    the draft cannot invent an entry point, and the gap may need a fixture.
 
+7. **Report back to Piwi.** Tell Piwi what you decided about the gap with
+   `triage_gap` (reporter or admin access): `verb: "accept"` for the gap you
+   wrote the test for, `covered-by` with the covering test's id when a test you
+   found already covers it, or `dismiss` with the reason (`not-worth-testing`,
+   `covered-elsewhere`, `wrong`) when the evidence did not hold. Each verdict counts toward the precision of the
+   detector that raised the gap, so a detector that keeps being wrong is muted.
+
 ## Guardrails
 
 - A gap is a suggestion with evidence, never a verdict. If the evidence does not
   hold — the route is headless by design, the control is decorative — dismiss it
-  in the dashboard with a reason rather than writing a test that asserts nothing.
+  with `triage_gap` and a reason rather than writing a test that asserts nothing.
 - Do not weaken an assertion to make the draft pass. A test that passes without
   asserting the behavior is the false-comfort gap you were sent to close.
 - The draft's assertion is a `TODO` on purpose: fill it from the source and the