@reqvire-org/ads 0.3.15 → 0.3.17

package/dist/showcase/resource-reader.js

@@ -0,0 +1,37 @@
+const retryDelays = [200, 800];
+const networkFailure = error => error?.name === "TypeError" && /^(Failed to fetch|fetch failed|Load failed|NetworkError when attempting to fetch resource\.)$/.test(error.message);
+
+function pause(milliseconds, signal) {
+  return new Promise((resolve, reject) => {
+    signal?.throwIfAborted();
+    const finish = () => { signal?.removeEventListener("abort", abort); resolve(); };
+    const timer = setTimeout(finish, milliseconds);
+    const abort = () => { clearTimeout(timer); signal.removeEventListener("abort", abort); reject(signal.reason); };
+    signal?.addEventListener("abort", abort, { once: true });
+  });
+}
+
+/** Only resources/read is repeatable here; never wrap tool calls or assertions. */
+export function resourceReader(read, { signal, onDiagnostic, wait = pause } = {}) {
+  return async input => {
+    for (let attempt = 1; ; attempt++) {
+      signal?.throwIfAborted();
+      try {
+        const response = await read(input);
+        signal?.throwIfAborted();
+        if (attempt > 1) onDiagnostic?.({ state: "recovered", uri: input.uri, attempt });
+        return response;
+      } catch (error) {
+        signal?.throwIfAborted();
+        if (!networkFailure(error)) throw error;
+        if (attempt > retryDelays.length) {
+          onDiagnostic?.({ state: "exhausted", uri: input.uri, attempt, message: error.message });
+          throw Object.assign(new Error(`MCP resource transport failed for ${input.uri} after ${attempt} attempts: ${error.message}. Inspect the host connection and browser network diagnostics; this resource-loading error does not establish a component assertion failure.`, { cause: error }), { code: "ADS_RESOURCE_TRANSPORT" });
+        }
+        const delayMs = retryDelays[attempt - 1];
+        onDiagnostic?.({ state: "retry", uri: input.uri, attempt, nextAttempt: attempt + 1, delayMs, message: error.message });
+        await wait(delayMs, signal);
+      }
+    }
+  };
+}

package/dist/skills/ads-break-ui/SKILL.md

@@ -52,6 +52,9 @@ For owner drafts, token-sample reconciliation, coupled transactions and local
 constant namespaces, read [guarded-editing.md](references/guarded-editing.md).
 For on-demand current/candidate screenshots and visual dry-run review, read
 [captures.md](references/captures.md).
+For a rejected patch, failed check or loading error, read
+[evidence and diagnosis](references/evidence.md); inspect the failing boundary
+and `ads_investigate` bundle before changing APIs or verification policy.
 
 
 For parent/child `covers`, conditional-control review, reference comparisons,

package/dist/skills/ads-break-ui/references/evidence.md

