@reqvire-org/ads 0.3.15 → 0.3.17

package/dist/skills/ads-motion/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-motion/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-motion/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/verification/browser.mjs

@@ -16,26 +16,45 @@ export async function openBehaviorScenario(page, checkId, { timeout = 30000 } =
 
 /** Shared readiness for registered verification and on-demand captures. */
 export async function openPreviewScenario(page, url, scenario, { timeout = 30000 } = {}) {
-  const failures = [];
+  const failures = [], requests = [], errors = [];
+  let boundary;
+  const record = (request, detail) => {
+    if (requests.length >= 8) return;
+    let resourceUri;
+    try { const payload=request.postDataJSON(); if(payload?.method==="resources/read"&&typeof payload.params?.uri==="string"&&payload.params.uri.startsWith("ads://"))resourceUri=payload.params.uri.slice(0,500); } catch { /* Bodies are never retained. */ }
+    requests.push({method:request.method(),url:request.url().slice(0,300),...detail,...(resourceUri?{resourceUri}:{})});
+  };
   const failed = request => {
     if (failures.length < 5) failures.push(`${request.method()} ${request.url().slice(0, 300)}: ${request.failure()?.errorText ?? "request failed"}`);
+    record(request,{error:request.failure()?.errorText??"request failed"});
   };
+  const response = response => { if(response.status()>=400)record(response.request(),{status:response.status()}); };
+  const pageError = error => { if(errors.length<3)errors.push(error.message.slice(0,500)); };
+  const diagnostic = (outcome, detail={}) => console.warn(JSON.stringify({adsPreviewDiagnostic:{kind:"preview-startup",scenario,outcome,viewport:page.viewportSize(),requests,errors,...detail}}));
   page.on("requestfailed", failed);
+  page.on("response", response);page.on("pageerror", pageError);
   try {
     await page.goto(url, { waitUntil: "load", timeout });
     const end = Date.now() + timeout;
     while (Date.now() < end) {
       for (const frame of page.frames().filter(frame => frame !== page.mainFrame())) {
-        const state = await frame.evaluate(() => ({ state: document.documentElement.dataset.adsPreviewState, id: document.documentElement.dataset.adsScenario, message: document.getElementById("ads-preview-status")?.textContent })).catch(() => ({}));
-        if (state.id === scenario && state.state === "ready") return frame;
-        if (state.id === scenario && state.state === "error") throw new Error(state.message || "The MCP App failed before verification.");
+        const state = await frame.evaluate(() => {const data=document.documentElement.dataset;return {state:data.adsPreviewState,id:data.adsScenario,revision:data.adsPreviewRevision,category:data.adsPreviewErrorCategory,code:data.adsPreviewErrorCode,resourceUri:data.adsPreviewResourceUri,message:document.getElementById("ads-preview-status")?.textContent};}).catch(() => ({}));
+        if (state.id === scenario && state.state === "ready") {
+          const retries = await page.evaluate(() => Number(document.documentElement.dataset.adsResourceRetries ?? 0)).catch(() => 0);
+          if (retries > 0) console.warn(JSON.stringify({ adsPreviewDiagnostic: { kind: "resource-read-recovery", scenario, retries, failedRequests: failures } }));
+          diagnostic("ready",{previewRevision:state.revision??null});
+          return frame;
+        }
+        if (state.id === scenario && state.state === "error") {boundary={category:state.category??"runner",phase:"preview-startup",code:state.code??"ADS_PREVIEW_STARTUP",...(state.resourceUri?{resourceUri:state.resourceUri}:{})};throw new Error(state.message || "The MCP App failed before verification.");}
       }
-      const error = await page.evaluate(() => document.querySelector('#status[data-error="true"]')?.textContent).catch(() => null);
-      if (error) throw new Error(error);
+      const error = await page.evaluate(() => {const node=document.querySelector('#status[data-error="true"]');return node?{message:node.textContent,category:node.dataset.errorCategory,code:node.dataset.errorCode}:null;}).catch(() => null);
+      if (error) {boundary={category:error.category??(requests.length?"transport":"runner"),phase:"host-startup",code:error.code??(requests.length?"ADS_BROWSER_REQUEST":"ADS_HOST_STARTUP")};throw new Error(error.message);}
       await page.waitForTimeout(50);
     }
     throw new Error("Timed out waiting for the selected MCP App scenario to become current and ready. Inspect ads_status and ads://project/build.");
   } catch (error) {
-    throw new Error(`Scenario ${scenario}: ${error.message}${failures.length ? `\nFailed browser requests:\n${failures.join("\n")}` : ""}`, { cause: error });
-  } finally { page.off("requestfailed", failed); }
+    boundary??={category:requests.length?"transport":"runner",phase:"preview-startup",code:requests.length?"ADS_BROWSER_REQUEST":"ADS_PREVIEW_NOT_READY",certainty:requests.length?"observed-boundary":"unclassified"};
+    diagnostic("failed",{failure:boundary});
+    throw Object.assign(new Error(`Scenario ${scenario}: ${error.message}${failures.length ? `\nFailed browser requests:\n${failures.join("\n")}` : ""}`, { cause: error }),{failure:boundary});
+  } finally { page.off("requestfailed", failed);page.off("response",response);page.off("pageerror",pageError); }
 }

