@decantr/cli 3.0.0-next.0 → 3.0.0

package/README.md

@@ -22,7 +22,7 @@ Use `decantr setup` when you are unsure which path applies. It detects whether t
 Use `decantr scan` when you want a zero-commit Brownfield preview. It reads local files, detects framework/routes/styling/static-hosting/assistant-rule signals, previews typed Contract graph readiness in memory when a Decantr contract already exists, reports the contract capsule source-handle count and limit, prints a terminal report, and writes no `.decantr` files or report artifacts. Add `--json` when automation needs the `ScanReportV1` payload.
 Use `decantr new` for a greenfield workspace in a fresh directory. With a starter-kit blueprint or archetype it uses the runnable adapter and Decantr CSS; without certified vocabulary content it creates a contract-only workspace unless you explicitly pass `--adoption=decantr-css`.
 Use `decantr adopt` when you already have an app and want Decantr governance without adopting a blueprint. Brownfield attach is proposal-driven: Decantr inventories the app, writes an observed essence proposal, hydrates hosted execution packs when online, and only applies the contract when you explicitly accept or merge it.
-Use `decantr doctor` when the next step is unclear, `decantr task` before asking an LLM to modify a route, `decantr verify` after the edit, and `decantr ci` in required automation. Use `decantr graph` when you want the Decantr 3 typed Contract graph, typed graph diff summary, manifest, content-addressed snapshot history, and cache-friendly contract capsule written under `.decantr/graph`; the capsule includes a bounded SourceArtifact path index so agents can discover valid file-impact handles without reading the full snapshot, and `--capsule-source-limit <count>` can tune that index for large repos. Add `--route /feed --task "improve loading" --json` when you want the exact task-ranked route-scoped subgraph an agent should inspect before editing, `--node cmp:button --impact --json` when you need the graph-shaped blast radius for a component, token, rule, finding, or source artifact, or `--file src/app/page.tsx --impact --json` when the agent knows the source file it is about to change. Use `--snapshot-id <id>` to inspect a replayable history snapshot and `--compare-to <id> --include-diff-ops --json` to compare the selected/current graph against a prior snapshot. Use `decantr codify --from-audit --style-bridge` when you want project-owned UI patterns, local rules, and token/class bridge mappings such as button/card/shell/theme standards to appear in future task context and verification. Once accepted, that local law is the first Hybrid lane: the app still owns source and styling, but Decantr treats accepted local patterns, rules, and style bridge mappings as project authority.
+Use `decantr doctor` when the next step is unclear, `decantr task` before asking an LLM to modify a route, `decantr verify` after the edit, and `decantr ci` in required automation. Use `decantr graph` when you want the Decantr 3 typed Contract graph, typed graph diff summary, manifest, content-addressed snapshot history, and cache-friendly contract capsule written under `.decantr/graph`; the capsule includes a bounded SourceArtifact path index so agents can discover valid file-impact handles without reading the full snapshot, and `--capsule-source-limit <count>` can tune that index for large repos. Add `--route /feed --task "improve loading" --json` when you want the exact task-ranked route-scoped subgraph an agent should inspect before editing, `--node cmp:button --impact --json` when you need the graph-shaped blast radius for a component, token, rule, finding, or source artifact, or `--file src/app/page.tsx --impact --json` when the agent knows the source file it is about to change. Use `--snapshot-id <id>` to inspect a replayable history snapshot and `--compare-to <id> --include-diff-ops --json` to compare the selected/current graph against a prior snapshot. Use `decantr codify --from-audit --style-bridge` when you want project-owned UI patterns, optional `behavior_obligations`, local rules, and token/class bridge mappings such as button/card/shell/theme standards to appear in future task context and verification. Once accepted, that local law is the first Hybrid lane: the app still owns source and styling, but Decantr treats accepted local patterns, behavior obligations, rules, and style bridge mappings as project authority.
 In monorepos, app-scoped commands accept `--project <app-path>`. `setup` shows attach guidance before adoption and the day-two loop after adoption. Hosted pack hydration also follows the essence path: `decantr registry compile-packs apps/web/decantr.essence.json --write-context` writes into `apps/web/.decantr/context`. In contract-only/offline Brownfield, deferred hosted packs are optional context unless a present manifest references missing files.
 Use `decantr init`, `decantr analyze`, `decantr check`, and `decantr health` as advanced primitives when you need direct control over one step.
 