@@ -0,0 +1,73 @@
+# Investigate the failing boundary
+
+Use this reference after a rejected patch, failed check or preview loading error.
+MCP serves it as `ads://guides/evidence`. Inspect the compact result first; fetch
+only the failing check's bundle or relevant artifact, rather than repeating a suite.
+
+## Read the result correctly
+
+`failure.category` identifies a boundary, not an inferred root cause:
+
+| Category | Established observation | Next inspection |
+|----------|-------------------------|-----------------|
+| `architecture` | A source/ownership/configuration gate rejected the candidate. | Exact rule, source location and `certainty`. An inconclusive ownership proof does not establish that a valid API is wrong. |
+| `build` | A registered project pipeline step or compiled-resource integrity check failed. | Named command/phase, exit code, bounded output and build revision. A custom project script may contain several kinds of checks. |
+| `transport` | An MCP/browser resource delivery boundary failed. | Resource URI, relevant failed startup requests and observed browser errors. Do not infer a network-interface or component cause without evidence. |
+| `runner` | The harness, process, readiness or reporting boundary failed, or a test threw without assertion evidence. | Active/pending checks, timeout, failing step and artifacts. `certainty: "unclassified"` means ADS cannot establish the cause. |
+| `assertion` | A reported assertion step or token binding check failed. | Expected behavior, source location, state and trace. This can still be a test defect; compare the intended contract before editing the component. |
+
+A complete failed run can contain independent passing cases. Suite interruption,
+missing/skipped cases, stale inputs and an unexplained process exit cannot certify
+a pass. Keep the reported case outcome separate from whole-run acceptance.
+
+## Get a compact investigation
+
+Discover exact owner/check IDs with `ads_behaviors`, then:
+
+```json
+{ "unit": "components/Example", "check": "keyboard-navigation" }
+```
+
+Send this to `ads_investigate`. It reads the latest bundle without running code.
+`ads://project/investigations` lists available entries; the returned `resourceUri`
+reads the same bundle. It records:
+
+- Project versus isolated candidate, configured framework/profile and scenario.
+- Exact input revision and the preview revision actually observed by the helper.
+- Failing step/source, observed startup viewport and relevant failed requests.
+- Available registered trace, screenshot or context artifact resource URIs.
+- Explicit `acceptance.established` and `acceptance.unverified` scope.
+
+Absent observations are `null` or empty; ADS does not invent a viewport, trace or
+source line. Viewport evidence is labeled `preview-startup`; a test that resizes
+later must collect its own failure-state evidence. Failed-request collection
+covers managed startup, not a complete network trace. Bodies and headers are not
+collected. Project-configured Playwright trace/screenshot policy controls which
+artifacts exist; ADS does not turn on expensive recording or rerun a failed case.
+Protocol runners may provide structured failure/step/location/artifact fields;
+older reports remain valid and their unclassified errors stay explicit.
+
+Only the latest bundle per registered check is exposed, including dry runs.
+Another verification replaces it and removes old artifacts from resource access;
+old runner output directories follow project cleanup policy. Artifact resources
+are restricted to registered ordinary files under that run's output directory,
+bounded to 20 MiB each and checked against their recorded digest on read.
+Metadata is bounded to 2 MiB. Removed registrations are pruned on verification.
+
+Candidate evidence never becomes passing live-source evidence. Compare the
+recorded input revision with current `ads_behaviors` evidence; a bundle describes
+its run, and does not claim current source merely because it remains available.
+For a build/architecture rejection before behavior runs, inspect the mutation
+result's `investigation` (also retained in `ads_status.mutations.lastResult`).
+
+## Preserve the design while repairing the failure
+
+Fix the owner of the demonstrated defect. Do not privatize a valid API, introduce
+demo-only props, substitute a styled link, change the reference baseline or weaken
+verification policy to pass a tooling limitation. Preserve the draft and report
+the smallest source/browser reproduction when ownership remains unprovable.
+
+`acceptance` states what that result established. Core checks establish source
+guard acceptance; registered tests establish only their actual cases/profiles.
+Neither establishes untested states, visual parity, an accessibility audit or
+another MCP host's compatibility. Captures show an appearance, not a transition.

package/dist/skills/ads-break-ui/references/guarded-editing.md

@@ -51,6 +51,18 @@ blanket sleeps. Fake clocks suit timer-only guarantees; keep real time for actua
 gesture/motion/layout guarantees. Project settings belong in guarded configuration
 changes; ADS does not silently raise budgets or override the worker count.
 
+If a check cannot load its MCP preview, preserve the draft and inspect the exact
+resource URI and failed browser requests before changing component code. The ADS
+showcase retries a fetch transport failure on `resources/read` at most twice
+(200/800 ms backoff); recovered startup reads remain visible in
+`startupDiagnostics`. It never retries tool calls, assertions or complete checks,
+and persistent failures still block application. HTTP/protocol/content errors,
+integrity failures and cancellation do not retry. External hosts own their
+transport behavior. Chrome's `ERR_NETWORK_CHANGED` does not prove an ADS restart
+or identify Docker/VPN churn: correlate failure timestamps with live interface
+events, Chrome network logs and server availability. Do not weaken checks or
+rewrite a valid API to hide infrastructure failures.
+
 Named barrel imports can narrow affected checks when the project accurately
 declares package `sideEffects`; retain CSS/global effects in that policy. Missing
 or unsupported policies and dynamic/wildcard dependencies stay conservative.

package/dist/skills/ads-break-ui/references/scenarios.md

@@ -101,6 +101,38 @@ do not export the helper solely for a test. Public/private ownership is a produc
 decision, not a coverage workaround. Browser checks verify transitions but do not
 replace the current static `covers` requirement; `exercises` does not waive it.
 