package/dist/verification/playwright-reporter.cjs

@@ -8,6 +8,9 @@ module.exports = class AdsBehaviorReporter {
     this.cases = [];
     this.errors = [];
     this.active = new Map();
+    this.diagnostics = new Map();
+    this.diagnosticBuffers = new Map();
+    this.steps = new Map();
     this.startedAt = Date.now();
     this.totalTests = 0;
   }
@@ -20,11 +23,46 @@ module.exports = class AdsBehaviorReporter {
     this.active.set(test.id, this.entries(test).map(entry => ({ ...entry, startedAt: (result.startTime ?? new Date()).toISOString(), workerIndex: result.workerIndex, retry: result.retry })));
     this.publish();
   }
+  location(value) {
+    if (!value?.file) return undefined;
+    const file=path.relative(this.request.projectRoot,value.file).replaceAll("\\","/");
+    return {file,line:value.line,column:value.column};
+  }
+  onStepEnd(test, _result, step) {
+    if (!step.error || this.steps.has(test.id)) return;
+    this.steps.set(test.id,{title:String(step.title).slice(0,300),category:step.category,location:this.location(step.error.location??step.location),durationMs:step.duration});
+  }
   onTestEnd(test, result) {
     this.active.delete(test.id);
-    for (const entry of this.entries(test)) this.cases.push({ ...entry, status: result.status === "passed" && test.expectedStatus === "passed" ? "passed" : ["skipped", "interrupted"].includes(result.status) ? "skipped" : "failed", durationMs: result.duration, workerIndex: result.workerIndex, retry: result.retry, completedAt: new Date().toISOString(), message: result.errors?.map(error => error.message || error.stack || error.value || "The browser runner reported an error without details.").join("\n").slice(0, 1000) });
+    const diagnostics = this.diagnostics.get(test.id);
+    const step=this.steps.get(test.id),startup=diagnostics?.findLast(item=>item.kind==="preview-startup"),failed=result.status!=="passed"||test.expectedStatus!=="passed";
+    const failure=failed?(startup?.failure??{category:step?.category==="expect"?"assertion":"runner",phase:step?.category==="expect"?"test-assertion":"test-execution",code:result.status==="timedOut"?"ADS_CASE_TIMEOUT":"ADS_CASE_FAILURE",certainty:step?.category==="expect"?"observed-boundary":"unclassified"}):undefined;
+    const artifacts=(result.attachments??[]).filter(item=>item.path).slice(0,5).map(item=>({name:String(item.name).slice(0,100),mimeType:String(item.contentType).slice(0,100),path:path.relative(path.dirname(process.env.ADS_VERIFY_REPORT),item.path).replaceAll("\\","/")}));
+    for (const entry of this.entries(test)) this.cases.push({ ...entry, status: !failed ? "passed" : ["skipped", "interrupted"].includes(result.status) ? "skipped" : "failed", durationMs: result.duration, workerIndex: result.workerIndex, retry: result.retry, completedAt: new Date().toISOString(), source:step?.location??this.location(result.errors?.[0]?.location??test.location), ...(step?{failingStep:step}:{}),...(failure?{failure}:{}),...(startup?.viewport?{viewport:startup.viewport,viewportSource:"preview-startup"}:{}),...(artifacts.length?{artifacts}:{}), ...(diagnostics?.length ? { diagnostics } : {}), message: result.errors?.map(error => error.message || error.stack || error.value || "The browser runner reported an error without details.").join("\n").slice(0, 1000) });
+    this.diagnostics.delete(test.id);
+    this.diagnosticBuffers.delete(test.id);
+    this.steps.delete(test.id);
     this.publish();
   }
