feat(tms): capability profiles with graduated enforcement and a deviation ledger

Phase 0 of the multi-mode expansion. Introduces the mode abstraction that
later modes (flatbed, bulk/tanker, drayage, final mile) build on, with zero
behavior change for existing organizations.

A "mode" is a preset of capability flags over three orthogonal axes — service
model, equipment class, execution party — rather than an enum on Shipment.
Customers run combinations (dedicated reefer, hazmat bulk, flatbed heavy haul),
so a single mode field would branch combinatorially by the second mode.

Three design commitments:

Graduated enforcement replaces boolean feature flags. Every capability rule
carries tenant.EnforcementLevel (Ignore/Warn/RequireReview/Block) instead of an
on/off switch. Defaults ship at Block so the system drives the process; an
organization dials a specific rule down without forking anything.

Warn and RequireReview results are recorded, not silenced. They become
Deviation records acknowledged with a reason, producing a queryable ledger of
where an organization departs from the standard process and why.

Resolved policy carries provenance. ShipmentUIPolicy now returns which profile
produced each rule, at what enforcement, whether it was overridden and why, plus
the rejected candidate profiles and the reason each lost. The UI can answer
"why is this required" inline instead of leaving users to guess.

Resolution mirrors detention.Policy exactly (priority, specificity score,
effective-date windows) rather than introducing a second algorithm. Capability
rules compose into the existing validationframework as conditioned rules; no new
validation engine. Field descriptors reuse customfield's FieldType,
ValidationRules, and UIAttributes.

errortypes.MultiError gains an Advisories slice, additive so HasErrors() and
every existing validator are untouched.

Enforcement migrated to profile-authoritative: cargo.maxShipmentWeight,
dispatch.moveRemoval, and the new cargo.temperatureRange. Hazmat segregation and
duplicate-BOL are represented in the resolved policy for explainability but keep
ShipmentControl enforcement; they migrate in Phase 1.

Zero behavior change is enforced two ways: when no profile resolves the
validator falls back to ShipmentControl, and the migration backfills one
org-default profile per organization with enforcement derived from that
organization's existing shipment_controls row. The new temperature rule
backfills at Ignore.

Client: capability helpers and the explainer live in packages/shared so both
apps consume them. ShipmentGeneralInformation is the first converted section —
temperature fields now render only when the profile declares TemperatureControl,
so the form gets shorter as modes are added rather than longer.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01559YzTFTKd3vV6eJWmSDzi

Author: claude

client/apps/web/src/routes/shipment/_components/shipment-general-information.tsx

@@ -1,6 +1,13 @@
 import { InputField } from "@/components/fields/input-field";
 import { NumberField } from "@/components/fields/number-field";
+import { CapabilityExplainer } from "@trenova/shared/components/capability-explainer";
 import { FormControl, FormGroup, FormSection } from "@trenova/shared/components/ui/form";
+import {
+  CAPABILITIES,
+  getProfile,
+  isFieldRequired,
+  isCapabilitySectionVisible,
+} from "@trenova/shared/lib/capability";
 import { ApiRequestError } from "@trenova/shared/lib/api";
 import { queries } from "@/lib/queries";
 import { apiService } from "@/services/api";