+## Native semantics through runtime-owned selectors
+
+An anchor or other native semantic element can also occupy a position styled by
+public runtime UI, without cloning or an `asChild` API:
+
+```tsx
+// Runtime owner: the class is attached to Line's actual rendered span.
+const line = css`:is(a, button) > & { color: var(--text-body); }`;
+export function Line(props) { return <span className={line} {...props} />; }
+
+// Scenario: semantics belong to the consumer, appearance to the runtime owner.
+<a href={fixture.destination}><Line>{fixture.label}</Line></a>
+```
+
+ADS traces the actual returned DOM, the attached Linaria template and matching
+selector relationships. A public parent's `& > a` is evidence too. A tag-agnostic
+parent selector such as `& > :has(> [data-part="line"])` must match a marker
+declared by the actual runtime-owned child; a scenario-authored lookalike does not
+qualify. No component names or marker spellings are reserved.
+
+Unused styles, unrelated CSS, broad `& > *` selectors, negative selectors alone,
+fabricated markers, unknown render alternatives and opaque class replacement
+cannot grant permission. A selector cannot establish a scenario-built custom
+widget's keyboard behavior. Inline styles and arbitrary classes remain rejected;
+existing source-verified public class helpers keep their own contract.
+
+Do not add a public link part or change the DOM to satisfy a cloning-only model.
+Preserve semantic attributes and the intended public API. Unsupported source
+grammar produces an inconclusive ownership diagnostic, not proof of a bad API.
+Browser verification must establish the real focus treatment, hover/state
+precedence, navigation and other promised behavior in the compiled App iframe.
+
 ## Native semantics through a public runtime slot
 
 A native element can be the direct child of a public runtime component that

package/dist/skills/ads-designer/SKILL.md

@@ -84,6 +84,9 @@ For owner drafts, token-sample reconciliation, coupled transactions and local
 constant namespaces, read [guarded-editing.md](references/guarded-editing.md).
 For on-demand current/candidate screenshots and visual dry-run review, read
 [captures.md](references/captures.md).
+For a rejected patch, failed check or loading error, read
+[evidence and diagnosis](references/evidence.md); inspect the failing boundary
+and `ads_investigate` bundle before changing APIs or verification policy.
 
 For parent/child `covers`, conditional-control review, reference comparisons,
 public style-helper use, fragment-link navigation, or `scenario-render` /

package/dist/skills/ads-designer/references/evidence.md

@@ -0,0 +1,73 @@
+# Investigate the failing boundary
+
+Use this reference after a rejected patch, failed check or preview loading error.
+MCP serves it as `ads://guides/evidence`. Inspect the compact result first; fetch
+only the failing check's bundle or relevant artifact, rather than repeating a suite.
+
+## Read the result correctly
+
+`failure.category` identifies a boundary, not an inferred root cause:
+
+| Category | Established observation | Next inspection |
+|----------|-------------------------|-----------------|
+| `architecture` | A source/ownership/configuration gate rejected the candidate. | Exact rule, source location and `certainty`. An inconclusive ownership proof does not establish that a valid API is wrong. |
+| `build` | A registered project pipeline step or compiled-resource integrity check failed. | Named command/phase, exit code, bounded output and build revision. A custom project script may contain several kinds of checks. |
+| `transport` | An MCP/browser resource delivery boundary failed. | Resource URI, relevant failed startup requests and observed browser errors. Do not infer a network-interface or component cause without evidence. |
+| `runner` | The harness, process, readiness or reporting boundary failed, or a test threw without assertion evidence. | Active/pending checks, timeout, failing step and artifacts. `certainty: "unclassified"` means ADS cannot establish the cause. |
+| `assertion` | A reported assertion step or token binding check failed. | Expected behavior, source location, state and trace. This can still be a test defect; compare the intended contract before editing the component. |
+
+A complete failed run can contain independent passing cases. Suite interruption,
+missing/skipped cases, stale inputs and an unexplained process exit cannot certify
+a pass. Keep the reported case outcome separate from whole-run acceptance.
+
+## Get a compact investigation
+
+Discover exact owner/check IDs with `ads_behaviors`, then:
+
+```json
+{ "unit": "components/Example", "check": "keyboard-navigation" }
+```
+
+Send this to `ads_investigate`. It reads the latest bundle without running code.
+`ads://project/investigations` lists available entries; the returned `resourceUri`
+reads the same bundle. It records:
+
+- Project versus isolated candidate, configured framework/profile and scenario.
+- Exact input revision and the preview revision actually observed by the helper.
+- Failing step/source, observed startup viewport and relevant failed requests.
+- Available registered trace, screenshot or context artifact resource URIs.
+- Explicit `acceptance.established` and `acceptance.unverified` scope.
+
+Absent observations are `null` or empty; ADS does not invent a viewport, trace or
+source line. Viewport evidence is labeled `preview-startup`; a test that resizes
+later must collect its own failure-state evidence. Failed-request collection
+covers managed startup, not a complete network trace. Bodies and headers are not
+collected. Project-configured Playwright trace/screenshot policy controls which
+artifacts exist; ADS does not turn on expensive recording or rerun a failed case.
+Protocol runners may provide structured failure/step/location/artifact fields;
+older reports remain valid and their unclassified errors stay explicit.
+
+Only the latest bundle per registered check is exposed, including dry runs.
+Another verification replaces it and removes old artifacts from resource access;
+old runner output directories follow project cleanup policy. Artifact resources
+are restricted to registered ordinary files under that run's output directory,
+bounded to 20 MiB each and checked against their recorded digest on read.
+Metadata is bounded to 2 MiB. Removed registrations are pruned on verification.
+
+Candidate evidence never becomes passing live-source evidence. Compare the
+recorded input revision with current `ads_behaviors` evidence; a bundle describes
+its run, and does not claim current source merely because it remains available.
+For a build/architecture rejection before behavior runs, inspect the mutation
+result's `investigation` (also retained in `ads_status.mutations.lastResult`).
+
+## Preserve the design while repairing the failure
+
+Fix the owner of the demonstrated defect. Do not privatize a valid API, introduce
+demo-only props, substitute a styled link, change the reference baseline or weaken
+verification policy to pass a tooling limitation. Preserve the draft and report
+the smallest source/browser reproduction when ownership remains unprovable.
+
+`acceptance` states what that result established. Core checks establish source
+guard acceptance; registered tests establish only their actual cases/profiles.
+Neither establishes untested states, visual parity, an accessibility audit or
+another MCP host's compatibility. Captures show an appearance, not a transition.

