@reqvire-org/ads 0.3.16 → 0.3.18

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/ADS.md

@@ -259,6 +259,16 @@ custom styling in fixture files. The ADS frame pattern uses `--ux-*`. Foreign br
 CSS imports the approved token files in order; shared assignments belong in
 those token files, never in consumer styles or component state overrides.
 
+Typed custom-property registrations follow the same ownership. Runtime-variable
+`@property` metadata lives in component/pattern Linaria; shared and owner-local
+token registrations live beside real token definitions. Names are document-global:
+unrelated owners and conflicting descriptor sets cannot claim the same name.
+Descriptors have their own CSS grammar and independent literal defaults; normal
+visual styling still uses tokens. Registration does not create token/sample
+coverage, and base resets/font metadata cannot host it. Preserve whole rules with
+the ADS Linaria resolver in product and MCP preview builds. See the portable
+[atomic styling guide](../skills/ads-designer/references/atomic-styles.md).
+
 Foundation roles are enforced by `foundation-role`, `foundation-selector` and
 `foundation-import`, alongside the regular token checks. Shared definitions
 belong on the document root or explicit root themes; ordinary declarations belong

package/docs/ARCHITECTURE.md

@@ -155,6 +155,19 @@ values; source guards alone cannot establish extraction correctness. The
 skill-local [atomic styling guide](../skills/ads-designer/references/atomic-styles.md#preserve-custom-property-arithmetic-during-extraction)
 documents integration and source-workaround semantics.
 
+The resolver also preserves complete `@property` registrations and their
+conditional at-rule context for atomic `css`/`styled`. Their descriptors are schema
+metadata, not separate atomic declarations. CSS-tree validates CSS value grammar;
+PostCSS supplies source/at-rule structure. Registered names have one owner and a
+stable schema across its modules, because registration is document-global. Runtime
+variables are registered in owned Linaria; shared or namespaced design tokens are
+registered beside their real value definitions. Base resets and fonts cannot own
+registrations. Descriptor literals are narrowly permitted where CSS requires an
+independent initial value; ordinary visual assignments remain token-governed.
+MCP serves these styles to the sandboxed App document. Registration metadata
+neither creates new token definitions nor replaces token sample coverage.
+Compiled-CSS and browser tests verify interpolation in React and Preact Apps.
+
 ## Public APIs preserve the boundary
 
 The application and project-owned preview scenarios consume a project's public ADS entry. Components
@@ -322,7 +335,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 +445,34 @@ 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).
+
+MCP delivery is separate from validation: verification and mutation controllers
+use complete results to decide acceptance. Their MCP replies contain counts,
+bounded acceptance, at most three failure previews and a result ID in at most
+4 KiB of UTF-8 JSON. `ads_results` reads saved outcomes, diagnostics and other
+sections without rerunning checks. Pages have at most 20 rows and 8 KiB of JSON;
+truncated records support bounded text ranges. Discovery and investigation
+sections use the same paging budget. Cursors bind the query and result/revision;
+superseded IDs fail explicitly instead of silently returning another run.
+Only the latest verification and mutation snapshots are retained, each at most
+8 MiB under `.ds/tool-results/`. Oversized reports retain a summary with an
+explicit unavailable-details warning. Storage/notification failure cannot change
+an accepted edit's applied state. These are payload byte budgets, not tokenizer
+estimates; MCP compatibility text may duplicate structured JSON on the wire.
+
+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,29 @@ 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.
+MCP execution replies contain counts, bounded acceptance, at most three failure
+previews and a `resultId` (4 KiB UTF-8 JSON maximum). Use `ads_results` to read
+selected `outcomes`, `checks`, `diagnostics` or other sections without execution.
+Pages default to 10 rows, allow at most 20 and stay within 8 KiB; follow
+`nextCursor` with identical selection/status. Truncated records provide
+`recordIndex` for exact `offset`/`chars` ranges. Only the latest verification and
+mutation snapshots are retained, independently, at most 8 MiB each. Replaced IDs
+fail explicitly. Validation still uses complete internal outcomes.
+
+Use `ads_investigate({unit,check,runId})` with an outcome's exact IDs for its compact
+summary (4 KiB maximum); details, requests, browser errors and artifact metadata are separate
+paged sections (8 KiB maximum). Truncated records support exact text ranges with
+the recorded run ID. Saved outcomes describe completion time; compare current
+`ads_behaviors` revisions for freshness. It includes 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,35 @@
 # Changelog
 