+  onStdErr(chunk, test) {
+    if (!test) return;
+    const lines = ((this.diagnosticBuffers.get(test.id) ?? "") + String(chunk)).split("\n");
+    this.diagnosticBuffers.set(test.id, lines.pop().slice(-8192));
+    for (const line of lines) {
+      if (line.length > 8192) continue;
+      try {
+        const diagnostic = JSON.parse(line).adsPreviewDiagnostic;
+        if (typeof diagnostic?.scenario !== "string") continue;
+        let entry;
+        if(diagnostic.kind==="resource-read-recovery"&&Number.isSafeInteger(diagnostic.retries)&&diagnostic.retries>0)entry={ kind: diagnostic.kind, scenario: diagnostic.scenario.slice(0, 300), retries: diagnostic.retries, failedRequests: (Array.isArray(diagnostic.failedRequests) ? diagnostic.failedRequests : []).slice(0, 5).map(value => String(value).slice(0, 500)) };
+        else if(diagnostic.kind==="preview-startup"&&["ready","failed"].includes(diagnostic.outcome))entry={kind:diagnostic.kind,scenario:diagnostic.scenario.slice(0,300),outcome:diagnostic.outcome,viewport:diagnostic.viewport,previewRevision:diagnostic.previewRevision,requests:diagnostic.requests,errors:diagnostic.errors,...(diagnostic.failure&&["architecture","build","transport","runner","assertion"].includes(diagnostic.failure.category)?{failure:diagnostic.failure}:{})};
+        if(!entry)continue;
+        const collected = this.diagnostics.get(test.id) ?? [];
+        if (collected.length < 5) collected.push(entry);
+        this.diagnostics.set(test.id, collected);
+      } catch { /* Ordinary test output is not an ADS startup diagnostic. */ }
+    }
+  }
   onError(error) {
     if (this.errors.length < 5) this.errors.push(String(error.message || error.stack || error.value || "The browser runner reported a suite error without details.").slice(0, 4000));
     this.publish();

package/dist/verification.mjs

@@ -12,6 +12,8 @@ import { inspectUnits, configurationFiles } from "./units.mjs";
 import { inspectBehaviors } from "./behaviors.mjs";
 import { inspectScenarios } from "./scenarios.mjs";
 import { readPreviewManifest } from "./preview-resources.mjs";
+import { acceptance, failure, failureCategories } from "./evidence.mjs";
+import { investigationArtifacts, investigationUri, saveInvestigations } from "./investigations.mjs";
 
 export const BEHAVIOR_URI = "ads://project/behaviors";
 const hash = bytes => createHash("sha256").update(bytes).digest("hex");
@@ -123,7 +125,7 @@ export function behaviorInputs(options, contract, check, context = inputContext(
   const rows = [...files].sort().map(file => [slash(path.relative(options.root, file)), context.digest(file)]);
   for (const file of ["package-lock.json", "bun.lock", "bun.lockb", "pnpm-lock.yaml", "yarn.lock", "node_modules/.package-lock.json"]) rows.push([file, existsSync(path.join(options.root, file)) ? context.digest(path.join(options.root, file)) : null]);
   rows.push(["profile", JSON.stringify(options.config.mcp.behaviorProfiles[check.profile])], ["node", process.version]);
-  for (const file of ["./verification.mjs", "./verification/browser.mjs", "./verification/playwright-reporter.cjs"]) rows.push([`tool:${file}`, hash(readFileSync(new URL(file, import.meta.url)))]);
+  for (const file of ["./verification.mjs", "./verification/browser.mjs", "./verification/playwright-reporter.cjs", "./evidence.mjs", "./investigations.mjs"]) rows.push([`tool:${file}`, hash(readFileSync(new URL(file, import.meta.url)))]);
   return { revision: hash(JSON.stringify(rows)), files: rows.map(([file]) => file) };
 }
 
@@ -136,6 +138,11 @@ function saved(root) {
   } catch { return {}; }
 }
 const identity = (unit, check) => `${unit}#${check}`;
+function verificationResult(diagnostics, results) {
+  const ok=diagnostics.length===0&&results.length>0&&results.every(result=>result.status==="passed"&&result.current);
+  return {ok,diagnostics:diagnostics.map(diagnostic=>({...diagnostic,failure:diagnostic.failure??failure("runner","verification",diagnostic.rule)})),results,
+    acceptance:acceptance("selected-behavior-checks",ok,results.filter(result=>result.status==="passed"&&result.current).map(result=>`${result.unit}#${result.check}`),["unselected-checks","unasserted-behavior","visual-parity","accessibility-audit"])};
+}
 
 export function behaviorStatus(options) {
   const inventory = inspectBehaviors(options), evidence = saved(options.root);
@@ -223,7 +230,7 @@ export function createVerificationController(root, { reportRoot = root, onProgre
     status: () => ({ running: !!active, ...(active && progress ? { progress: { ...progress, elapsedMs: Date.now() - progress.startedAt } } : {}) }),
     async close() { active?.abort(); await active?.completion; },
     async run({ unit, units, checks, persist = true } = {}, signal, notifyProgress) {
-      if (active) return { ok: false, diagnostics: [{ rule: "behavior-busy", message: "A behavior verification is already running." }], results: [] };
+      if (active) return verificationResult([{ rule: "behavior-busy", message: "A behavior verification is already running." }],[]);
       active = new AbortController();
       const controller = active;
       signal = signal ? AbortSignal.any([signal, active.signal]) : active.signal;
@@ -232,13 +239,13 @@ export function createVerificationController(root, { reportRoot = root, onProgre
       const results = [], diagnostics = [];
       try {
         const options = loadConfig(root), inventory = inspectBehaviors(options);
-        if (inventory.diagnostics.length) return { ok: false, diagnostics: inventory.diagnostics, results };
+        if (inventory.diagnostics.length) return verificationResult(inventory.diagnostics.map(diagnostic=>({...diagnostic,failure:failure("architecture","behavior-contract",diagnostic.rule)})),results);
         const selectedUnits = new Set(units ?? (unit ? [unit] : inventory.contracts.map(item => item.unit)));
         const contracts = inventory.contracts.filter(item => selectedUnits.has(item.unit));
-        if (!contracts.length || [...selectedUnits].some(id => !contracts.some(contract => contract.unit === id))) return { ok: false, diagnostics: [{ rule: "behavior-selection", message: "No behavior contract matches the complete selection. Discover exact owner/check IDs with ads_behaviors." }], results };
+        if (!contracts.length || [...selectedUnits].some(id => !contracts.some(contract => contract.unit === id))) return verificationResult([{ rule: "behavior-selection", message: "No behavior contract matches the complete selection. Discover exact owner/check IDs with ads_behaviors." }],results);
         const context = inputContext(options);
         const selection = contracts.flatMap(contract => Object.entries(contract.checks).filter(([id]) => !checks || checks.includes(id)).map(([id, check]) => ({ unit: contract.unit, id, ...check, inputRevision: behaviorInputs(options, contract, check, context).revision, contract })));
-        if (!selection.length || checks?.some(id => !selection.some(check => check.id === id))) return { ok: false, diagnostics: [{ rule: "behavior-selection", message: "Unknown check selection. Use check IDs returned by ads_behaviors." }], results };
+        if (!selection.length || checks?.some(id => !selection.some(check => check.id === id))) return verificationResult([{ rule: "behavior-selection", message: "Unknown check selection. Use check IDs returned by ads_behaviors." }],results);
         for (const profileName of new Set(selection.map(check => check.profile))) {
           const profile = options.config.mcp.behaviorProfiles[profileName];
           const group = selection.filter(check => check.profile === profileName);
@@ -295,7 +302,11 @@ export function createVerificationController(root, { reportRoot = root, onProgre
           // Unexplained exits, suite errors and interrupted reports grant no pass.
           const caseFailureExit = run?.code === 1 && !runnerError && !suiteErrors.length && !incompleteReport && reportValue?.cases.some(item => item?.status === "failed");
           const runnerFailure = run && (run.code !== 0 || suiteErrors.length || incompleteReport) ? `Registered runner ${profileName} ${run.code !== 0 ? `exited with code ${run.code ?? "unknown"}` : incompleteReport ? "left an incomplete report" : "reported a suite error"}. ${suiteErrors.join("; ") || reportValue?.cases.filter(item => item?.status === "failed").slice(0, 3).map(item => `${item.id}: ${item.message || "failed without a case diagnostic"}`).join("; ") || "Inspect the runner output and verification report."}`.slice(0, 3000) : undefined;
-          if (runnerFailure) diagnostics.push({ rule: "behavior-runner", message: runnerFailure, output: run.output?.slice(-4000), profile: profileName });
+          if (runnerFailure) {
+            const caseFailures=reportValue?.cases.filter(item=>item.status==="failed"&&failureCategories.has(item.failure?.category)).map(item=>item.failure)??[];
+            diagnostics.push({ rule: "behavior-runner", message: runnerFailure, output: run.output?.slice(-4000), profile: profileName,
+              failure:caseFailureExit&&caseFailures.length?{...caseFailures[0],phase:"case-results",relatedCategories:[...new Set(caseFailures.map(item=>item.category))]}:failure("runner","profile-execution","ADS_RUNNER_EXIT",{certainty:caseFailureExit?"unclassified":"observed-boundary"}) });
+          }
           const afterOptions = loadConfig(root), afterContext = inputContext(afterOptions);
           for (const check of group) {
             const file = slash(path.relative(root, path.resolve(root, path.dirname(check.contract.file), check.file)));
@@ -307,15 +318,27 @@ export function createVerificationController(root, { reportRoot = root, onProgre
             const current = behaviorInputs(afterOptions, check.contract, check, afterContext).revision === check.inputRevision;
             if (!current) status = "stale";
             if (signal.aborted) status = "cancelled";
-            results.push({ unit: check.unit, check: check.id, file: check.file, case: check.case, profile: profileName, status, current, revision: check.inputRevision, runId, completedAt: new Date().toISOString(),
+            const caseDetail=matches.find(item=>item.status!=="passed")??matches.at(-1);
+            const reportedFailure=caseDetail?.failure;
+            const checkFailure=status==="passed"?undefined:status==="stale"||status==="cancelled"?failure("runner","verification",`ADS_${status.toUpperCase()}`):caseDetail?.status==="failed"&&failureCategories.has(reportedFailure?.category)?reportedFailure:blockedRun?failure("runner","profile-execution",runnerError?.reason??"ADS_RUNNER_INCOMPLETE",{certainty:"observed-boundary"}):failure("runner","test-execution","ADS_CASE_UNCLASSIFIED",{certainty:"unclassified"});
+            const accepted=acceptance("registered-case",status==="passed"&&current,status==="passed"&&current?["registered-case-completed"]:[],["unasserted-behavior","visual-parity","accessibility-audit"]);
+            const investigation={unit:check.unit,check:check.id,status,runId,resourceUri:investigationUri({unit:check.unit,check:check.id}),target:root===reportRoot?"project":"candidate",framework:options.config.framework,profile:profileName,mode:profile.mode??"unit",scenario:check.scenario??null,inputRevision:check.inputRevision,inputsCurrentAtCompletion:current,
+              source:caseDetail?.source??{file},failingStep:caseDetail?.failingStep??null,viewport:caseDetail?.viewport??null,viewportSource:caseDetail?.viewportSource??null,
+              observedPreviewRevision:matches.flatMap(item=>item.diagnostics??[]).findLast(item=>item.kind==="preview-startup")?.previewRevision??null,
+              requests:matches.flatMap(item=>item.diagnostics??[]).flatMap(item=>item.requests??[]).slice(0,8),browserErrors:matches.flatMap(item=>item.diagnostics??[]).flatMap(item=>item.errors??[]).slice(0,3),
+              artifacts:investigationArtifacts(reportRoot,report,matches.flatMap(item=>item.artifacts??[])),acceptance:accepted,...(checkFailure?{failure:checkFailure}:{}),completedAt:new Date().toISOString()};
+            results.push({ unit: check.unit, check: check.id, file: check.file, case: check.case, profile: profileName, status, current, revision: check.inputRevision, runId, completedAt: investigation.completedAt,
+              ...(checkFailure?{failure:checkFailure}:{}),acceptance:accepted,investigation,
               previewRevision: profile.mode === "browser" ? host?.previewRevision() ?? readPreviewManifest(options)?.revision ?? null : null,
               ...(matches.length ? { reportedStatus, durationMs: matches.reduce((sum, item) => sum + (Number.isFinite(item.durationMs) ? Math.max(0, item.durationMs) : 0), 0) } : {}),
+              ...(matches.some(item => item.diagnostics?.length) ? { startupDiagnostics: matches.flatMap(item => Array.isArray(item.diagnostics) ? item.diagnostics.slice(0, 5) : []).slice(0, 10) } : {}),
               ...(runnerFailure ? { runnerExitCode: run.code } : {}),
               execution: progress.cases.find(item => item.unit === check.unit && item.check === check.id)?.state,
               message: [matches.filter(item => item.status !== "passed").map(item => String(item.message || `Case reported ${item.status} without a diagnostic.`).slice(0, 2000)).join("\n"), runnerError ? `${runnerError.message} This check ${matches.length ? `reported ${reportedStatus}` : `was ${progress.cases.find(item => item.unit === check.unit && item.check === check.id)?.state ?? "not reported"}`}; the complete run did not pass.` : !matches.length ? "The selected case did not execute/report. Missing and skipped cases do not pass." : runnerFailure ? `This case reported ${reportedStatus}, but the complete run did not pass. ${runnerFailure}` : ""].filter(Boolean).join("\n"), report: slash(path.relative(reportRoot, report)) });
           }
           if (signal.aborted) break;
         }
+        saveInvestigations(reportRoot,results.map(result=>result.investigation),inventory.contracts.flatMap(contract=>Object.keys(contract.checks).map(id=>identity(contract.unit,id))));
         if (persist) {
           const evidence = saved(root);
           for (const result of results) evidence[identity(result.unit, result.check)] = result;
@@ -324,8 +347,8 @@ export function createVerificationController(root, { reportRoot = root, onProgre
           if (Buffer.byteLength(content) > 2 * 1024 * 1024) throw new Error("Verification evidence exceeds 2 MiB. Remove obsolete generated evidence and retry.");
           try { writeFileSync(temporary, content); renameSync(temporary, file); } finally { rmSync(temporary, { force: true }); }
         }
-        return { ok: diagnostics.length === 0 && results.length > 0 && results.every(result => result.status === "passed" && result.current), diagnostics, results };
-      } catch (error) { return { ok: false, diagnostics: [{ rule: "behavior-verification", message: error.message }], results }; }
+        return verificationResult(diagnostics,results);
+      } catch (error) { return verificationResult([{ rule: "behavior-verification", message: error.message }],results); }
       finally { try { await host?.close(); } finally { if (active === controller) { active = undefined; progress = undefined; } finish(); } }
     },
   };

package/docs/ARCHITECTURE.md

@@ -229,6 +229,15 @@ scenarios unmounts the previous view while keeping unchanged dependencies cached
 Persistence is a host lifecycle choice; a new external widget loads the same
 resources independently. Resource sharing is scoped to an App instance.
 
+The showcase's resource bridge can recover a transient fetch failure with at most
+three read attempts and bounded backoff. This applies only to `resources/read`;
+tool calls, assertions and whole checks are never replayed. Cancellation,
+HTTP/protocol/content errors and integrity failures remain failures. Browser
+diagnostics record retries, and verification retains recovered startup reads in
+its case results. Persistent transport failures still block a mutation. External
+hosts own their transport recovery; the reusable App's integrity checks remain
+the same.
+
 Managed graph builders publish into a private session directory beside the
 configured manifest. Logical scenario IDs and resource URIs stay unchanged;
 standalone builds retain the configured output and cannot overwrite a live
@@ -313,7 +322,12 @@ styles. This preserves ownership rather than granting scenario styling freedom.
 A native element may provide semantics as the single direct child of a public
 runtime slot when source tracing proves it is cloned with that owner's props.
 This preserves polymorphic composition without allowing standalone scenario
-controls, scenario styling or name-based exceptions.
+controls, scenario styling or name-based exceptions. Selector-based composition
+can establish the same ownership through actual returned DOM and attached runtime
+Linaria: a positive native-tag relationship, or a `:has` relationship to a marker
+declared by a real runtime-owned child. Broad selectors and scenario-authored
+lookalikes grant no permission. This source proof does not establish computed
+appearance, keyboard behavior or visual parity; browser checks remain necessary.
 The skill-local [scenario guide](../skills/ads-designer/references/scenarios.md)
 explains evidence, limits and diagnostics.
 
@@ -418,8 +432,20 @@ ADS owns affected-check selection, candidate hosting, progress, evidence freshne
 and process cleanup. One profile timeout bounds its entire runner process. Parallel
 workers can share that candidate host with independent App state. Partial outcomes
 remain diagnostic when execution is interrupted; they cannot approve a mutation.
-Passing checks describe their registered assertions, not every natural-language claim. This keeps edits
-focused without requiring entire file bodies in model context. Peer units and
+Passing checks describe their registered assertions, not every natural-language claim.
+Results distinguish architecture, project-build, transport, runner and assertion
+boundaries with structured phase/code evidence; an unclassified test exception
+does not become an assertion or a component defect. Acceptance explicitly lists
+established and unverified scope. Verification retains one latest investigation
+per registered check, including isolated candidates: exact input revision,
+observed preview revision, failing step/source, observed startup viewport,
+failed requests and available project-recorded artifacts. MCP exposes bounded
+bundle/index resources and only registered, digest-checked artifact files.
+Another run replaces that check's resource access; candidate evidence never
+certifies live source. Detailed usage lives in the portable skill-local
+[evidence guide](../skills/ads-designer/references/evidence.md).
+
+Edits stay focused without requiring entire file bodies in model context. Peer units and
 unrelated owners remain outside the selected unit's edit boundary. Shared foundation,
 branding and guides have their own units. Shared credits and text license notices
 belong to the documentation unit, including conventional root notices and shared

package/docs/BEHAVIORS.md

@@ -169,8 +169,23 @@ pass, even if all reported cases claim success. Results retain `reportedStatus`
 and `runnerExitCode` and explain the overall failure. Suite-level browser errors and
 bounded runner output appear in diagnostics. `openBehaviorScenario` includes the
 scenario ID and failed browser requests in startup failures; App resource errors
-identify the resource URI. Failed assertions and startup errors are not retried
-automatically. Fix or investigate the failure before explicitly verifying again.
+identify the resource URI. The ADS showcase retries only `resources/read` fetch
+transport failures, with at most three attempts and 200/800 ms backoff. Recovered
+startup reads appear in `startupDiagnostics` with retry counts and failed browser
+requests; each retry is also logged in the browser console. This does not retry a
+tool call, assertion, check or complete startup. HTTP/protocol/content errors,
+integrity failures and cancellations do not retry. Persistent loading failures
+still fail the check and block mutations. External hosts control their own
+transport recovery.
+
+`net::ERR_NETWORK_CHANGED` reports Chrome's network-change error, not proof that
+the MCP endpoint restarted or that a particular interface changed. To investigate
+an intermittent failure, correlate the saved case timestamps with Chrome's
+network log, server availability and live interface monitoring (for example,
+`ip -ts monitor link address route` on Linux). Interfaces being present, or stable
+after a failure, does not establish the cause. Preserve the draft and original
+diagnostic; do not change a component API, reference example or verification
+policy to compensate for a resource-loading failure.
 
 The reporter atomically publishes partial snapshots at test start/end. While a
 run is active, `ads_status.behaviors.progress` exposes the profile, runner budget,
@@ -257,6 +272,13 @@ publish `complete:true` at completion. Older final reports without `complete`
 remain supported after normal process completion. An explicitly incomplete report
 cannot pass even with exit code zero. Partial reports retain the same schema/run
 identity and size limits as final reports.
+Cases may optionally include `failure: {category,phase,code,certainty?}`,
+`source: {file,line,column}`, `failingStep`, `viewport`/`viewportSource`, and
+`artifacts: [{name,mimeType,path}]`. Artifact paths are relative to the report
+directory and must remain under that run's `artifacts/` directory. The built-in
+Playwright reporter supplies these from actual step/startup/attachment evidence.
+Older protocol runners can omit them; ADS preserves that lack of classification
+instead of treating an arbitrary thrown message as an assertion.
 `file` is project-relative. Nonzero process exit, missing cases, skipped cases,
 wrong run IDs and unavailable reports do not pass. Test commands are trusted
 project code; an adapter cannot prove the quality or honesty of their assertions.
@@ -285,6 +307,17 @@ changes mark results stale; changes during execution prevent a current pass.
 Guarantees report passing only when all their checks have current passing evidence.
 Passing applies to those cases and profiles, not every application state.
 
+Results expose structured `failure` boundaries and explicit `acceptance` scope.
+Use `ads_investigate({unit,check})` for the latest compact investigation, including
+isolated dry runs; `ads://project/investigations` lists available entries. Exact
+input and observed preview revisions, failing step/source, startup viewport,
+failed startup requests and available project-recorded artifacts keep diagnosis
+separate from an inferred component defect. No artifact is invented or test
+retried. Each check retains one latest bundle; old artifact resource access is
+superseded. Candidate bundles remain distinct from passing live-source evidence.
+Read the portable [evidence reference](../skills/ads-designer/references/evidence.md)
+for category meanings, collection limits and artifact policy.
+
 Revisions include owned files, literal import dependencies, local CSS imports and
 asset URLs, token foundation, project/runner configuration, lockfiles and tooling.
 Computed module selection conservatively includes all ADS owners. Environment,

package/docs/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.3.17
+
+- Recognize native semantic composition through source-verified runtime Linaria
+  selectors, including runtime-owned part bindings. Keep unrelated controls,
+  broad selectors, fabricated markers and custom scenario styling rejected.
+- Distinguish architecture, build, transport, runner and assertion boundaries;
+  expose explicit acceptance scope and latest-per-check investigation bundles
+  with revisions, source/step, startup viewport, requests and available artifacts.
+  Preserve candidate/live-source evidence and independent case outcomes.
+- Add generic React/Preact conformance checks for selector composition, extracted
+  CSS, MCP resource recovery and native iframe interaction. Document diagnosis
+  through portable skill references without project-specific implementation rules.
+
+## 0.3.16
+
+- Recover transient showcase MCP resource fetch failures with bounded read-only
+  retries. Keep tool calls, assertions, checks and non-transport failures outside
+  recovery; expose recovered startup reads in verification diagnostics and keep
+  persistent loading failures blocking. Verify interrupted resource delivery and
+  failed delivery against a dummy App, without changing project verification policy.
+
 ## 0.3.15
 
 - Keep fragment links inside inline preview documents by supplying a local

package/docs/MCP.md

@@ -177,6 +177,7 @@ The server supplies agent guidance through its instructions, tool descriptions,
 | `ads_show_scenario` | Render an exact discovered scenario with its own fixtures |
 | `ads_behaviors` | Bounded guarantee/evidence discovery; pass an exact unit for contract details |
 | `ads_verify` | Execute an owner's registered checks and record revision-bound evidence |
+| `ads_investigate` | Read one check's latest compact failure/evidence bundle without rerunning it |
 | `ads_capture` | On-demand PNG of a discovered scenario or named element; replace current and clear candidate |
 | `ads_capture_clear` | Remove generated captures or discard only the candidate |
 | `ads_show_<id>` | Optional explicitly configured grouped App |
@@ -275,6 +276,18 @@ single failed assertion does not turn the other checks into failures. Overall
 verification and guarded application still fail. Suite errors, unexplained exits,
 missing results and interrupted reports cannot certify passing checks.
 
+For diagnosis, call `ads_investigate({ "unit": "components/Example", "check": "keyboard-navigation" })`
+with discovered IDs. It reads the latest check bundle without rerunning anything,
+including rejected candidates. `ads://project/investigations` lists available
+bundles; returned resource URIs expose the bundle and available registered
+artifacts. Exact input/observed preview revisions, source/failing step, startup
+viewport and failed requests separate evidence from a suspected cause.
+`failure.category` distinguishes architecture, build, transport, runner and
+assertion boundaries; `acceptance` names established and unverified scope.
+Only the latest bundle per check remains resource-accessible. Read the portable
+[evidence guide](../skills/ads-designer/references/evidence.md) for collection
+limits and project-controlled trace/screenshot recording.
+
 Browser profiles start an isolated showcase and verify its sandboxed App using
 the selected candidate's sources. StrictMode profiles need a project React
 development harness. Profiles describe the execution environment, not a proof

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reqvire-org/ads",
-  "version": "0.3.15",
+  "version": "0.3.17",
   "type": "module",
   "description": "A design system your agent can see and shape. Your components. Your look. Your code.",
   "repository": {