package/dist/skills/ads-designer/references/guarded-editing.md

@@ -51,6 +51,18 @@ blanket sleeps. Fake clocks suit timer-only guarantees; keep real time for actua
 gesture/motion/layout guarantees. Project settings belong in guarded configuration
 changes; ADS does not silently raise budgets or override the worker count.
 
+If a check cannot load its MCP preview, preserve the draft and inspect the exact
+resource URI and failed browser requests before changing component code. The ADS
+showcase retries a fetch transport failure on `resources/read` at most twice
+(200/800 ms backoff); recovered startup reads remain visible in
+`startupDiagnostics`. It never retries tool calls, assertions or complete checks,
+and persistent failures still block application. HTTP/protocol/content errors,
+integrity failures and cancellation do not retry. External hosts own their
+transport behavior. Chrome's `ERR_NETWORK_CHANGED` does not prove an ADS restart
+or identify Docker/VPN churn: correlate failure timestamps with live interface
+events, Chrome network logs and server availability. Do not weaken checks or
+rewrite a valid API to hide infrastructure failures.
+
 Named barrel imports can narrow affected checks when the project accurately
 declares package `sideEffects`; retain CSS/global effects in that policy. Missing
 or unsupported policies and dynamic/wildcard dependencies stay conservative.

package/dist/skills/ads-designer/references/scenarios.md

@@ -101,6 +101,38 @@ do not export the helper solely for a test. Public/private ownership is a produc
 decision, not a coverage workaround. Browser checks verify transitions but do not
 replace the current static `covers` requirement; `exercises` does not waive it.
 
+## Native semantics through runtime-owned selectors
+
+An anchor or other native semantic element can also occupy a position styled by
+public runtime UI, without cloning or an `asChild` API:
+
+```tsx
+// Runtime owner: the class is attached to Line's actual rendered span.
+const line = css`:is(a, button) > & { color: var(--text-body); }`;
+export function Line(props) { return <span className={line} {...props} />; }
+
+// Scenario: semantics belong to the consumer, appearance to the runtime owner.
+<a href={fixture.destination}><Line>{fixture.label}</Line></a>
+```
+
+ADS traces the actual returned DOM, the attached Linaria template and matching
+selector relationships. A public parent's `& > a` is evidence too. A tag-agnostic
+parent selector such as `& > :has(> [data-part="line"])` must match a marker
+declared by the actual runtime-owned child; a scenario-authored lookalike does not
+qualify. No component names or marker spellings are reserved.
+
+Unused styles, unrelated CSS, broad `& > *` selectors, negative selectors alone,
+fabricated markers, unknown render alternatives and opaque class replacement
+cannot grant permission. A selector cannot establish a scenario-built custom
+widget's keyboard behavior. Inline styles and arbitrary classes remain rejected;
+existing source-verified public class helpers keep their own contract.
+
+Do not add a public link part or change the DOM to satisfy a cloning-only model.
+Preserve semantic attributes and the intended public API. Unsupported source
+grammar produces an inconclusive ownership diagnostic, not proof of a bad API.
+Browser verification must establish the real focus treatment, hover/state
+precedence, navigation and other promised behavior in the compiled App iframe.
+
 ## Native semantics through a public runtime slot
 
 A native element can be the direct child of a public runtime component that

