@reqvire-org/ads 0.3.16 → 0.3.17

package/dist/verification/browser.mjs

@@ -16,30 +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(() => ({}));
+        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") throw new Error(state.message || "The MCP App failed before verification.");
+        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

@@ -10,6 +10,7 @@ module.exports = class AdsBehaviorReporter {
     this.active = new Map();
     this.diagnostics = new Map();
     this.diagnosticBuffers = new Map();
+    this.steps = new Map();
     this.startedAt = Date.now();
     this.totalTests = 0;
   }
@@ -22,25 +23,42 @@ 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);
     const diagnostics = this.diagnostics.get(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(), ...(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) });
+    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(-4000));
+    this.diagnosticBuffers.set(test.id, lines.pop().slice(-8192));
     for (const line of lines) {
-      if (line.length > 4000) continue;
+      if (line.length > 8192) continue;
       try {
         const diagnostic = JSON.parse(line).adsPreviewDiagnostic;
-        if (diagnostic?.kind !== "resource-read-recovery" || typeof diagnostic.scenario !== "string" || !Number.isSafeInteger(diagnostic.retries) || diagnostic.retries < 1) continue;
+        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({ 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)) });
+        if (collected.length < 5) collected.push(entry);
         this.diagnostics.set(test.id, collected);
       } catch { /* Ordinary test output is not an ADS startup diagnostic. */ }
     }

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,7 +318,17 @@ 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) } : {}),
@@ -317,6 +338,7 @@ export function createVerificationController(root, { reportRoot = root, onProgre
           }
           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;
@@ -325,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

@@ -322,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.
 
@@ -427,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

@@ -272,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.
@@ -300,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,18 @@
 # 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

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.16",
+  "version": "0.3.17",
   "type": "module",
   "description": "A design system your agent can see and shape. Your components. Your look. Your code.",
   "repository": {