+## 0.3.18
+
+- Preserve complete typed `@property` registrations through atomic css/styled
+  extraction, conditional rules and CSS minification. Validate descriptors with
+  CSS-tree, enforce runtime/token ownership and naming conflicts, and retain
+  ordinary style-token gates. Verify dummy interpolation in React/Preact MCP Apps.
+- Sync all skill references for registrations and selector-owned native
+  composition; keep implementation independent of any imported component library.
+
+- Deliver verification and guarded-edit replies as 4 KiB JSON summaries with
+  counts, acceptance and result IDs. Page outcomes, diagnostics, logs and captures
+  through `ads_results`; retain only the latest verification and mutation snapshots.
+  Keep complete internal validation independent of delivery.
+- Page behavior discovery and investigation details; bind cursors to their query
+  and recorded run, reject superseded evidence, and document selective retrieval
+  in every portable skill. Keep artifacts separate from tool JSON.
+
+## 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

@@ -175,8 +175,10 @@ The server supplies agent guidance through its instructions, tool descriptions,
 | `ads_show_tokens` | Render a discovered token scenario; legacy compilers retain the definition inspector |
 | `ads_scenarios` | Bounded token/component/pattern/composition scenario discovery |
 | `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_behaviors` | Paged owner discovery; select a unit and detail section |
 | `ads_verify` | Execute an owner's registered checks and record revision-bound evidence |
+| `ads_results` | Page saved execution outcomes, diagnostics, logs and captures without rerunning |
+| `ads_investigate` | Read one check's summary, then paged requests/errors/artifacts |
 | `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 |
@@ -192,8 +194,9 @@ public exports from `components/`, `patterns/` and `controllers/`; it does not e
 guess component props. Read the exported API and owning guide. An export name
 alone does not prove that a preview renders that particular element.
 
-`ads://project/status`, `/build`, `/tokens`, `/catalog`, `/scenarios`, `/behaviors`, and `/checks` carry complete JSON
-detail. Allowed project documentation/source and skill files are separate
+`ads://project/status`, `/build`, `/tokens`, `/catalog`, `/scenarios` and `/checks`
+carry project JSON detail. Behavior discovery, execution outcomes and investigation
+details are paged; their resource reads use the same bounds as their tools. Allowed project documentation/source and skill files are separate
 resources. No arbitrary filesystem reader is exposed. Prefer bounded tools for
 large catalogues; explicit resource reads can enter model context and a client
 may truncate large payloads.
@@ -214,6 +217,14 @@ informational limit nor a traced target proves a rendered failure or success.
 Bounded check results put warnings before informational limits; the checks
 resource retains complete results.
 
+`property-registration` is a blocking architecture diagnostic for invalid or
+conflicting typed CSS registrations. Keep registrations in their runtime owner
+or beside their real token definitions; `base.css` remains a closed reset contract.
+Use `@reqvire-org/ads/linaria` in both product and preview extraction so each
+registration survives intact in the App's CSS resources. Descriptor literals are
+metadata; normal styling still uses tokens. Read `ads://guides/atomic-styles` for
+ownership, valid initial values, browser checks and examples.
+
 ### Screenshots and candidate comparison
 
 `ads_capture({scenario:"<discovered ID>",target?,theme?,viewport?})` renders current
@@ -248,8 +259,10 @@ limits, target declarations and the guarded review workflow.
 
 Read `ads://guides/behaviors` or the [behavior guide](BEHAVIORS.md) for the contract
 and runner schema. `ads_behaviors({ "unit": "components/MessageScroller" })`