package/dist/skills/ads-import/SKILL.md

@@ -48,6 +48,9 @@ For owner drafts, token-sample reconciliation, coupled transactions and local
 constant namespaces, read [guarded-editing.md](references/guarded-editing.md).
 For on-demand current/candidate screenshots and visual dry-run review, read
 [captures.md](references/captures.md).
+For a rejected patch, failed check or loading error, read
+[evidence and diagnosis](references/evidence.md); inspect the failing boundary
+and `ads_investigate` bundle before changing APIs or verification policy.
 
 For parent/child `covers`, conditional-control review, reference comparisons,
 public style-helper use, fragment-link navigation, or `scenario-render` /

package/dist/skills/ads-import/references/evidence.md

@@ -0,0 +1,73 @@
+# Investigate the failing boundary
+
+Use this reference after a rejected patch, failed check or preview loading error.
+MCP serves it as `ads://guides/evidence`. Inspect the compact result first; fetch
+only the failing check's bundle or relevant artifact, rather than repeating a suite.
+
+## Read the result correctly
+
+`failure.category` identifies a boundary, not an inferred root cause:
+
+| Category | Established observation | Next inspection |
+|----------|-------------------------|-----------------|
+| `architecture` | A source/ownership/configuration gate rejected the candidate. | Exact rule, source location and `certainty`. An inconclusive ownership proof does not establish that a valid API is wrong. |
+| `build` | A registered project pipeline step or compiled-resource integrity check failed. | Named command/phase, exit code, bounded output and build revision. A custom project script may contain several kinds of checks. |
+| `transport` | An MCP/browser resource delivery boundary failed. | Resource URI, relevant failed startup requests and observed browser errors. Do not infer a network-interface or component cause without evidence. |
+| `runner` | The harness, process, readiness or reporting boundary failed, or a test threw without assertion evidence. | Active/pending checks, timeout, failing step and artifacts. `certainty: "unclassified"` means ADS cannot establish the cause. |
+| `assertion` | A reported assertion step or token binding check failed. | Expected behavior, source location, state and trace. This can still be a test defect; compare the intended contract before editing the component. |
+
+A complete failed run can contain independent passing cases. Suite interruption,
+missing/skipped cases, stale inputs and an unexplained process exit cannot certify
+a pass. Keep the reported case outcome separate from whole-run acceptance.
+
+## Get a compact investigation
+
+Discover exact owner/check IDs with `ads_behaviors`, then:
+
+```json
+{ "unit": "components/Example", "check": "keyboard-navigation" }
+```
+
+Send this to `ads_investigate`. It reads the latest bundle without running code.
+`ads://project/investigations` lists available entries; the returned `resourceUri`
+reads the same bundle. It records:
+
+- Project versus isolated candidate, configured framework/profile and scenario.
+- Exact input revision and the preview revision actually observed by the helper.
+- Failing step/source, observed startup viewport and relevant failed requests.
+- Available registered trace, screenshot or context artifact resource URIs.
+- Explicit `acceptance.established` and `acceptance.unverified` scope.
+
+Absent observations are `null` or empty; ADS does not invent a viewport, trace or
+source line. Viewport evidence is labeled `preview-startup`; a test that resizes
+later must collect its own failure-state evidence. Failed-request collection
+covers managed startup, not a complete network trace. Bodies and headers are not
+collected. Project-configured Playwright trace/screenshot policy controls which
+artifacts exist; ADS does not turn on expensive recording or rerun a failed case.
+Protocol runners may provide structured failure/step/location/artifact fields;
+older reports remain valid and their unclassified errors stay explicit.
+
+Only the latest bundle per registered check is exposed, including dry runs.
+Another verification replaces it and removes old artifacts from resource access;
+old runner output directories follow project cleanup policy. Artifact resources
+are restricted to registered ordinary files under that run's output directory,
+bounded to 20 MiB each and checked against their recorded digest on read.
+Metadata is bounded to 2 MiB. Removed registrations are pruned on verification.
+
+Candidate evidence never becomes passing live-source evidence. Compare the
+recorded input revision with current `ads_behaviors` evidence; a bundle describes
+its run, and does not claim current source merely because it remains available.
+For a build/architecture rejection before behavior runs, inspect the mutation
+result's `investigation` (also retained in `ads_status.mutations.lastResult`).
+
+## Preserve the design while repairing the failure
+
+Fix the owner of the demonstrated defect. Do not privatize a valid API, introduce
+demo-only props, substitute a styled link, change the reference baseline or weaken
+verification policy to pass a tooling limitation. Preserve the draft and report
+the smallest source/browser reproduction when ownership remains unprovable.
+
+`acceptance` states what that result established. Core checks establish source
+guard acceptance; registered tests establish only their actual cases/profiles.
+Neither establishes untested states, visual parity, an accessibility audit or
+another MCP host's compatibility. Captures show an appearance, not a transition.