@@ -23,31 +30,47 @@ function Inner({ children }: { children: React.ReactNode }) {
 
 export default function ShipmentGeneralInformation() {
   const { control } = useFormContext<Shipment>();
+  const { data: shipmentUIPolicy } = useQuery({ ...queries.shipment.uiPolicy() });
+
+  const profile = getProfile(shipmentUIPolicy);
+  const showTemperature = isCapabilitySectionVisible(
+    profile,
+    CAPABILITIES.temperatureControl,
+  );
+  const temperatureRequired = isFieldRequired(profile, "temperatureMin");
 
   return (
     <Inner>
       <FormGroup cols={2}>
         <BOLField />
-        <FormControl>
-          <NumberField
-            control={control}
-            name="temperatureMin"
-            description="The minimum temperature for the shipment."
-            label="Temperature Min"
-            placeholder="Enter Temperature Min"
-            sideText="°F"
-          />
-        </FormControl>
-        <FormControl>
-          <NumberField
-            control={control}
-            name="temperatureMax"
-            label="Temperature Max"
-            description="The maximum temperature for the shipment."
-            placeholder="Enter Temperature Max"
-            sideText="°F"
-          />
-        </FormControl>
+        {showTemperature && (
+          <>
+            <FormControl>
+              <NumberField
+                control={control}
+                name="temperatureMin"
+                description="The minimum temperature for the shipment."
+                label="Temperature Min"
+                placeholder="Enter Temperature Min"
+                sideText="°F"
+                rules={{ required: temperatureRequired }}
+              />
+              <CapabilityExplainer profile={profile} field="temperatureMin" />
+            </FormControl>
+            <FormControl>
+              <NumberField
+                control={control}
+                name="temperatureMax"
+                label="Temperature Max"
+                description="The maximum temperature for the shipment."
+                placeholder="Enter Temperature Max"
+                sideText="°F"
+                rules={{ required: isFieldRequired(profile, "temperatureMax") }}
+              />
+              <CapabilityExplainer profile={profile} field="temperatureMax" />
+            </FormControl>
+          </>
+        )}
       </FormGroup>
     </Inner>
   );

client/packages/shared/src/components/capability-explainer.tsx

@@ -0,0 +1,87 @@
+import { InfoIcon } from "lucide-react";
+import {
+  describeMatch,
+  enforcementLabel,
+  enforcementTone,
+  rulesForField,
+} from "../lib/capability";
+import { cn } from "../lib/utils";
+import type { ResolvedCapabilityRule, ResolvedModeProfile } from "../types/shipment";
+import { Popover, PopoverContent, PopoverTrigger } from "./ui/popover";
+
+type CapabilityExplainerProps = {
+  profile: ResolvedModeProfile | null | undefined;
+  field: string;
+  className?: string;
+};
+
+export function CapabilityExplainer({ profile, field, className }: CapabilityExplainerProps) {
+  const rules = rulesForField(profile, field);
+
+  if (!profile || rules.length === 0) {
+    return null;
+  }
+
+  return (
+    <Popover>
+      <PopoverTrigger
+        type="button"
+        aria-label="Why does this field behave this way?"
+        className={cn(
+          "inline-flex size-4 items-center justify-center rounded-full text-muted-foreground",
+          "transition-colors hover:text-foreground focus-visible:outline-none",
+          "focus-visible:ring-2 focus-visible:ring-ring",
+          className,
+        )}
+      >
+        <InfoIcon className="size-3.5" />
+      </PopoverTrigger>
+      <PopoverContent align="start" className="w-96 p-0">
+        <div className="border-b border-border px-4 py-3">
+          <p className="text-xs font-medium">Why this field behaves this way</p>
+          <p className="mt-1 text-xs text-muted-foreground">
+            Resolved from the <span className="font-medium">{profile.profileName}</span> profile,
+            matched on {describeMatch(profile.candidates?.find((c) => c.selected)?.matchedOn)}.
+          </p>
+        </div>
+        <ul className="divide-y divide-border">
+          {rules.map((rule) => (
+            <RuleExplanation key={rule.key} rule={rule} />
+          ))}
+        </ul>
+      </PopoverContent>
+    </Popover>
+  );
+}
+
+function RuleExplanation({ rule }: { rule: ResolvedCapabilityRule }) {
+  const { provenance } = rule;
+
+  return (
+    <li className="px-4 py-3">
+      <div className="flex items-baseline justify-between gap-2">
+        <p className="text-xs font-medium">{rule.label}</p>
+        <span className={cn("text-[11px] font-medium", enforcementTone(rule.enforcement))}>
+          {enforcementLabel(rule.enforcement)}
+        </span>
+      </div>
+
+      <p className="mt-1.5 text-xs leading-relaxed text-muted-foreground">
+        {provenance.rationale}
+      </p>
+
+      {provenance.overridden && (
+        <div className="mt-2 rounded-md bg-muted px-2.5 py-2">
+          <p className="text-[11px] font-medium">
+            Your organization changed this from {enforcementLabel(provenance.defaultEnforcement)}
+          </p>
+          {provenance.overrideReason && (
+            <p className="mt-0.5 text-[11px] text-muted-foreground">
+              {provenance.overrideReason}
+            </p>
+          )}
+        </div>
+      )}
+    </li>
+  );
+}