-returns subjects, guarantees, demonstration links and check IDs for a discovered
-owner. `ads_verify({ "unit": "components/MessageScroller", "checks": ["prepend-anchor"] })`
+pages an owner's checks by default; select `section: "subjects"`, `"guarantees"`,
+`"demonstrations"` or `"profiles"` for other details. Without a unit it lists owner
+summaries. Follow `nextCursor` with identical filters. Changed registrations or
+evidence revisions invalidate discovery cursors. `ads_verify({ "unit": "components/MessageScroller", "checks": ["prepend-anchor"] })`
 runs those registered cases. The names here are examples, never built-in cases.
 
 `covers` describes rendered UI; optional `exercises` describes public behavioral
@@ -275,6 +288,51 @@ 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.
 
+Verification and guarded-edit replies are summaries: counts, acceptance, at most
+three failure previews and `resultId`, within 4096 UTF-8 JSON bytes. Use:
+
+```js
+ads_results({resultId: "<returned ID>", section: "outcomes", status: "not_passed"})
+ads_results({resultId: "<returned ID>", section: "outcomes", status: "not_passed", cursor: "<nextCursor>"})
+```
+
+Each listing defaults to 10 rows, allows at most 20 and stays within 8192 JSON
+bytes. A byte-limited page can contain fewer than `limit` rows; follow
+`nextCursor` with the same result ID, section and status. Other sections are
+`checks`, `advisories`, `warnings`, `changes`, `captures`, `acceptance`,
+`investigation` and `selection`. No page reruns validation. Rows marked
+`detailTruncated` can be read exactly with `recordIndex`, `offset` and `chars`
+(maximum 2000 UTF-16 characters); follow `nextOffset`. Read full logs only for the
+relevant record. JSON also remains available through `ads://results/<resultId>`;
+use matching query parameters for pages or ranges. `ads://project/results` lists
+the latest IDs. Status embeds summaries, not complete runner reports. Saved
+outcomes are completion-time evidence; compare revisions with `ads_behaviors`
+before claiming current source passed.
+
+Only the latest verification snapshot and latest mutation snapshot are retained,
+independently, each up to 8 MiB in `.ds/tool-results/`. Replacing a snapshot makes
+its old ID unavailable; do not mix pages across runs. An oversized report retains
+only its summary and an explicit unavailable-details warning. A failed disk write
+keeps details in server memory until shutdown. Neither condition changes guard
+acceptance or whether source was applied. These are logical payload byte limits;
+compatibility text can duplicate structured JSON in the MCP response.
+
+For diagnosis, take one outcome's exact `unit`, `check` and `runId` and call
+`ads_investigate`. The run ID rejects superseded evidence. Without a check, it
+lists available investigations with paging. An exact check returns a summary
+within 4096 JSON bytes; `section: "details"`, `"requests"`, `"browserErrors"` or `"artifacts"`
+returns detail pages with the same 10/20-row and 8192-byte limits. Truncated records support
+`recordIndex`/`offset`/`chars` with the exact `runId`; artifact URIs are read
+separately. It never reruns checks, 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.
+The summary's `details.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
@@ -411,8 +469,9 @@ Pass that `patchFile` to `ads_apply_patch` with `dryRun:true` to validate before
 applying. This runs the normal candidate gates, including affected registered
 behavior checks against an isolated candidate and its configured browser preview.
 It writes no live source and does not persist passing evidence for live inputs.
-Read returned `behavior` failures or behavior-check results in `checks`; update the
-draft, diff again and repeat as needed. Apply with `dryRun:false` after validation;
+Read the summary, then use its `resultId` with `ads_results` for failing
+`outcomes`, `diagnostics` or named pipeline `checks`; update the draft, diff again
+and repeat as needed. Apply with `dryRun:false` after validation;
 the gates run again. `ads_verify({unit,checks?})` checks current source and accepts
 no draft argument; a selected-check draft runner is not currently exposed.
 Use `action:"discard"` to remove the draft. Remote clients can continue sending

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reqvire-org/ads",
-  "version": "0.3.16",
+  "version": "0.3.18",
   "type": "module",
   "description": "A design system your agent can see and shape. Your components. Your look. Your code.",
   "repository": {
@@ -52,6 +52,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/server": "2.3.1",
+    "css-tree": "3.2.1",
     "postcss": "^8.5.30",
     "postcss-selector-parser": "^7.1.6",
     "postcss-value-parser": "^4.2.0",