package/dist/skills/ads-import/references/guarded-editing.md

@@ -51,6 +51,18 @@ blanket sleeps. Fake clocks suit timer-only guarantees; keep real time for actua
 gesture/motion/layout guarantees. Project settings belong in guarded configuration
 changes; ADS does not silently raise budgets or override the worker count.
 
+If a check cannot load its MCP preview, preserve the draft and inspect the exact
+resource URI and failed browser requests before changing component code. The ADS
+showcase retries a fetch transport failure on `resources/read` at most twice
+(200/800 ms backoff); recovered startup reads remain visible in
+`startupDiagnostics`. It never retries tool calls, assertions or complete checks,
+and persistent failures still block application. HTTP/protocol/content errors,
+integrity failures and cancellation do not retry. External hosts own their
+transport behavior. Chrome's `ERR_NETWORK_CHANGED` does not prove an ADS restart
+or identify Docker/VPN churn: correlate failure timestamps with live interface
+events, Chrome network logs and server availability. Do not weaken checks or
+rewrite a valid API to hide infrastructure failures.
+
 Named barrel imports can narrow affected checks when the project accurately
 declares package `sideEffects`; retain CSS/global effects in that policy. Missing
 or unsupported policies and dynamic/wildcard dependencies stay conservative.

package/dist/skills/ads-import/references/scenarios.md

@@ -101,6 +101,38 @@ do not export the helper solely for a test. Public/private ownership is a produc
 decision, not a coverage workaround. Browser checks verify transitions but do not
 replace the current static `covers` requirement; `exercises` does not waive it.
 
+## Native semantics through runtime-owned selectors
+
+An anchor or other native semantic element can also occupy a position styled by
+public runtime UI, without cloning or an `asChild` API:
+
+```tsx
+// Runtime owner: the class is attached to Line's actual rendered span.
+const line = css`:is(a, button) > & { color: var(--text-body); }`;
+export function Line(props) { return <span className={line} {...props} />; }
+
+// Scenario: semantics belong to the consumer, appearance to the runtime owner.
+<a href={fixture.destination}><Line>{fixture.label}</Line></a>
+```
+
+ADS traces the actual returned DOM, the attached Linaria template and matching
+selector relationships. A public parent's `& > a` is evidence too. A tag-agnostic
+parent selector such as `& > :has(> [data-part="line"])` must match a marker
+declared by the actual runtime-owned child; a scenario-authored lookalike does not
+qualify. No component names or marker spellings are reserved.
+
+Unused styles, unrelated CSS, broad `& > *` selectors, negative selectors alone,
+fabricated markers, unknown render alternatives and opaque class replacement
+cannot grant permission. A selector cannot establish a scenario-built custom
+widget's keyboard behavior. Inline styles and arbitrary classes remain rejected;
+existing source-verified public class helpers keep their own contract.
+
+Do not add a public link part or change the DOM to satisfy a cloning-only model.
+Preserve semantic attributes and the intended public API. Unsupported source
+grammar produces an inconclusive ownership diagnostic, not proof of a bad API.
+Browser verification must establish the real focus treatment, hover/state
+precedence, navigation and other promised behavior in the compiled App iframe.
+
 ## Native semantics through a public runtime slot
 
 A native element can be the direct child of a public runtime component that