@@ -91,9 +91,9 @@ pnpm exec decantr codify --map-pattern hero --project apps/web
 pnpm exec decantr ci init --project apps/web
 ```
 
-Assistant rule integration is preview-first: `--assistant-bridge=preview` writes `.decantr/context/assistant-bridge.md`, `decantr rules preview` prints the bridge, and `--assistant-bridge=apply` or `decantr rules apply` mutates supported rule files with idempotent marked blocks. When `.decantr/graph/contract-capsule.json` exists, `decantr task` includes it in the read list and JSON payload so CLI-only agents can load the typed Contract capsule and its SourceArtifact path index before route-specific edits. When `.decantr/graph/graph.snapshot.json` exists, `decantr task --json` also includes `graph.routeContext`: the route node, scoped page/shell/pattern/component/token nodes, local law/style bridge nodes, open findings/evidence IDs, deterministic ranked nodes boosted by the task text, and the supporting edges. If git changed files resolve to SourceArtifact nodes, `decantr task --json` also includes `graph.changedFileContext` so an agent can see source-file blast radius before editing or repairing the current diff.
+Assistant rule integration is preview-first: `--assistant-bridge=preview` writes `.decantr/context/assistant-bridge.md`, `decantr rules preview` prints the bridge, and `--assistant-bridge=apply` or `decantr rules apply` mutates supported rule files with idempotent marked blocks. When `.decantr/graph/contract-capsule.json` exists, `decantr task` includes it in the read list and JSON payload so CLI-only agents can load the typed Contract capsule and its SourceArtifact path index before route-specific edits. When `.decantr/graph/graph.snapshot.json` exists, `decantr task --json` also includes `graph.routeContext`: the route node, scoped page/shell/pattern/component/token nodes, local law/style bridge nodes, behavior-obligation LocalRule nodes, open findings/evidence IDs, deterministic ranked nodes boosted by the task text, and the supporting edges. Accepted `.decantr/local-patterns.json` `behavior_obligations` also appear in `localLaw.patterns[].behaviorObligations` and `localLaw.behaviorObligations` so agents see project-owned dialog/form obligations before editing. If git changed files resolve to SourceArtifact nodes, `decantr task --json` also includes `graph.changedFileContext` so an agent can see source-file blast radius before editing or repairing the current diff.
 
-`decantr scan` is different from the mutating Brownfield primitives: it is look-don't-touch reconnaissance for fit, route/style evidence, GitHub Pages hints, typed Contract graph readiness, capsule source-handle bounds, and next-command guidance. For attached Essence V4 apps it derives the graph preview in memory, reports stale/missing `.decantr/graph` artifacts, and still writes nothing. `decantr analyze` writes `.decantr/doctrine-map.json`, a ranked source-precedence map across security/data, architecture, design-system, workflow/CI, feature/business, assistant-specific, stale, and unsafe-to-cite evidence. It also writes `.decantr/brownfield-intelligence.json`, `.decantr/theme-inventory.json`, and `.decantr/enrichment-backlog.md`. The proposal groups routes into observed semantic domains such as auth, RBAC, billing, reporting, facilities, settings, and public surfaces across Next App/Pages Router, React Router, Angular Router, SvelteKit, Vue Router, and Nuxt file routes. Existing styling systems such as Tailwind, Bootstrap, MUI, Chakra, plain CSS, and Decantr CSS are observed as evidence instead of replaced. Theme variants are observed in the theme inventory without changing Essence V4. `decantr adopt` writes the first typed Contract graph baseline before verification so Project Health, task context, and agents can anchor to graph artifacts immediately. `decantr codify --from-audit` proposes `.decantr/local-patterns.proposal.json` and `.decantr/rules.proposal.json` with Hybrid authority guidance, source-derived button/card/form/theme evidence, variant hints, and confidence tiers; `decantr codify --style-bridge` proposes `.decantr/style-bridge.proposal.json`, mapping Decantr intent to project-owned tokens/classes without requiring `@decantr/css`; `decantr codify --map-pattern <slug>` maps a hosted or bundled registry pattern into an advisory local-law proposal without changing source. After review, `decantr codify --accept` promotes whichever proposals exist. `decantr doctor` reports whether the app is contract-only, Hybrid local law, style bridge, Decantr CSS, or Hybrid composition. `decantr task` prints that authority block and warns before mixing runtimes or adding Decantr CSS to a non-Decantr-CSS app. `decantr suggest --from-code` surfaces accepted local patterns and style bridge mappings from the app root or selected `--project`, and `decantr ci` prints accepted local-rule findings plus style bridge status in text, markdown, and JSON reports. `decantr verify --brownfield --local-patterns` uses the Brownfield guard layer plus accepted local law to flag actionable missing doctrine coverage, unsafe context, missing assistant bridges, style drift, raw local-rule violations, and unsafe defaults without treating current database migrations as stale docs.
+`decantr scan` is different from the mutating Brownfield primitives: it is look-don't-touch reconnaissance for fit, route/style evidence, GitHub Pages hints, typed Contract graph readiness, capsule source-handle bounds, and next-command guidance. For attached Essence V4 apps it derives the graph preview in memory, reports stale/missing `.decantr/graph` artifacts, and still writes nothing. `decantr analyze` writes `.decantr/doctrine-map.json`, a ranked source-precedence map across security/data, architecture, design-system, workflow/CI, feature/business, assistant-specific, stale, and unsafe-to-cite evidence. It also writes `.decantr/brownfield-intelligence.json`, `.decantr/theme-inventory.json`, and `.decantr/enrichment-backlog.md`. The proposal groups routes into observed semantic domains such as auth, RBAC, billing, reporting, facilities, settings, and public surfaces across Next App/Pages Router, React Router, Angular Router, SvelteKit, Vue Router, and Nuxt file routes. Existing styling systems such as Tailwind, Bootstrap, MUI, Chakra, plain CSS, and Decantr CSS are observed as evidence instead of replaced. Theme variants are observed in the theme inventory without changing Essence V4. `decantr adopt` writes the first typed Contract graph baseline before verification so Project Health, task context, and agents can anchor to graph artifacts immediately. `decantr codify --from-audit` proposes `.decantr/local-patterns.proposal.json` and `.decantr/rules.proposal.json` with Hybrid authority guidance, source-derived button/card/form/theme evidence, variant hints, confidence tiers, and optional `behavior_obligations` for form controls and destructive confirmation dialogs when source evidence is strong; `decantr codify --style-bridge` proposes `.decantr/style-bridge.proposal.json`, mapping Decantr intent to project-owned tokens/classes without requiring `@decantr/css`; `decantr codify --map-pattern <slug>` maps a hosted or bundled registry pattern into an advisory local-law proposal without changing source. After review, `decantr codify --accept` promotes whichever proposals exist. `decantr doctor` reports whether the app is contract-only, Hybrid local law, style bridge, Decantr CSS, or Hybrid composition. `decantr task` prints that authority block and warns before mixing runtimes or adding Decantr CSS to a non-Decantr-CSS app. `decantr suggest --from-code` surfaces accepted local patterns and style bridge mappings from the app root or selected `--project`, and `decantr ci` prints accepted local-rule findings, behavior-obligation findings, plus style bridge status in text, markdown, and JSON reports. `decantr verify --brownfield --local-patterns` uses the Brownfield guard layer plus accepted local law to flag actionable missing doctrine coverage, unsafe context, missing assistant bridges, behavior-obligation drift, style drift, raw local-rule violations, and unsafe defaults without treating current database migrations as stale docs.
 
 ## What It Does
 
@@ -102,7 +102,7 @@ Assistant rule integration is preview-first: `--assistant-bridge=preview` writes
 - guides users through human workflow commands: setup, adopt, doctor, task, verify, ci, and codify
 - supports explicit workflow lanes: greenfield blueprint, greenfield contract-only, brownfield adoption, Hybrid local law, Hybrid style bridge, Hybrid Decantr CSS, and hybrid composition
 - generates execution-pack context files for AI coding assistants
-- generates typed Contract graph artifacts, replayable snapshot history, graph diffs, manifests, source-file impact context, style-bridge Token nodes, and `contract-capsule.json` for agent sessions
+- generates typed Contract graph artifacts, replayable snapshot history, graph diffs, manifests, source-file impact context, style-bridge Token nodes, behavior-obligation LocalRule nodes, and `contract-capsule.json` for agent sessions
 - audits projects against Decantr contracts
 - produces local Project Health reports, Evidence Bundles, workspace health, and a localhost Studio dashboard for end-user drift triage
 - audits local vocabulary repositories with Content Health reports for schema, reference, and quality coverage
@@ -181,7 +181,7 @@ decantr showcase verification --json
 
 `decantr ci` is the blessed non-mutating automation gate. It runs the Project Health surface with adoption-mode-aware local law checks and emits a schema-backed CI report. `decantr ci init` writes root GitHub workflows or portable generic snippets using the detected package manager and pinned local CLI command instead of `@latest`; if the root manifest has not pinned Decantr yet, it prints the exact install command first.
 
-`decantr health` remains the advanced project observability primitive. It composes the existing verifier audit, guard checks, brownfield route drift checks, runtime evidence, component reuse drift, accepted style bridge drift, typed Contract graph freshness, and execution-pack files into a `ProjectHealthReport` with a status, score, route summary, pack summary, findings, stable diagnostic codes, typed repair IDs, and AI-ready remediation prompts. The graph freshness slice emits `GRAPH001` / `regenerate-typed-graph` when an attached app has missing, stale, or non-derivable `.decantr/graph` artifacts. The component reuse slice emits `COMP001` / `import-existing-component` when production source locally redeclares a common primitive that already exists as an exported reusable component, and `COMP010` / `replace-raw-control-with-local-component` when production JSX renders raw controls such as `<button>` while the project already owns a reusable primitive. The style bridge slice emits `TOKEN010` / `replace-arbitrary-style-with-bridge-token` when production JSX, common class helpers, hardcoded inline color styles, or hardcoded visual values in CSS/module stylesheets bypass `.decantr/style-bridge.json` after it has been accepted as project-owned style authority. The baseline slice emits `VISUAL010` / `review-visual-baseline-drift` when `--since-baseline` detects changed screenshot hashes. When `.decantr/graph/graph.snapshot.json` exists, each finding is anchored to the most specific graph node Decantr can resolve, and JSON, markdown, text output, repair prompts, and Evidence Bundles carry that anchor. `decantr graph` also writes content-addressed history snapshots under `.decantr/graph/snapshots/` so repeated graph runs can be replayed across an AI edit sequence. When `.decantr/analysis.json` exists, `decantr graph` links observed routes/pages to implementation source artifacts and links exported reusable component declarations to their source files. When browser evidence writes `.decantr/evidence/visual-manifest.json`, `decantr graph` ingests it as local route/page Evidence nodes without uploading screenshots. When `.decantr/evidence/latest.json` exists, `decantr graph` can also materialize saved findings, evidence strings, graph anchors, repair IDs, and referenced repair/read target files as typed graph nodes and edges. When `.decantr/health-baseline-diff.json` exists, baseline changed files become file-level temporal evidence in the graph.
+`decantr health` remains the advanced project observability primitive. It composes the existing verifier audit, guard checks, brownfield route drift checks, runtime evidence, component reuse drift, accepted style bridge drift, accepted behavior-obligation checks, typed Contract graph freshness, and execution-pack files into a `ProjectHealthReport` with a status, score, route summary, pack summary, findings, stable diagnostic codes, typed repair IDs, and AI-ready remediation prompts. The graph freshness slice emits `GRAPH001` / `regenerate-typed-graph` when an attached app has missing, stale, or non-derivable `.decantr/graph` artifacts. The component reuse slice emits `COMP001` / `import-existing-component` when production source locally redeclares a common primitive that already exists as an exported reusable component, and `COMP010` / `replace-raw-control-with-local-component` when production JSX renders raw controls such as `<button>` while the project already owns a reusable primitive. The behavior-obligation slice emits `A11Y010`, `A11Y011`, `INT010`, `INT011`, `INT012`, `INT013`, and `COMP020` for high-confidence dialog/form regressions such as missing accessible names, missing label associations, missing visible destructive consequence copy, missing cancel affordances, missing submitting guards, implicit form button types, or bypassed project-owned interaction primitives. The style bridge slice emits `TOKEN010` / `replace-arbitrary-style-with-bridge-token` when production JSX, common class helpers, hardcoded inline color styles, or hardcoded visual values in CSS/module stylesheets bypass `.decantr/style-bridge.json` after it has been accepted as project-owned style authority. The baseline slice emits `VISUAL010` / `review-visual-baseline-drift` when `--since-baseline` detects changed screenshot hashes. When `.decantr/graph/graph.snapshot.json` exists, each finding is anchored to the most specific graph node Decantr can resolve, and JSON, markdown, text output, repair prompts, and Evidence Bundles carry that anchor. `decantr graph` also writes content-addressed history snapshots under `.decantr/graph/snapshots/` so repeated graph runs can be replayed across an AI edit sequence. When `.decantr/analysis.json` exists, `decantr graph` links observed routes/pages to implementation source artifacts and links exported reusable component declarations to their source files. When browser evidence writes `.decantr/evidence/visual-manifest.json`, `decantr graph` ingests it as local route/page Evidence nodes without uploading screenshots. When `.decantr/evidence/latest.json` exists, `decantr graph` can also materialize saved findings, evidence strings, graph anchors, repair IDs, and referenced repair/read target files as typed graph nodes and edges. When `.decantr/health-baseline-diff.json` exists, baseline changed files become file-level temporal evidence in the graph.
 
 ```bash
 decantr verify

