@reqvire-org/ads 0.3.3 → 0.3.6

package/README.md

@@ -58,6 +58,8 @@ Linaria; integrate its extraction with your build as described in the
 | `ads init --framework react` | Set up ADS in the current project; also accepts `preact`; saved choices can omit the flag |
 | `ads check` | Check tokens, styles, imports, and ADS ownership |
 | `ads tokens` | Inspect token values and themes |
+| `ads behaviors` | Inspect registered behavior guarantees and current evidence |
+| `ads verify --unit <id>` | Run an owner's registered behavior checks |
 | `ads assets` | Generate standard web icons from the project's SVG |
 | `ads lint-config` | Generate lint config; normally called by the build |
 | `ads mcp` | Start the stdio MCP server and its local showcase |
@@ -89,12 +91,22 @@ for config files and Claude Desktop setup.
 To let the agent edit the ADS through enforced checks, append `--mutations` to
 the MCP command. It accepts a Git patch for one ADS unit, including its owned scenarios and
 fixtures, and runs the guards before applying it. Foundation styles, original
-assets, guides and project configuration/guard extensions have editable units too. See [guarded editing](docs/MCP.md#guarded-editing).
+assets, guides and project configuration/guard extensions have editable units too.
+Coupled changes use bounded owner transactions with checks on the complete final
+candidate. Local owner drafts and token-sample preparation reduce patch setup;
+they keep source writes behind the same guards. See
+[guarded editing](docs/MCP.md#guarded-editing).
 
 The server exposes public components/patterns, token values,
-source guides, architecture checks, workflow prompts, and packaged ADS skills.
+source guides, controllers/hooks, architecture checks, behavioral verification,
+workflow prompts, and packaged ADS skills.
 It supports older MCP clients and the newer Skills protocol.
 
+Private controllers stay beside their component; shared controllers have their own
+edit units. Optional behavior contracts connect guarantees to maintained checks.
+Demonstrations and passing execution evidence remain distinct. See
+[controllers and verification](docs/BEHAVIORS.md).
+
 Experimental MCP Apps show an interactive token inspector and project-built
 token, component, pattern and composition scenarios. They use the same public implementations and fixtures
 as the showcase. Text and resource access remain available without Apps support.
@@ -202,13 +214,13 @@ app's bundler. With no icon source, generation is skipped. See the
 Install skills with `npx skills`:
 
 ```sh
-npx skills add reqvire-org/ads --skill ads-designer --skill ads-import --skill ads-assimilate --skill ads-break-ui --skill ads-motion
+npx skills add reqvire-org/ads --skill ads-designer --skill ads-import --skill ads-migrate --skill ads-break-ui --skill ads-motion
 ```
 
 For local development, install from this checkout:
 
 ```sh
-npx skills add ./skills --skill ads-designer --skill ads-import --skill ads-assimilate --skill ads-break-ui --skill ads-motion
+npx skills add ./skills --skill ads-designer --skill ads-import --skill ads-migrate --skill ads-break-ui --skill ads-motion
 ```
 
 Acknowledgments: `ads-designer`'s craft/mobile guidance, `ads-break-ui`, and
@@ -220,7 +232,7 @@ notice beside its files.
 
 - [ads-designer](skills/ads-designer/SKILL.md): start an ADS or build UI with your local ADS.
 - [ads-import](skills/ads-import/SKILL.md): import external components, patterns, styles, token values, or brand artwork.
-- [ads-assimilate](skills/ads-assimilate/SKILL.md): implement a native component inspired by an external library.
+- [ads-migrate](skills/ads-migrate/SKILL.md): implement a native component inspired by an external library.
 - [ads-break-ui](skills/ads-break-ui/SKILL.md): stress-test real components and patterns with difficult content.
 - [ads-motion](skills/ads-motion/SKILL.md): implement, review, audit, or profile component animation.
 

package/dist/behaviors.mjs

@@ -0,0 +1,157 @@
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import path from "node:path";
+import { isBuiltin } from "node:module";
+import ts from "typescript";
+import { z } from "zod";
+import { isBehaviorFile, isDevelopmentFile, isInside, sourceFiles } from "./config.mjs";
+import { importResolver, projectCompilerOptions } from "./boundaries.mjs";
+import { inspectUnits } from "./units.mjs";
+import { publicApi } from "./public-api.mjs";
+import { inspectScenarios } from "./scenarios.mjs";
+import { uiOperation } from "./ui-framework.mjs";
+
+const id = z.string().regex(/^[a-zA-Z0-9][\w.-]{0,99}$/);
+const reference = z.string().min(1).max(500);
+const subject = z.union([
+  z.object({ api: reference }).strict(),
+  z.object({ source: reference, symbol: reference.optional() }).strict(),
+]);
+export const behaviorSchema = z.object({
+  schemaVersion: z.literal(1),
+  subjects: z.record(id, subject).refine(value => Object.keys(value).length > 0 && Object.keys(value).length <= 100),
+  guarantees: z.array(z.object({ id, description: z.string().min(1).max(2000), subjects: z.array(id).min(1).max(100), checks: z.array(id).min(1).max(100) }).strict()).min(1).max(100),
+  checks: z.record(id, z.object({ file: reference, case: id, scenario: reference.optional(), profile: id }).strict()).refine(value => Object.keys(value).length > 0 && Object.keys(value).length <= 100),
+}).strict();
+
+/** Static contracts never execute project code or certify natural-language claims. */
+export function inspectBehaviors(options, suppliedProgram, suppliedRegistry) {
+  const { root, dsRoot, config } = options;
+  const inventory = inspectUnits(options);
+  const files = sourceFiles(dsRoot).filter(isBehaviorFile);
+  if (!files.length) return { contracts: [], diagnostics: [] };
+  const program = suppliedProgram ?? ts.createProgram(sourceFiles(dsRoot).filter(file => /\.[cm]?[jt]sx?$/.test(file)), { ...projectCompilerOptions(options), allowJs: true });
+  const checker = program.getTypeChecker();
+  const apis = new Map(publicApi(program, options).map(item => [item.name, item]));
+  const scenarios = (suppliedRegistry ?? inspectScenarios(options, program)).scenarios;
+  const diagnostics = [], contracts = [], owners = new Set();
+  const relative = file => path.relative(root, file).replaceAll("\\", "/");
+  for (const file of files) {
+    const report = message => diagnostics.push({ file: relative(file), rule: "behavior-contract", line: 1, column: 1, message });
+    let value;
+    try {
+      if (statSync(file).size > 128 * 1024 || realpathSync(file) !== file) throw new Error("Behavior contracts must be regular files of at most 128 KiB.");
+      const parsed = behaviorSchema.safeParse(JSON.parse(readFileSync(file, "utf8")));
+      if (!parsed.success) throw new Error(parsed.error.issues.slice(0, 5).map(issue => `${issue.path.join(".")}: ${issue.message}`).join("; "));
+      value = parsed.data;
+    } catch (error) { report(error.message); continue; }
+    const unit = inventory.owner(inventory.relative(relative(file)));
+    if (!["components", "patterns", "controllers"].includes(unit?.split("/")[0])) { report("Behavior contracts belong to a component, pattern or controller unit."); continue; }
+    if (owners.has(unit)) { report(`Only one behavior contract may describe ${unit}.`); continue; }
+    owners.add(unit);
+    function owned(target, field) {
+      if (path.isAbsolute(target) || target.includes("\\") || target.includes("\0")) { report(`${field} must be an owner-local relative path.`); return null; }
+      const absolute = path.resolve(path.dirname(file), target);
+      if (!isInside(dsRoot, absolute) || inventory.owner(inventory.relative(relative(absolute))) !== unit
+        || !existsSync(absolute) || !statSync(absolute).isFile() || realpathSync(absolute) !== absolute) { report(`${field} must resolve to a real file in ${unit}: ${target}`); return null; }
+      return absolute;
+    }
+    for (const [name, entry] of Object.entries(value.subjects)) {
+      if (entry.api) {
+        const api = apis.get(entry.api);
+        if (!api || inventory.owner(inventory.relative(relative(api.file))) !== unit) report(`Subject ${name} must resolve to a public API owned by ${unit}: ${entry.api}`);
+      } else {
+        const source = owned(entry.source, `Subject ${name}`);
+        if (source && isDevelopmentFile(source, options)) report(`Subject ${name} must identify runtime implementation, not a fixture, scenario or check.`);
+        if (source && entry.symbol) {
+          const ast = program.getSourceFile(source);
+          if (!ast || !checker.getSymbolsInScope(ast, ts.SymbolFlags.Value).some(symbol => symbol.name === entry.symbol && symbol.declarations?.some(declaration => declaration.getSourceFile() === ast))) report(`Subject ${name}: symbol ${entry.symbol} is not declared in ${entry.source}.`);
+        }
+      }
+    }
+    const guaranteeIds = new Set();
+    for (const guarantee of value.guarantees) {
+      if (guaranteeIds.has(guarantee.id)) report(`Duplicate guarantee ID ${guarantee.id}.`);
+      guaranteeIds.add(guarantee.id);
+      for (const name of guarantee.subjects) if (!Object.hasOwn(value.subjects, name)) report(`Guarantee ${guarantee.id} references unknown subject ${name}.`);
+      for (const check of guarantee.checks) if (!Object.hasOwn(value.checks, check)) report(`Guarantee ${guarantee.id} references unknown check ${check}.`);
+    }
+    const cases = new Set();
+    for (const [name, check] of Object.entries(value.checks)) {
+      const target = owned(check.file, `Check ${name}`);
+      if (target && !isDevelopmentFile(target, options)) report(`Check ${name} must use a development-only test/spec file.`);
+      if (!Object.hasOwn(config.mcp.behaviorProfiles, check.profile)) report(`Check ${name} references unregistered profile ${check.profile}. Register its literal runner command in ds.config.json; checks cannot install packages or assume host globals.`);
+      if (check.scenario && !scenarios.some(scenario => scenario.id === check.scenario)) report(`Check ${name} references unknown scenario ${check.scenario}.`);
+      const identity = JSON.stringify([check.file, check.case, check.profile]);
+      if (cases.has(identity)) report(`Duplicate execution identity for check ${name}. Use one check ID and reference it from several guarantees.`);
+      cases.add(identity);
+    }
+    contracts.push({ ...value, unit, file: relative(file), demonstrations: Object.fromEntries(Object.entries(value.subjects).filter(([, item]) => item.api).map(([name, item]) => [name, scenarios.filter(scenario => scenario.exercises?.includes(item.api)).map(scenario => scenario.id)])) });
+  }
+  return { contracts, diagnostics };
+}
+
+/** Headless ownership applies to shared controllers and explicitly named private subjects. */
+export function inspectControllers(options, program, report, contracts = []) {
+  const { root, dsRoot, config } = options;
+  const resolve = importResolver(options);
+  const pkg = existsSync(path.join(root, "package.json")) ? JSON.parse(readFileSync(path.join(root, "package.json"), "utf8")) : {};
+  const declared = new Set(Object.keys({ ...pkg.dependencies, ...pkg.devDependencies, ...pkg.peerDependencies, ...pkg.optionalDependencies }));
+  const privateFiles = new Map();
+  for (const contract of contracts) for (const subject of Object.values(contract.subjects).filter(item => item.source)) {
+    const file = path.resolve(root, path.dirname(contract.file), subject.source);
+    if (!privateFiles.has(file)) privateFiles.set(file, new Set());
+    privateFiles.get(file).add(subject.symbol ?? null);
+  }
+  const checker = program.getTypeChecker();
+  for (const source of program.getSourceFiles()) {
+    const file = source.fileName;
+    if (isDevelopmentFile(file, options) || !isInside(path.join(dsRoot, "controllers"), file) && !privateFiles.has(file)) continue;
+    const wholeFile = isInside(path.join(dsRoot, "controllers"), file) || privateFiles.get(file)?.has(null);
+    const subjects = wholeFile ? [] : checker.getSymbolsInScope(source, ts.SymbolFlags.Value).filter(symbol => privateFiles.get(file)?.has(symbol.name)).flatMap(symbol => symbol.declarations ?? []);
+    const headless = node => wholeFile || subjects.some(subject => subject.getSourceFile() === source && node.pos >= subject.pos && node.end <= subject.end);
+    function emit(node, rule, message) { const p = source.getLineAndCharacterOfPosition(node.getStart()); report(file, rule, message, p.line + 1, p.character + 1); }
+    function visit(node) {
+      let specifier;
+      if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier && ts.isStringLiteralLike(node.moduleSpecifier)) specifier = node.moduleSpecifier.text;
+      if (ts.isCallExpression(node) && (node.expression.kind === ts.SyntaxKind.ImportKeyword || ts.isIdentifier(node.expression) && node.expression.text === "require") && node.arguments[0] && ts.isStringLiteralLike(node.arguments[0])) specifier = node.arguments[0].text;
+      if (specifier) {
+        const typeOnly = ts.isImportDeclaration(node) && (node.importClause?.isTypeOnly || node.importClause?.namedBindings && ts.isNamedImports(node.importClause.namedBindings) && !node.importClause.name && node.importClause.namedBindings.elements.every(item => item.isTypeOnly)) || ts.isExportDeclaration(node) && node.isTypeOnly;
+        if (!typeOnly) {
+          if (wholeFile && /^(?:@linaria\/|.*\.css(?:[?#].*)?$)/.test(specifier)) emit(node, "controller-skin", "Controllers own behavior and measurements. Put CSS/Linaria skins in the consuming component or pattern.");
+          const framework = /^(?:react|react-dom)(?:\/|$)/.test(specifier) ? "react" : /^preact(?:\/|$)/.test(specifier) ? "preact" : null;
+          if (framework && config.framework !== framework) emit(node, "controller-framework", `Controller imports ${framework}, but ds.config.json selects ${config.framework ?? "no framework"}. Use the configured framework or plain TypeScript/browser APIs; MCP hosts do not supply another runtime.`);
+          const targets = resolve(specifier, file);
+          const local = specifier.startsWith(".") || specifier === config.publicAlias || targets.some(target => isInside(root, target) && !target.includes(`${path.sep}node_modules${path.sep}`) && existsSync(target));
+          if (local) {
+            if (targets.some(target => !existsSync(target))) emit(node, "controller-dependency", `Unresolved controller dependency ${specifier}. Declare real project dependencies and local modules; do not assume MCP host globals.`);
+            if (isInside(path.join(dsRoot, "controllers"), file)) {
+              const targetsInUi = targets.some(target => ["components", "patterns"].some(kind => isInside(path.join(dsRoot, kind), target)));
+              if (targetsInUi) emit(node, "controller-dependency", "Shared controllers cannot import component/pattern runtime implementations. Pass behavior adapters or callbacks from the consumer; type-only imports are allowed.");
+              if (specifier === config.publicAlias) {
+                for (const item of node.importClause?.namedBindings && ts.isNamedImports(node.importClause.namedBindings) ? node.importClause.namedBindings.elements : []) {
+                  let symbol = checker.getSymbolAtLocation(item.name);
+                  if (symbol?.flags & ts.SymbolFlags.Alias) symbol = checker.getAliasedSymbol(symbol);
+                  if (symbol?.declarations?.some(declaration => ["components", "patterns"].some(kind => isInside(path.join(dsRoot, kind), declaration.getSourceFile().fileName)))) emit(item, "controller-dependency", "Shared controllers consume behavior helpers, not styled component/pattern implementations.");
+                }
+                if (!node.importClause?.namedBindings || ts.isNamespaceImport(node.importClause.namedBindings)) emit(node, "controller-dependency", "Use explicit behavior imports in shared controllers so dependency ownership can be checked.");
+              }
+            }
+          } else if (!isBuiltin(specifier)) {
+            const name = specifier.startsWith("@") ? specifier.split("/").slice(0, 2).join("/") : specifier.split("/")[0];
+            if (!declared.has(name)) emit(node, "controller-dependency", `Undeclared controller dependency ${name}. Register it in the project package; ADS does not install dependencies or receive them from an MCP host.`);
+          }
+        }
+      }
+      if (headless(node) && ((ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node)) && ts.isIdentifier(node.tagName) && /^[a-z]/.test(node.tagName.text)
+        || ts.isCallExpression(node) && uiOperation(node.expression, checker) === "createElement" && node.arguments[0] && ts.isStringLiteralLike(node.arguments[0]))) emit(node, "controller-skin", "Visual DOM markup belongs in components/patterns. Controllers may use framework hooks and context providers.");
+      if (!wholeFile && headless(node) && (ts.isTaggedTemplateExpression(node) || ts.isCallExpression(node))) {
+        let base = ts.isTaggedTemplateExpression(node) ? node.tag : node.expression;
+        while (ts.isPropertyAccessExpression(base) || ts.isCallExpression(base)) base = base.expression;
+        if (checker.getSymbolAtLocation(base)?.declarations?.some(declaration => ts.isImportSpecifier(declaration) && declaration.parent.parent.parent.moduleSpecifier.text.startsWith("@linaria/")
+          || ts.isNamespaceImport(declaration) && declaration.parent.parent.moduleSpecifier.text.startsWith("@linaria/"))) emit(node, "controller-skin", "Keep Linaria styling outside the declared private controller subject, in its visual consumer.");
+      }
+      ts.forEachChild(node, visit);
+    }
+    visit(source);
+  }
+}

package/dist/bootstrap-ds/ADS.md

@@ -36,8 +36,14 @@ Projects sharing this ADS use the same token names, meanings, and value types;
 their concrete values and theme overrides can differ. Reuse existing local values
 when importing components/patterns, add missing shared definitions, and import
 source token values only when adopting that theme is requested.
-Token names and prefixes are fixed by ADS architecture; foreign brand prefixes
-are rejected. Shared assignments belong in token files. Components own
+Shared token names and prefixes follow the ADS contract. A component/pattern may
+register one unique local namespace in colocated `tokens.json` and define it in
+`tokens.css`, imported by its runtime. Flat owners use `<Owner>.tokens.json` and
+`<Owner>.tokens.css`. These definition-only sheets contain root/theme custom
+properties, not UI selectors or ordinary styles. Other owners consume shared
+tokens; they cannot override or consume a peer's local namespace. A colocated
+`kind:"tokens"` scenario needs real samples for every local token. Shared
+assignments remain in the shared token files. Components own
 `--ds-*`, patterns `--ux-*`, and the showcase `--showcase-*`; token files cannot
 assign those local variables or override component state.
 
@@ -183,7 +189,7 @@ mounting, correct props, every branch/state or visual parity. The older
 
 `token-scenario-reference` rejects undeclared token names in metadata and reachable
 inputs. `token-scenario-render` rejects claimed tokens with no reachable input
-reference; `token-scenario-coverage` requires every discovered foundation token
+reference; `token-scenario-coverage` requires every discovered shared or owner-local token
 to have coverage. A new or removed token therefore needs a scenario/fixture
 update. All three are errors in `ads check`, run by `lint:ds` and the build.
 Coverage is static reachability, not proof that every branch actually renders
@@ -241,3 +247,10 @@ Run `npm run build` after adding or changing components. Add meaningful tests
 for stateful behavior, accessibility, gestures, or async lifecycle where needed.
 Run `npm run dev` to inspect the real showcase. A screenshot alone does not
 verify interaction or animation. Generated output and dependencies are not source.
+
+Shared behavior may live in `controllers/<Name>/`; private controllers stay with
+their component/pattern. Use the configured framework and declared dependencies.
+Behavior contracts/checks are development-only, and scenario `exercises` links
+public hooks to demonstrations separately from rendered `covers`. Read the
+installed ADS package's `docs/BEHAVIORS.md` or MCP `ads://guides/behaviors` before
+registering guarantees, profiles and verification.

package/dist/bootstrap-ds/README.md

@@ -62,6 +62,10 @@ the public `TokenPreview` pattern owns their presentation and applies the real C
 variables. Add/remove samples alongside token definitions. `ads check` rejects
 missing coverage and invented names; the App verifies the declared CSS bindings
 in the browser. Extend or replace the project-owned pattern as your tokens evolve.
+`ads_prepare_token_samples` can prepare a fixture patch from explicit project
+property/probe bindings. It preserves existing samples and reports unmapped tokens;
+it does not guess how a new value should look. Component/pattern constants can use
+the colocated namespace contract in [ADS.md](ADS.md), with their own token scenario.
 
 Create a component under `design-system/components/`, export it through `@ds`,
 and colocate `Scenario.tsx` plus `fixture.ts` (or `<Owner>.scenario.tsx` and
@@ -79,6 +83,8 @@ stale retained output. Switching or rebuilding a scenario unmounts its previous
 state. `showcase/mcp/main.tsx` exports `mountScenario(Scenario, container)` and
 returns an unmount callback; it is not the shell. Keep the saved `framework`,
 compiler and mount adapter consistent.
+Managed sessions own their graph output; standalone prebuilds cannot replace it.
+Verified generated graph snapshots preserve warm-start reuse across sessions.
 
 The application and previews use the same foundation CSS and Linaria pipeline.
 The source barrel loads the foundation once. The private `build:lib` script uses
@@ -98,3 +104,7 @@ from a user-selected external repository, preserving revisions and licenses.
 inspection builds it automatically, then loads selected entries. Browser review
 still checks layout, accessibility, keyboard/focus, states, themes and motion. A clean
 build or delivered HTML alone does not establish those behaviors.
+Opt-in MCP editing uses owner Git patches. `ads_prepare_patch` creates a temporary
+owner draft/diff; `ads_apply_transaction` validates bounded coupled owner patches
+against one final candidate. Preparation changes no live source. Keep all guards
+and review the rendered result after applying.

package/dist/boundaries.mjs

@@ -3,6 +3,7 @@ import ts from "typescript";
 import { importedUiName } from "./ui-framework.mjs";
 import { isInside, isStateVariable, isTestFile, isDevelopmentFile } from "./config.mjs";
 import { isSharedToken } from "./token-policy.mjs";
+import { scopedTokenOwner } from "./scoped-tokens.mjs";
 
 export function projectCompilerOptions({ root }) {
   const file = ts.findConfigFile(root, ts.sys.fileExists, "tsconfig.json");
@@ -59,6 +60,8 @@ export function checkComponentVariable(name, filename, options) {
   const components = !development && isInside(path.join(dsRoot, "components"), filename);
   const patterns = !development && isInside(path.join(dsRoot, "patterns"), filename);
   const showcase = development;
+  const owned = scopedTokenOwner(options, name);
+  if (owned) return path.resolve(options.root, owned.file) === filename ? null : { rule: "token-ownership", message: `Define ${name} only in ${owned.file}, owned by ${owned.unit}. Consume it with var(); runtime geometry remains a separate styleWrites boundary.` };
   if (isSharedToken(name)) return tokens ? null : { rule: "token-ownership", message: `Define ${name} in ADS tokens, not component, pattern, showcase, or app styles.` };
   if (name.startsWith("--ux-")) return patterns || showcase ? null : { rule: "variable-ownership", message: "--ux-* variables belong to ADS patterns and showcase composition." };
   if (name.startsWith("--showcase-")) return showcase ? null : { rule: "variable-ownership", message: "--showcase-* variables belong to the ADS showcase." };

package/dist/check.mjs

@@ -15,7 +15,10 @@ import { inspectShowcaseCoverage } from "./showcase-coverage.mjs";
 import { inspectScenarioCoverage } from "./scenarios.mjs";
 import { uiOperation, importedUiApi } from "./ui-framework.mjs";
 import { inspectStyleBoundaries, pointerCaptureAdvisories } from "./style-boundaries.mjs";
+import { inspectBehaviors, inspectControllers } from "./behaviors.mjs";
+import { numericCssUnit, tokenLengthLiteral } from "./css-values.mjs";
 import { foundationDeclaration, foundationSelector } from "./foundation.mjs";
+import { scopedTokens, scopedTokenOwner } from "./scoped-tokens.mjs";
 
 const scenarioLayoutGuidance = "Put demo-only sizing and framing in a public review/layout pattern. Keep required behavior in the runtime owner; add component props for deliberate product API needs.";
 const inlineStyleGuidance = `Own visual styles in component/pattern Linaria. ${scenarioLayoutGuidance} Reserve inlineStyleFiles for documented measured geometry, not demo layout.`;
@@ -38,6 +41,8 @@ export function checkProject(directory, { trackingRoot } = {}) {
   diagnostics.push(...tokenInventory.diagnostics);
   diagnostics.push(...inspectAssets(options));
   const resolveImport = importResolver(options);
+  const scoped = scopedTokens(options);
+  const scopedFiles = new Set(scoped.definitions.map(entry => path.resolve(root, entry.file)));
   const rootHtml = path.join(root, "index.html");
   const files = [...new Set([...sourceFiles(sourceRoot), ...sourceFiles(dsRoot), ...(existsSync(rootHtml) ? [rootHtml] : [])])];
   const boundaryFiles = [...config.inlineStyleFiles, ...config.boundaries.styleWrites.map(entry => entry.file)].map(file => path.resolve(root, file)).filter(file => existsSync(file) && statSync(file).isFile());
@@ -51,7 +56,10 @@ export function checkProject(directory, { trackingRoot } = {}) {
   inspectStyleBoundaries(options, program, report);
   inspectShowcasePages(options, program, resolveImport, report);
   inspectShowcaseCoverage(options, program, report);
-  inspectScenarioCoverage(options, program, report);
+  inspectScenarioCoverage(options, program, report, (file, rule, message) => advisories.push({ file: path.relative(root, file).replaceAll("\\", "/"), rule, message, line: 1, column: 1 }));
+  const behaviors = inspectBehaviors(options, program);
+  diagnostics.push(...behaviors.diagnostics);
+  inspectControllers(options, program, report, behaviors.contracts);
   // The foundation remains a fixed import-only entry, not an extra styling layer.
   const foundationEntry = path.join(dsRoot, config.stylesEntry);
   try {
@@ -105,6 +113,11 @@ export function checkProject(directory, { trackingRoot } = {}) {
       const variable = checkComponentVariable(decl.prop, file, options);
       if (variable) report(file, variable.rule, variable.message, offset.line + decl.source.start.line - 1, decl.source.start.column);
       for (const ref of references(decl.value)) {
+        const owned = scopedTokenOwner(options, ref.name);
+        if (owned) {
+          if (scoped.inventory.owner(scoped.inventory.relative(path.relative(root, file))) !== owned.unit || !declaredTokens.has(ref.name)) report(file, "token-reference", `${ref.name} belongs to ${owned.unit}. Use shared tokens across owners; owner-local tokens must be defined and consumed by their owner.`, offset.line + decl.source.start.line - 1, decl.source.start.column);
+          continue;
+        }
         const local = /^(?:--ds-|--ux-|--showcase-)/.test(ref.name);
         if (foundation && local) report(file, "foundation-role", "Foundation defaults consume shared tokens, not component, pattern or scenario-local variables.", offset.line + decl.source.start.line - 1, decl.source.start.column);
         if (!local && !isSharedToken(ref.name)) report(file, "token-name", `${ref.name} does not follow ADS's fixed token naming contract.`, offset.line + decl.source.start.line - 1, decl.source.start.column);
@@ -114,7 +127,7 @@ export function checkProject(directory, { trackingRoot } = {}) {
       const violations = new Set();
       valueParser(decl.value).walk((node) => {
         if (node.type === "function" && node.value === "url") return false;
-        if (node.type === "word" && /^(?:#[\da-f]{3,8}|[-+]?(?:\d*\.)?\d+(?:px|rem|em|m?s))$/i.test(node.value)) violations.add("Use a token for colors, dimensions, and durations.");
+        if (node.type === "word" && (/^#[\da-f]{3,8}$/i.test(node.value) || tokenLengthLiteral(node.value) || ["s", "ms"].includes(numericCssUnit(node.value)))) violations.add("Use a token for colors, absolute/font-relative lengths (including ch), and durations. Unitless geometry and structural angle/viewport/container relationships remain valid.");
         if (node.type === "function" && /^(?:rgb|rgba|hsl|hsla|hwb|lab|lch|oklab|oklch|color|color-mix|cubic-bezier)$/.test(node.value)) violations.add("Define color formulas and easing in tokens.");
         if (node.type === "function" && /^(?:blur|brightness|contrast|drop-shadow|grayscale|hue-rotate|invert|saturate|sepia)$/.test(node.value)) violations.add("Define visual filter effects in tokens.");
         if (node.type === "word" && /^ease(?:-in|-out|-in-out)?$/.test(node.value)) violations.add("Use a motion token for easing.");
@@ -125,6 +138,7 @@ export function checkProject(directory, { trackingRoot } = {}) {
     });
   }
   for (const file of files) {
+    if (scopedFiles.has(file)) continue; // Closed definition-only contract checked by inspectTokens.
     if (file.endsWith(".css") && isInside(path.join(dsRoot, config.tokenDir), file) && !isDevelopmentFile(file, options)) { checkCss(file, readFileSync(file, "utf8"), undefined, true); continue; }
     if (file.endsWith(".html")) { inspectHtml(readFileSync(file, "utf8"), (rule, message, line) => report(file, rule, message, line)); continue; }
     if (file.endsWith(".css")) {
@@ -218,6 +232,10 @@ export function checkProject(directory, { trackingRoot } = {}) {
       if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)) specifier = node.moduleSpecifier.text;
       if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword && node.arguments[0] && ts.isStringLiteral(node.arguments[0])) specifier = node.arguments[0].text;
       if (specifier && importViolation(specifier, file, options, resolveImport)) nodeReport(node, "public-import", `Import through ${config.publicAlias}, not ADS implementation paths.`);
+      if (specifier) for (const target of resolveImport(specifier, file)) {
+        const tokenOwner = scoped.definitions.find(entry => path.resolve(root, entry.file) === target);
+        if (tokenOwner && scoped.inventory.owner(scoped.inventory.relative(path.relative(root, file))) !== tokenOwner.unit) nodeReport(node, "token-ownership", `Only ${tokenOwner.unit} imports its token sheet. Import the public component/pattern to consume its design.`);
+      }
       if (specifier && resolveImport(specifier, file).some((target) => (specifier.startsWith(".") || existsSync(target)) && target.endsWith(".css") && isInside(root, target) && !isInside(dsRoot, target) && target !== path.join(sourceRoot, "app-mount.css") && !isInside(path.join(root, "node_modules"), target))) nodeReport(node, "style-ownership", "Imported project CSS belongs to ADS components, patterns, or the foundation. Only structural app-mount.css is allowed outside the ADS.");
       if (specifier && appImportViolation(specifier, file, options, resolveImport)) nodeReport(node, "no-app-import", "ADS implementations and showcase fixtures must not import app code. Use public ADS APIs with local fixture data; keep application integration harnesses in application tests.");
       if (specifier && showcaseImportViolation(specifier, file, options, resolveImport)) nodeReport(node, "showcase-import", "Showcase code and styles are development fixtures; runtime code must not import them.");

package/dist/cli.mjs

@@ -11,6 +11,8 @@ Usage: ads init [options]           Run inside your project
 
   init                 Set up ADS in the current project (requires package.json)
   check [directory]    Check tokens, ownership, imports, and showcase coverage
+  behaviors [dir]      Inspect behavior contracts and current verification evidence
+  verify [directory]   Run registered behavior checks (--unit and --check select)
   tokens [directory]   Inspect local token values and theme definitions
   assets [directory]   Generate standard web icons in .ds/assets from assets.iconSource
   lint-config [dir]    Generate .ds/oxlintrc.json with core and project plugins
@@ -25,6 +27,8 @@ Usage: ads init [options]           Run inside your project
   --port number        MCP/showcase only: loopback website port (default: automatic)
   --no-showcase        MCP only: disable the local website
   --mutations          MCP only: enable guarded ADS source editing
+  --unit id            Verify only: select one discovered behavior contract owner
+  --check id           Verify only: select a registered check (repeatable)
 
 External components and examples are imported using the ADS skills.
 No component library or example catalogue is bundled.
@@ -38,6 +42,8 @@ async function main(args) {
   let packageManager;
   let framework;
   let port;
+  let unit;
+  const selectedChecks = [];
   let showcase = true;
   let mutations = false;
   const positional = [];
@@ -46,6 +52,12 @@ async function main(args) {
     if (argument === "--json") json = true;
     else if (argument === "--no-showcase") showcase = false;
     else if (argument === "--mutations") mutations = true;
+    else if (argument === "--unit" || argument === "--check") {
+      const value = args[++index];
+      if (!value || value.startsWith("-")) throw new Error(`${argument} needs a discovered unit/check ID.`);
+      if (argument === "--unit") { if (unit) throw new Error("Specify one --unit."); unit = value; }
+      else selectedChecks.push(value);
+    }
     else if (argument === "--port") {
       const value = args[++index];
       if (port !== undefined || !/^\d+$/.test(value ?? "") || Number(value) > 65535) throw new Error("--port requires one port between 0 and 65535.");
@@ -72,6 +84,7 @@ async function main(args) {
   if (packageManager !== undefined && command !== "init") throw new Error("--package-manager is supported only by init.");
   if (framework !== undefined && command !== "init") throw new Error("--framework is supported only by init.");
   if (command === "init" && directory) throw new Error("Run ads init inside the project, without a directory argument.");
+  if ((unit || selectedChecks.length) && command !== "verify") throw new Error("--unit and --check are supported only by verify.");
   const target = path.resolve(directory ?? process.cwd());
   if (command === "mcp" || command === "showcase") {
     if (json) throw new Error("--json is not supported by mcp/showcase; mcp reserves stdout for JSON-RPC.");
@@ -82,6 +95,8 @@ async function main(args) {
   let result;
   if (command === "init") result = initProject(target, { toolPackage, packageManager, framework });
   else if (command === "check") result = checkProject(target);
+  else if (command === "behaviors") { const {behaviorStatus}=await import("./verification.mjs"); const {loadConfig}=await import("./config.mjs"); result=behaviorStatus(loadConfig(target)); }
+  else if (command === "verify") { const {createVerificationController}=await import("./verification.mjs"); const verification=createVerificationController(target); try {result=await verification.run({...(unit?{unit}:{}),...(selectedChecks.length?{checks:selectedChecks}:{})});} finally {await verification.close();} }
   else if (command === "tokens") result = inspectTokens(target);
   else if (command === "assets") result = await generateBrandAssets(target);
   else if (command === "lint-config") result = generateLintConfig(target);
@@ -90,6 +105,8 @@ async function main(args) {
   else if (command === "init") console.log(`Initialized ${target}\nFramework: ${result.framework}\nAdded ${result.toolDependency.name} (${result.toolDependency.spec}) as a development dependency.\nRun ${result.packageManager} install and ${result.packageManager} run build; the build refreshes lint configuration, runs ADS checks, and generates configured brand assets automatically.`);
   else if (command === "assets") console.log(result.skipped ? "No assets.iconSource configured; brand generation skipped." : `Generated ${result.files.length} brand assets in ${result.directory}.`);
   else if (command === "lint-config") console.log(`Generated ${result.file}\nProjects initialized with ads init refresh this automatically during lint:ds/build.`);
+  else if (command === "behaviors") console.log(JSON.stringify(result, null, 2));
+  else if (command === "verify") { for (const item of result.results) console.log(`${item.unit}#${item.check}: ${item.status} (${item.profile})`); }
   else if (command === "tokens") {
     for (const token of result.tokens) console.log(`${token.name}${token.type ? ` (${token.type})` : ""}: ${token.definitions.map((entry) => `${entry.scope}: ${entry.value}`).join("; ")}`);
   } else if (result.ok) console.log(`ADS check passed: ${target}`);

package/dist/config.mjs

@@ -17,7 +17,7 @@ export const defaultConfig = {
   boundaries: { styleWrites: [], componentVariables: [] },
   assets: { publicDirs: ["public/assets"], generatedPaths: ["dist", "dist-showcase", ".vite", ".ds"], generatedFiles: [], iconSource: null },
   oxlint: { plugins: [], rules: {}, overrides: [] },
-  mcp: { showcaseUrl: null, showcaseTitle: null, apps: [], previewWatch: null, previewManifest: null, mutationChecks: null },
+  mcp: { showcaseUrl: null, showcaseTitle: null, apps: [], previewWatch: null, previewManifest: null, mutationChecks: null, behaviorProfiles: {} },
 };
 
 export function isInside(parent, file) {
@@ -100,6 +100,18 @@ export function loadConfig(directory = process.cwd()) {
   }
   if (config.mcp.showcaseTitle !== null && (typeof config.mcp.showcaseTitle !== "string" || !config.mcp.showcaseTitle.trim() || config.mcp.showcaseTitle.length > 120)) throw new Error("mcp.showcaseTitle must be a non-empty title of at most 120 characters or null.");
   if (!Array.isArray(config.mcp.apps)) throw new Error("mcp.apps must be an array of built project previews.");
+  if (!config.mcp.behaviorProfiles || typeof config.mcp.behaviorProfiles !== "object" || Array.isArray(config.mcp.behaviorProfiles) || Object.keys(config.mcp.behaviorProfiles).length > 20) throw new Error("mcp.behaviorProfiles must be an object of up to 20 registered execution profiles.");
+  for (const [name, profile] of Object.entries(config.mcp.behaviorProfiles)) {
+    if (!/^[a-zA-Z0-9][\w.-]{0,79}$/.test(name) || !profile || typeof profile !== "object" || Array.isArray(profile)
+      || Object.keys(profile).some(key => !["command", "args", "timeoutMs", "runner", "framework", "mode"].includes(key))
+      || typeof profile.command !== "string" || !profile.command.trim() || profile.command.includes("\0")
+      || !Array.isArray(profile.args) || profile.args.some(arg => typeof arg !== "string" || arg.includes("\0"))
+      || !["protocol", "playwright"].includes(profile.runner ?? "protocol")
+      || profile.framework !== undefined && profile.framework !== config.framework
+      || profile.mode !== undefined && !["browser", "strict", "unit"].includes(profile.mode)
+      || profile.timeoutMs !== undefined && (!Number.isInteger(profile.timeoutMs) || profile.timeoutMs < 100 || profile.timeoutMs > 300000)) throw new Error(`Invalid behavior profile ${name}. Use literal executable/args, a protocol or Playwright runner, a matching framework and a bounded timeout. Profiles do not install dependencies or receive APIs from an MCP host.`);
+    if (profile.mode === "strict" && config.framework !== "react") throw new Error(`Behavior profile ${name}: React StrictMode requires framework react; use the configured framework's lifecycle tests instead.`);
+  }
   if (config.mcp.mutationChecks !== null && (!Array.isArray(config.mcp.mutationChecks) || config.mcp.mutationChecks.length > 12 || new Set(config.mcp.mutationChecks).size !== config.mcp.mutationChecks.length || config.mcp.mutationChecks.some(name => typeof name !== "string" || !/^[a-zA-Z0-9][\w:.-]*$/.test(name)))) throw new Error("mcp.mutationChecks must be null or up to 12 unique package script names.");
   if (config.mcp.previewManifest !== null) {
     const manifest = projectPath(root, config.mcp.previewManifest, "mcp.previewManifest");
@@ -136,10 +148,18 @@ export function isFixtureFile(file) {
 }
 
 /** File role, rather than folder location, keeps colocated preview code private. */
+export function isBehaviorFile(file) {
+  return /(?:^|[\\/])behavior\.json$|\.behavior\.json$/.test(file);
+}
+
+export function isTokenManifestFile(file) {
+  return /(?:^|[\\/])tokens\.json$|\.tokens\.json$/.test(file);
+}
+
 export function isDevelopmentFile(file, { dsRoot }) {
   if (!isInside(dsRoot, file)) return isTestFile(file);
   const relative = path.relative(dsRoot, file).replaceAll("\\", "/");
-  return isTestFile(file) || isScenarioFile(file) || isFixtureFile(file)
+  return isTestFile(file) || isScenarioFile(file) || isFixtureFile(file) || isBehaviorFile(file) || isTokenManifestFile(file)
     || /^(?:showcase|composition)\//.test(relative)
     || /(?:^|\/)(?:scenario|fixtures)(?:\/|$)/.test(relative)
     || /\.scenario(?:-adapter)?\.[cm]?[jt]sx?$/.test(relative);
@@ -154,7 +174,7 @@ export function sourceFiles(root) {
     if (ignored.has(entry.name) || entry.isSymbolicLink()) continue;
     const file = path.join(root, entry.name);
     if (entry.isDirectory()) files.push(...sourceFiles(file));
-    else if (entry.isFile() && /\.(css|html|[cm]?[jt]sx?)$/.test(entry.name)) files.push(file);
+    else if (entry.isFile() && (/\.(css|html|[cm]?[jt]sx?)$/.test(entry.name) || isBehaviorFile(entry.name) || isTokenManifestFile(entry.name))) files.push(file);
   }
   return files.sort();
 }

package/dist/css-values.mjs

@@ -0,0 +1,26 @@
+import valueParser from "postcss-value-parser";
+
+// CSS-language categories, independent of any project's token names or values.
+// https://www.w3.org/TR/css-values-4/#lengths
+const absoluteLengths = new Set(["px", "cm", "mm", "q", "in", "pt", "pc"]);
+const fontLengths = new Set(["em", "rem", "ex", "rex", "cap", "rcap", "ch", "rch", "ic", "ric", "lh", "rlh"]);
+const responsiveLength = /^(?:[sld]?v(?:w|h|i|b|min|max)|cq(?:w|h|i|b|min|max))$/;
+
+export function numericCssUnit(value) {
+  const parsed = valueParser.unit(value);
+  return parsed ? parsed.unit.toLowerCase() : null;
+}
+
+/** Skin lengths use tokens regardless of font metrics, physical units or notation.
+ * Responsive viewport/container relationships retain their structural treatment. */
+export function tokenLengthLiteral(value) {
+  const unit = numericCssUnit(value);
+  return absoluteLengths.has(unit) || fontLengths.has(unit);
+}
+
+/** The same CSS categories apply to length-valued foundation tokens. */
+export function dimensionValue(value) {
+  const unit = numericCssUnit(value);
+  return unit !== null && (absoluteLengths.has(unit) || fontLengths.has(unit)
+    || responsiveLength.test(unit) || unit === "%" || unit === "" && Number(value) === 0);
+}

package/dist/index.mjs

@@ -7,3 +7,5 @@ export { generateBrandAssets } from "./brand-assets.mjs";
 // same validated configuration and property boundary as the core checker.
 export { loadConfig } from "./config.mjs";
 export { importResolver, styleWriteViolation } from "./boundaries.mjs";
+export { inspectBehaviors } from "./behaviors.mjs";
+export { behaviorStatus, createVerificationController } from "./verification.mjs";

package/dist/init.mjs

@@ -183,7 +183,7 @@ export function initProject(directory = process.cwd(), { toolPackage, packageMan
     }
     updates.set(entryFile, current + "\n" + reviewExport);
   }
-  for (const section of ["components", "patterns", "composition"]) addMissing(path.join(dsRoot, section, ".gitkeep"), "");
+  for (const section of ["components", "patterns", "controllers", "composition"]) addMissing(path.join(dsRoot, section, ".gitkeep"), "");
   addMissing(path.join(dsRoot, "assets/brand/README.md"), readFileSync(path.join(starter, "design-system/assets/brand/README.md")));
   addMissing(path.join(dsRoot, "assets/fonts/.gitkeep"), "");
   const configFile = path.join(root, "ds.config.json");