package/dist/skills/ads-migrate/SKILL.md

@@ -49,6 +49,9 @@ For owner drafts, token-sample reconciliation, coupled transactions and local
 constant namespaces, read [guarded-editing.md](references/guarded-editing.md).
 For on-demand current/candidate screenshots and visual dry-run review, read
 [captures.md](references/captures.md).
+For a rejected patch, failed check or loading error, read
+[evidence and diagnosis](references/evidence.md); inspect the failing boundary
+and `ads_investigate` bundle before changing APIs or verification policy.
 
 
 For parent/child `covers`, conditional-control review, reference comparisons,

package/dist/skills/ads-migrate/references/evidence.md

@@ -0,0 +1,73 @@
+# Investigate the failing boundary
+
+Use this reference after a rejected patch, failed check or preview loading error.
+MCP serves it as `ads://guides/evidence`. Inspect the compact result first; fetch
+only the failing check's bundle or relevant artifact, rather than repeating a suite.
+
+## Read the result correctly
+
+`failure.category` identifies a boundary, not an inferred root cause:
+
+| Category | Established observation | Next inspection |
+|----------|-------------------------|-----------------|
+| `architecture` | A source/ownership/configuration gate rejected the candidate. | Exact rule, source location and `certainty`. An inconclusive ownership proof does not establish that a valid API is wrong. |
+| `build` | A registered project pipeline step or compiled-resource integrity check failed. | Named command/phase, exit code, bounded output and build revision. A custom project script may contain several kinds of checks. |
+| `transport` | An MCP/browser resource delivery boundary failed. | Resource URI, relevant failed startup requests and observed browser errors. Do not infer a network-interface or component cause without evidence. |
+| `runner` | The harness, process, readiness or reporting boundary failed, or a test threw without assertion evidence. | Active/pending checks, timeout, failing step and artifacts. `certainty: "unclassified"` means ADS cannot establish the cause. |
+| `assertion` | A reported assertion step or token binding check failed. | Expected behavior, source location, state and trace. This can still be a test defect; compare the intended contract before editing the component. |
+
+A complete failed run can contain independent passing cases. Suite interruption,
+missing/skipped cases, stale inputs and an unexplained process exit cannot certify
+a pass. Keep the reported case outcome separate from whole-run acceptance.
+
+## Get a compact investigation
+
+Discover exact owner/check IDs with `ads_behaviors`, then:
+
+```json
+{ "unit": "components/Example", "check": "keyboard-navigation" }
+```
+
+Send this to `ads_investigate`. It reads the latest bundle without running code.
+`ads://project/investigations` lists available entries; the returned `resourceUri`
+reads the same bundle. It records:
+
+- Project versus isolated candidate, configured framework/profile and scenario.
+- Exact input revision and the preview revision actually observed by the helper.
+- Failing step/source, observed startup viewport and relevant failed requests.
+- Available registered trace, screenshot or context artifact resource URIs.
+- Explicit `acceptance.established` and `acceptance.unverified` scope.
+
+Absent observations are `null` or empty; ADS does not invent a viewport, trace or
+source line. Viewport evidence is labeled `preview-startup`; a test that resizes
+later must collect its own failure-state evidence. Failed-request collection
+covers managed startup, not a complete network trace. Bodies and headers are not
+collected. Project-configured Playwright trace/screenshot policy controls which
+artifacts exist; ADS does not turn on expensive recording or rerun a failed case.
+Protocol runners may provide structured failure/step/location/artifact fields;
+older reports remain valid and their unclassified errors stay explicit.
+
+Only the latest bundle per registered check is exposed, including dry runs.
+Another verification replaces it and removes old artifacts from resource access;
+old runner output directories follow project cleanup policy. Artifact resources
+are restricted to registered ordinary files under that run's output directory,
+bounded to 20 MiB each and checked against their recorded digest on read.
+Metadata is bounded to 2 MiB. Removed registrations are pruned on verification.
+
+Candidate evidence never becomes passing live-source evidence. Compare the
+recorded input revision with current `ads_behaviors` evidence; a bundle describes
+its run, and does not claim current source merely because it remains available.
+For a build/architecture rejection before behavior runs, inspect the mutation
+result's `investigation` (also retained in `ads_status.mutations.lastResult`).
+
+## Preserve the design while repairing the failure
+
+Fix the owner of the demonstrated defect. Do not privatize a valid API, introduce
+demo-only props, substitute a styled link, change the reference baseline or weaken
+verification policy to pass a tooling limitation. Preserve the draft and report
+the smallest source/browser reproduction when ownership remains unprovable.
+
+`acceptance` states what that result established. Core checks establish source
+guard acceptance; registered tests establish only their actual cases/profiles.
+Neither establishes untested states, visual parity, an accessibility audit or
+another MCP host's compatibility. Captures show an appearance, not a transition.