package/dist/bin.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import "./chunk-BDY4JCFH.js";
+import "./chunk-GN63PIKK.js";
 import "./chunk-SIDKK73N.js";
-import "./chunk-GXC5IJQY.js";
-import "./chunk-WUIFEHWM.js";
-import "./chunk-MNZKOZW7.js";
+import "./chunk-B2PJDAMS.js";
+import "./chunk-4NDOHCYY.js";
+import "./chunk-7Z74ETDR.js";

package/dist/{chunk-WUIFEHWM.js → chunk-4NDOHCYY.js}

@@ -3,7 +3,7 @@ import {
   sendProjectHealthCiFailedTelemetry,
   sendProjectHealthPromptTelemetry,
   sendProjectHealthReportTelemetry
-} from "./chunk-MNZKOZW7.js";
+} from "./chunk-7Z74ETDR.js";
 
 // src/commands/health.ts
 import { execFileSync as execFileSync2 } from "child_process";
@@ -117,9 +117,9 @@ import { createHash } from "crypto";
 import { existsSync as existsSync4, mkdirSync as mkdirSync3, readFileSync as readFileSync4, writeFileSync as writeFileSync3 } from "fs";
 import { dirname as dirname2, isAbsolute as isAbsolute2, join as join4, relative as relative2 } from "path";
 import {
+  buildContractCapsuleFromSnapshot,
   buildGraphImpactContext,
   buildGraphRouteContext,
-  buildContractCapsuleFromSnapshot,
   buildGraphSnapshotFromEssence,
   diffGraphSnapshots,
   GRAPH_DIFF_SCHEMA_URL,
@@ -182,6 +182,129 @@ function readLocalPatternPack(projectRoot) {
 function readLocalRuleManifest(projectRoot) {
   return readJsonFile(localRulesPath(projectRoot));
 }
+function stringArray(value) {
+  return Array.isArray(value) ? value.filter((entry) => typeof entry === "string" && entry.trim().length > 0) : [];
+}
+function localBehaviorSeverity(value) {
+  return value === "info" || value === "warn" || value === "error" ? value : null;
+}
+function summarizeLocalPatternBehaviorObligations(pattern) {
+  const contract = pattern.behavior_obligations;
+  if (!contract || typeof contract !== "object" || Array.isArray(contract)) return null;
+  if (!Array.isArray(contract.obligations)) return null;
+  const patternId = typeof pattern.id === "string" && pattern.id.trim() ? pattern.id : "unknown";
+  const obligations = contract.obligations.map((obligation, index) => {
+    if (!obligation || typeof obligation !== "object" || Array.isArray(obligation)) {
+      return null;
+    }
+    const id = typeof obligation.id === "string" && obligation.id.trim() ? obligation.id.trim() : `obligation-${index + 1}`;
+    const label = typeof obligation.label === "string" && obligation.label.trim() ? obligation.label.trim() : id;
+    const evidence = typeof obligation.evidence === "string" && obligation.evidence.trim() ? obligation.evidence.trim() : null;
+    return {
+      id,
+      label,
+      severity: localBehaviorSeverity(obligation.severity),
+      evidence
+    };
+  }).filter(
+    (entry) => Boolean(entry)
+  );
+  if (obligations.length === 0) return null;
+  return {
+    patternId,
+    patternRole: typeof contract.pattern_role === "string" ? contract.pattern_role : typeof pattern.role === "string" ? pattern.role : null,
+    intent: typeof contract.intent === "string" && contract.intent.trim() ? contract.intent.trim() : null,
+    modalities: stringArray(contract.modalities),
+    states: stringArray(contract.states),
+    riskProfile: stringArray(contract.risk_profile),
+    obligations,
+    testHints: stringArray(contract.test_hints),
+    componentPaths: stringArray(pattern.componentPaths)
+  };
+}
+function formControlBehaviorObligations(evidence) {
+  if (evidence.formComponents.length === 0 && evidence.formSourceEvidence.length === 0) {
+    return void 0;
+  }
+  return {
+    intent: "Preserve accessible, explicit form behavior when AI edits inputs, labels, validation, or form actions.",
+    pattern_role: "form-control",
+    modalities: ["keyboard", "pointer", "screen-reader", "touch"],
+    states: ["empty", "focused", "valid", "invalid", "submitting", "disabled"],
+    risk_profile: ["label-loss", "accidental-submit", "validation-context-loss"],
+    obligations: [
+      {
+        id: "label-associated",
+        label: "Inputs, selects, and textareas keep an associated visible or programmatic label.",
+        severity: "warn",
+        evidence: "static"
+      },
+      {
+        id: "explicit-form-button-type",
+        label: 'Buttons inside forms declare type="button" or type="submit" explicitly.',
+        severity: "warn",
+        evidence: "static"
+      },
+      {
+        id: "project-form-primitive",
+        label: "Use project-owned form/control primitives when they exist.",
+        severity: "info",
+        evidence: "primitive"
+      }
+    ],
+    test_hints: [
+      "keyboard form path smoke test",
+      "label association assertion",
+      "non-submit action does not submit form"
+    ]
+  };
+}
+function confirmationDialogBehaviorObligations() {
+  return {
+    intent: "Confirm destructive account or data actions without accidental execution.",
+    pattern_role: "confirmation-dialog",
+    modalities: ["keyboard", "pointer", "screen-reader", "touch"],
+    states: ["closed", "opening", "open", "submitting", "error", "success"],
+    risk_profile: ["accidental-destruction", "focus-loss", "screen-reader-context-loss"],
+    obligations: [
+      {
+        id: "project-dialog-primitive",
+        label: "Use the project-owned Dialog or AlertDialog primitive instead of one-off overlays.",
+        severity: "warn",
+        evidence: "primitive"
+      },
+      {
+        id: "accessible-name",
+        label: "Dialog has an accessible name.",
+        severity: "error",
+        evidence: "static"
+      },
+      {
+        id: "visible-consequence",
+        label: "Destructive consequence is stated in visible text.",
+        severity: "warn",
+        evidence: "static"
+      },
+      {
+        id: "cancel-affordance",
+        label: "Dialog exposes a clear cancel/close affordance before the destructive action.",
+        severity: "warn",
+        evidence: "static"
+      },
+      {
+        id: "submitting-guard",
+        label: "Submitting state prevents accidental repeated destructive execution.",
+        severity: "info",
+        evidence: "static"
+      }
+    ],
+    test_hints: [
+      "keyboard interaction smoke test",
+      "focus return assertion",
+      "destructive action requires explicit confirmation"
+    ]
+  };
+}
 function createBrownfieldCodifyProposal(input) {
   const sourceFiles = input.fromAudit ? listSourceFiles(input.projectRoot, 800) : [];
   const evidence = summarizeSourceEvidence(input.projectRoot, sourceFiles);
@@ -326,6 +449,7 @@ function createBrownfieldCodifyProposal(input) {
             "Start by mapping field wrappers, labels, error states, and disabled states from source."
           ]
         },
+        behavior_obligations: formControlBehaviorObligations(evidence),
         evidence: evidence.formComponents.length ? evidence.formComponents : ["Add form field wrapper paths and validation examples."],
         forbiddenAlternatives: [
           "Unlabeled one-off inputs or validation states that do not match the app standard."
@@ -356,7 +480,39 @@ function createBrownfieldCodifyProposal(input) {
         forbiddenAlternatives: [
           "Component-local theme forks that bypass shared theme providers or tokens."
         ]
-      }
+      },
+      ...evidence.dialogComponents.length > 0 || evidence.dialogSourceEvidence.length > 0 ? [
+        {
+          id: "confirmation-dialog",
+          label: "Confirmation dialogs",
+          role: "Destructive confirmations, modal decisions, and interruptive dialog actions",
+          appliesTo: [
+            "destructive confirmations",
+            "account deletion",
+            "data removal",
+            "modal decisions"
+          ],
+          componentPaths: evidence.dialogComponents,
+          decide: "Define which Dialog/AlertDialog primitive, destructive Button variant, consequence copy, cancel affordance, and submitting guard the app owns.",
+          sourceEvidence: evidence.dialogSourceEvidence,
+          confidence: confidenceForEvidence({
+            componentCount: evidence.dialogComponents.length,
+            sourceEvidenceCount: evidence.dialogSourceEvidence.length
+          }),
+          enforcement: {
+            level: "warn",
+            status: "proposal",
+            notes: [
+              "Only enforce statically checkable obligations. Focus trapping and screen-reader behavior should stay in project tests unless source evidence is explicit."
+            ]
+          },
+          behavior_obligations: confirmationDialogBehaviorObligations(),
+          evidence: evidence.dialogComponents.length ? evidence.dialogComponents : evidence.dialogSourceEvidence.map((entry) => entry.file),
+          forbiddenAlternatives: [
+            "One-off overlays for destructive actions without reviewed dialog primitives."
+          ]
+        }
+      ] : []
     ],
     starterRules: [
       "Prefer project-owned wrappers for repeated primitives once they exist.",
@@ -597,6 +753,29 @@ function validateLocalLaw(projectRoot) {
           `Local pattern ${id} maps hosted registry guidance but has no project-owned component path yet.`
         );
       }
+      if (pattern.behavior_obligations && (typeof pattern.behavior_obligations !== "object" || Array.isArray(pattern.behavior_obligations))) {
+        warnings.push(
+          `Local pattern ${id || "unknown"} has behavior_obligations, but it is not an object.`
+        );
+      } else if (pattern.behavior_obligations && !Array.isArray(pattern.behavior_obligations.obligations)) {
+        warnings.push(
+          `Local pattern ${id || "unknown"} has behavior_obligations without an obligations array.`
+        );
+      } else if (pattern.behavior_obligations?.obligations) {
+        for (const [index, obligation] of pattern.behavior_obligations.obligations.entries()) {
+          if (!obligation || typeof obligation !== "object" || Array.isArray(obligation)) {
+            warnings.push(
+              `Local pattern ${id || "unknown"} has malformed behavior obligation at index ${index}.`
+            );
+            continue;
+          }
+          if (typeof obligation.id !== "string" || !obligation.id.trim()) {
+            warnings.push(
+              `Local pattern ${id || "unknown"} has a behavior obligation missing an id.`
+            );
+          }
+        }
+      }
     }
   }
   if (ruleManifest && !Array.isArray(ruleManifest.rules)) {
@@ -615,14 +794,20 @@ function validateLocalLaw(projectRoot) {
 function createLocalLawTaskSummary(projectRoot) {
   const patternPack = readLocalPatternPack(projectRoot);
   const ruleManifest = readLocalRuleManifest(projectRoot);
-  const patterns = (patternPack?.patterns ?? []).map((pattern) => ({
-    id: typeof pattern.id === "string" ? pattern.id : "unknown",
-    role: typeof pattern.role === "string" ? pattern.role : null,
-    componentPaths: Array.isArray(pattern.componentPaths) ? pattern.componentPaths.filter((entry) => typeof entry === "string") : [],
-    confidenceTier: typeof pattern.confidence === "object" && pattern.confidence !== null && typeof pattern.confidence.tier === "string" ? pattern.confidence.tier : null,
-    enforcementLevel: typeof pattern.enforcement === "object" && pattern.enforcement !== null && typeof pattern.enforcement.level === "string" ? pattern.enforcement.level : null,
-    hostedPatternRefs: Array.isArray(pattern.hostedPatternRefs) ? pattern.hostedPatternRefs.map((ref) => typeof ref?.slug === "string" ? ref.slug : null).filter((slug) => Boolean(slug)) : []
-  }));
+  const behaviorObligations = [];
+  const patterns = (patternPack?.patterns ?? []).map((pattern) => {
+    const behavior = summarizeLocalPatternBehaviorObligations(pattern);
+    if (behavior) behaviorObligations.push(behavior);
+    return {
+      id: typeof pattern.id === "string" ? pattern.id : "unknown",
+      role: typeof pattern.role === "string" ? pattern.role : null,
+      componentPaths: Array.isArray(pattern.componentPaths) ? pattern.componentPaths.filter((entry) => typeof entry === "string") : [],
+      confidenceTier: typeof pattern.confidence === "object" && pattern.confidence !== null && typeof pattern.confidence.tier === "string" ? pattern.confidence.tier : null,
+      enforcementLevel: typeof pattern.enforcement === "object" && pattern.enforcement !== null && typeof pattern.enforcement.level === "string" ? pattern.enforcement.level : null,
+      hostedPatternRefs: Array.isArray(pattern.hostedPatternRefs) ? pattern.hostedPatternRefs.map((ref) => typeof ref?.slug === "string" ? ref.slug : null).filter((slug) => Boolean(slug)) : [],
+      behaviorObligations: behavior
+    };
+  });
   const rules = (ruleManifest?.rules ?? []).map((rule) => ({
     id: rule.id,
     severity: rule.severity,
@@ -635,6 +820,7 @@ function createLocalLawTaskSummary(projectRoot) {
     patternCount: patterns.length,
     ruleCount: rules.length,
     patterns,
+    behaviorObligations,
     rules
   };
 }
@@ -732,6 +918,7 @@ function summarizeSourceEvidence(projectRoot, files) {
   const componentPaths = files.filter((file) => /(^|[/\\])components?([/\\]|$)|(^|[/\\])ui([/\\]|$)/i.test(file.relative)).map((file) => file.relative);
   const byName = (terms) => componentPaths.filter((file) => terms.some((term) => basename(file).toLowerCase().includes(term))).slice(0, 12);
   const themeComponents = componentPaths.filter((file) => /theme|provider|mode|appearance|tenant|brand/i.test(file)).slice(0, 12);
+  const dialogComponents = componentPaths.filter((file) => /dialog|modal|alert|confirm|sheet|drawer/i.test(file)).slice(0, 12);
   const shellComponents = files.filter((file) => /layout|shell|frame|app|root|nav|sidebar/i.test(basename(file.relative))).map((file) => file.relative).slice(0, 12);
   return {
     buttonComponents: byName(["button", "action"]),
@@ -776,6 +963,19 @@ function summarizeSourceEvidence(projectRoot, files) {
       "field",
       "select"
     ]),
+    dialogComponents,
+    dialogSourceEvidence: collectSourceEvidence(projectRoot, files, [
+      "dialog",
+      "alertdialog",
+      "modal",
+      "confirm",
+      "confirmation",
+      "delete",
+      "remove",
+      "destructive",
+      "irreversible",
+      "cannot be undone"
+    ]),
     themeSourceEvidence: collectSourceEvidence(projectRoot, files, [
       "theme",
       "dark",
@@ -988,13 +1188,13 @@ function readStyleBridge(projectRoot) {
 function readStyleBridgeProposal(projectRoot) {
   return readJsonFile2(styleBridgeProposalPath(projectRoot));
 }
-function stringArray(value) {
+function stringArray2(value) {
   return Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : [];
 }
 function readThemeInventory(projectRoot) {
   const inventory = readJsonFile2(join3(projectRoot, ".decantr", "theme-inventory.json"));
   return {
-    modes: stringArray(inventory?.modes),
+    modes: stringArray2(inventory?.modes),
     variantIds: Array.isArray(inventory?.variants) ? inventory.variants.map((variant) => variant.id).filter((id) => typeof id === "string") : [],
     darkModeDetected: typeof inventory?.darkModeDetected === "boolean" ? inventory.darkModeDetected : null
   };
@@ -1003,9 +1203,7 @@ function tokenHints(styling, terms) {
   return styling.cssVariables.filter((name) => terms.test(name)).slice(0, 12);
 }
 function readProjectPatternPack(projectRoot) {
-  return readLocalPatternPack(projectRoot) ?? readJsonFile2(
-    join3(projectRoot, ".decantr", "local-patterns.proposal.json")
-  );
+  return readLocalPatternPack(projectRoot) ?? readJsonFile2(join3(projectRoot, ".decantr", "local-patterns.proposal.json"));
 }
 function classHintsForPattern(projectRoot, ids) {
   const pack = readProjectPatternPack(projectRoot);
@@ -1029,7 +1227,9 @@ function sourceEvidence(projectRoot, ids) {
 function colorTokenNames(styling) {
   const names = new Set(Object.keys(styling.colors ?? {}));
   for (const variable of styling.cssVariables) {
-    if (/color|bg|background|surface|text|foreground|border|primary|secondary|accent|muted/i.test(variable)) {
+    if (/color|bg|background|surface|text|foreground|border|primary|secondary|accent|muted/i.test(
+      variable
+    )) {
       names.add(variable);
     }
   }
@@ -1038,7 +1238,9 @@ function colorTokenNames(styling) {
 function createStyleBridgeProposal(input) {
   const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
   const theme = readThemeInventory(input.projectRoot);
-  const routeCount = input.essence && typeof input.essence === "object" && "blueprint" in input.essence ? Object.keys(input.essence.blueprint?.routes ?? {}).length : 0;
+  const routeCount = input.essence && typeof input.essence === "object" && "blueprint" in input.essence ? Object.keys(
+    input.essence.blueprint?.routes ?? {}
+  ).length : 0;
   const target = input.essence && typeof input.essence === "object" && "meta" in input.essence ? String(input.essence.meta?.target ?? "") || null : null;
   const darkModeDetected = theme.darkModeDetected ?? input.styling.darkMode;
   const themeModes = theme.modes.length > 0 ? theme.modes : darkModeDetected ? ["base", "dark"] : ["base"];
@@ -1084,7 +1286,10 @@ function createStyleBridgeProposal(input) {
         label: "Surfaces and cards",
         decantrIntent: "surface background, card treatment, border, radius, depth, and hover state",
         projectAuthority: "Use the app card/surface primitives, tokens, and accepted local law.",
-        tokenHints: tokenHints(input.styling, /surface|card|panel|bg|background|border|shadow|radius/i),
+        tokenHints: tokenHints(
+          input.styling,
+          /surface|card|panel|bg|background|border|shadow|radius/i
+        ),
         classHints: classHintsForPattern(input.projectRoot, ["surface-card"]),
         sourceEvidence: sourceEvidence(input.projectRoot, ["surface-card"]),
         guardrails: [
@@ -1097,7 +1302,10 @@ function createStyleBridgeProposal(input) {
         label: "Actions and buttons",
         decantrIntent: "primary, secondary, tertiary, destructive, icon-only, loading, and disabled action states",
         projectAuthority: "Use the app button/action primitives and local variant names.",
-        tokenHints: tokenHints(input.styling, /primary|secondary|accent|danger|error|destructive|focus/i),
+        tokenHints: tokenHints(
+          input.styling,
+          /primary|secondary|accent|danger|error|destructive|focus/i
+        ),
         classHints: classHintsForPattern(input.projectRoot, ["button"]),
         sourceEvidence: sourceEvidence(input.projectRoot, ["button"]),
         guardrails: [
@@ -1209,7 +1417,9 @@ function styleBridgeMatches(projectRoot, query) {
   if (!projectRoot) return [];
   const bridge = readStyleBridge(projectRoot);
   if (!bridge) return [];
-  const terms = query.toLowerCase().split(/[^a-z0-9]+/).filter((term) => term.length > 1).flatMap((term) => term.endsWith("s") && term.length > 3 ? [term, term.slice(0, -1)] : [term]);
+  const terms = query.toLowerCase().split(/[^a-z0-9]+/).filter((term) => term.length > 1).flatMap(
+    (term) => term.endsWith("s") && term.length > 3 ? [term, term.slice(0, -1)] : [term]
+  );
   if (terms.length === 0) return [];
   return bridge.mappings.map((mapping) => {
     const haystack = [
@@ -1594,6 +1804,15 @@ function sourceArtifacts(projectRoot, componentReuseAudit = null) {
       hash: hashFile(rulesPath)
     });
   }
+  const patternsPath = localPatternsPath(projectRoot);
+  if (existsSync4(patternsPath)) {
+    sources.push({
+      id: "src:.decantr/local-patterns.json",
+      kind: "local-pattern-manifest",
+      path: ".decantr/local-patterns.json",
+      hash: hashFile(patternsPath)
+    });
+  }
   const bridgePath = styleBridgePath(projectRoot);
   if (existsSync4(bridgePath)) {
     sources.push({
@@ -1673,7 +1892,11 @@ function sourceArtifacts(projectRoot, componentReuseAudit = null) {
         }
       });
     }
-    const importedFile = resolveImportSourcePath(projectRoot, importingFile, importReference.source);
+    const importedFile = resolveImportSourcePath(
+      projectRoot,
+      importingFile,
+      importReference.source
+    );
     if (!importedFile) continue;
     const importedPath = join4(projectRoot, importedFile);
     if (!existsSync4(importedPath)) continue;
@@ -1865,6 +2088,63 @@ function augmentProjectGraph(snapshot, projectRoot, sources, componentReuseAudit
       });
     }
   }
+  const localPatterns = readLocalPatternPack(projectRoot);
+  if (localPatterns) {
+    const sourceId = "src:.decantr/local-patterns.json";
+    for (const pattern of localPatterns.patterns ?? []) {
+      const behavior = summarizeLocalPatternBehaviorObligations(pattern);
+      if (!behavior) continue;
+      const patternNodeId = `pat:${graphSlug(behavior.patternId, "pattern")}`;
+      for (const obligation of behavior.obligations) {
+        const ruleId = `rule:behavior:${graphSlug(behavior.patternId, "pattern")}:${graphSlug(
+          obligation.id,
+          "obligation"
+        )}`;
+        addNode(nodes, {
+          id: ruleId,
+          type: "LocalRule",
+          payload: {
+            id: ruleId.replace(/^rule:/, ""),
+            kind: "behavior-obligation",
+            patternId: behavior.patternId,
+            patternRole: behavior.patternRole,
+            intent: behavior.intent,
+            obligationId: obligation.id,
+            label: obligation.label,
+            severity: obligation.severity,
+            evidence: obligation.evidence,
+            modalities: behavior.modalities,
+            states: behavior.states,
+            riskProfile: behavior.riskProfile,
+            testHints: behavior.testHints,
+            componentPaths: behavior.componentPaths,
+            manifest: {
+              status: localPatterns.status,
+              source: localPatterns.source,
+              acceptedAt: localPatterns.acceptedAt
+            }
+          }
+        });
+        addEdge(edges, {
+          src: ruleId,
+          dst: snapshot.project_id,
+          relation: "LOCAL_RULE_APPLIES_TO"
+        });
+        if (nodes.has(patternNodeId)) {
+          addEdge(edges, {
+            src: ruleId,
+            dst: patternNodeId,
+            relation: "LOCAL_RULE_APPLIES_TO"
+          });
+        }
+        addEdge(edges, {
+          src: ruleId,
+          dst: sourceId,
+          relation: "NODE_DERIVED_FROM_SOURCE"
+        });
+      }
+    }
+  }
   const styleBridge = readStyleBridge(projectRoot);
   if (styleBridge) {
     const sourceId = "src:.decantr/style-bridge.json";
@@ -1998,7 +2278,11 @@ function augmentProjectGraph(snapshot, projectRoot, sources, componentReuseAudit
   for (const importReference of componentReuseAudit?.imports ?? []) {
     const importingFile = projectRelativePath(projectRoot, importReference.file);
     if (!importingFile || !nodes.has(`src:${importingFile}`)) continue;
-    const importedFile = resolveImportSourcePath(projectRoot, importingFile, importReference.source);
+    const importedFile = resolveImportSourcePath(
+      projectRoot,
+      importingFile,
+      importReference.source
+    );
     if (!importedFile || !nodes.has(`src:${importedFile}`)) continue;
     addEdge(edges, {
       src: `src:${importingFile}`,
@@ -2463,7 +2747,10 @@ function summaryPayload(artifacts, routeContext, impactContext, selected, compar
       evidence: selected.snapshot.summary.evidence
     } : void 0,
     comparison,
-    routeContext: routeContextPayload(routeContext ?? null, routeContext ? optionsRoute(routeContext) : void 0),
+    routeContext: routeContextPayload(
+      routeContext ?? null,
+      routeContext ? optionsRoute(routeContext) : void 0
+    ),
     impactContext: impactContextPayload(impactContext ?? null, impactSelection)
   };
 }
@@ -3008,7 +3295,7 @@ function sourceFromAuditFinding(finding) {
   if (category.includes("pack") || category.includes("review contract")) {
     return "pack";
   }
-  if (category.includes("interaction") || id.includes("interaction") || rule.includes("interaction")) {
+  if (category.includes("interaction") || category.includes("behavior") || id.includes("interaction") || id.includes("behavior") || rule.includes("interaction")) {
     return "interaction";
   }
   if (category.includes("style bridge") || id.includes("style-bridge") || rule.includes("style-bridge")) {
@@ -3030,6 +3317,7 @@ function normalizeHealthCategory(category, source) {
   if (source === "design-token" || lower.includes("design-token")) return "Design Token";
   if (source === "style-bridge" || lower.includes("style bridge")) return "Style Bridge";
   if (source === "graph") return "Typed Contract Graph";
+  if (lower.includes("behavior obligation")) return "Behavior Obligation";
   if (lower.includes("accessibility")) return "Accessibility";
   if (source === "runtime") return "Runtime";
   if (source === "browser") return "Visual Evidence";

package/dist/{chunk-MNZKOZW7.js → chunk-7Z74ETDR.js}

@@ -1559,7 +1559,10 @@ async function captureCliTelemetryEvent(input) {
   }
 }
 async function sendCliCommandTelemetry(input) {
-  const projectRoot = resolveCliTelemetryProjectRoot(input.projectRoot ?? process.cwd(), input.args);
+  const projectRoot = resolveCliTelemetryProjectRoot(
+    input.projectRoot ?? process.cwd(),
+    input.args
+  );
   const command = normalizeCommand(input.args[0]);
   if (!isOptedIn(projectRoot) || !command || command === "help" || command === "version" || isHelpOrVersionProbe(input.args)) {
     return;
@@ -2157,11 +2160,11 @@ ${CYAN}Telemetry enabled.${RESET} Decantr will send privacy-filtered CLI product
 }
 
 export {
+  scanStyling,
   loadBundledContentItem,
   loadBundledContentList,
   scanAmbientContext,
   scanRoutes,
-  scanStyling,
   createDoctrineMap,
   writeDoctrineMap,
   isOptedIn,

package/dist/{chunk-GXC5IJQY.js → chunk-B2PJDAMS.js}

@@ -1,7 +1,7 @@
 import {
   createProjectHealthReport,
   listWorkspaceAppCandidates
-} from "./chunk-WUIFEHWM.js";
+} from "./chunk-4NDOHCYY.js";
 
 // src/commands/workspace.ts
 import { execFileSync } from "child_process";