package/dist/skills/ads-migrate/references/guarded-editing.md

@@ -51,6 +51,18 @@ blanket sleeps. Fake clocks suit timer-only guarantees; keep real time for actua
 gesture/motion/layout guarantees. Project settings belong in guarded configuration
 changes; ADS does not silently raise budgets or override the worker count.
 
+If a check cannot load its MCP preview, preserve the draft and inspect the exact
+resource URI and failed browser requests before changing component code. The ADS
+showcase retries a fetch transport failure on `resources/read` at most twice
+(200/800 ms backoff); recovered startup reads remain visible in
+`startupDiagnostics`. It never retries tool calls, assertions or complete checks,
+and persistent failures still block application. HTTP/protocol/content errors,
+integrity failures and cancellation do not retry. External hosts own their
+transport behavior. Chrome's `ERR_NETWORK_CHANGED` does not prove an ADS restart
+or identify Docker/VPN churn: correlate failure timestamps with live interface
+events, Chrome network logs and server availability. Do not weaken checks or
+rewrite a valid API to hide infrastructure failures.
+
 Named barrel imports can narrow affected checks when the project accurately
 declares package `sideEffects`; retain CSS/global effects in that policy. Missing
 or unsupported policies and dynamic/wildcard dependencies stay conservative.

package/dist/skills/ads-migrate/references/scenarios.md

@@ -101,6 +101,38 @@ do not export the helper solely for a test. Public/private ownership is a produc
 decision, not a coverage workaround. Browser checks verify transitions but do not
 replace the current static `covers` requirement; `exercises` does not waive it.
 
+## Native semantics through runtime-owned selectors
+
+An anchor or other native semantic element can also occupy a position styled by
+public runtime UI, without cloning or an `asChild` API:
+
+```tsx
+// Runtime owner: the class is attached to Line's actual rendered span.
+const line = css`:is(a, button) > & { color: var(--text-body); }`;
+export function Line(props) { return <span className={line} {...props} />; }
+
+// Scenario: semantics belong to the consumer, appearance to the runtime owner.
+<a href={fixture.destination}><Line>{fixture.label}</Line></a>
+```
+
+ADS traces the actual returned DOM, the attached Linaria template and matching
+selector relationships. A public parent's `& > a` is evidence too. A tag-agnostic
+parent selector such as `& > :has(> [data-part="line"])` must match a marker
+declared by the actual runtime-owned child; a scenario-authored lookalike does not
+qualify. No component names or marker spellings are reserved.
+
+Unused styles, unrelated CSS, broad `& > *` selectors, negative selectors alone,
+fabricated markers, unknown render alternatives and opaque class replacement
+cannot grant permission. A selector cannot establish a scenario-built custom
+widget's keyboard behavior. Inline styles and arbitrary classes remain rejected;
+existing source-verified public class helpers keep their own contract.
+
+Do not add a public link part or change the DOM to satisfy a cloning-only model.
+Preserve semantic attributes and the intended public API. Unsupported source
+grammar produces an inconclusive ownership diagnostic, not proof of a bad API.
+Browser verification must establish the real focus treatment, hover/state
+precedence, navigation and other promised behavior in the compiled App iframe.
+
 ## Native semantics through a public runtime slot
 
 A native element can be the direct child of a public runtime component that

package/dist/skills/ads-motion/SKILL.md

@@ -69,6 +69,9 @@ For owner drafts, token-sample reconciliation, coupled transactions and local
 constant namespaces, read [guarded-editing.md](references/guarded-editing.md).
 For on-demand current/candidate screenshots and visual dry-run review, read
 [captures.md](references/captures.md).
+For a rejected patch, failed check or loading error, read
+[evidence and diagnosis](references/evidence.md); inspect the failing boundary
+and `ads_investigate` bundle before changing APIs or verification policy.
 
 
 For parent/child `covers`, conditional-control review, reference comparisons,