@event4u/agent-config 9.9.0 → 9.11.0

package/dist/agent-src/templates/scripts/work_engine/stack/detect.ts

@@ -17,17 +17,35 @@
  *
  * 1. `composer.json` lists `livewire/livewire` AND `livewire/flux` →
  *    `blade-livewire-flux`
- * 2. `package.json` lists `react` AND any of `@radix-ui/*`,
+ * 2. `composer.json` lists `filament/filament` → `filament` (before bare
+ *    Livewire: Filament pulls Livewire in transitively)
+ * 3. `composer.json` lists `livewire/livewire` → `blade-livewire`
+ * 4. `package.json` lists `react` AND any of `@radix-ui/*`,
  *    `shadcn-ui` or has a `components.json` (the shadcn marker file)
  *    → `react-shadcn`
- * 3. `package.json` lists `vue` (any major) → `vue`
- * 4. Otherwise → `plain`
+ * 5. `package.json` lists `react` → `react`
+ * 6. `package.json` lists `vue` (any major) → `vue`
+ * 7. Either manifest names a recognised-but-unmodelled framework
+ *    (Svelte, Angular, Nuxt, Astro, Solid, Qwik, Inertia) → `unknown`
+ * 8. Otherwise → `plain`
+ *
+ * Rules 3, 5 and 7 exist because the earlier table sent three common
+ * shapes into `plain`: Laravel+Livewire without Flux failed rule 1's `&&`,
+ * React without Radix failed rule 4, and every unmodelled framework was
+ * indistinguishable from a genuinely plain project. `plain` now means "no
+ * frontend markers"; `unknown` means "a framework we do not model", and
+ * dispatch refuses on it rather than handing over generic tooling silently.
  *
  * Detection is filesystem-cheap: at most three small JSON reads per
  * project root. Errors (missing file, malformed JSON, missing `require`
  * section) downgrade to `plain` rather than raising — a wrong stack
  * label is recoverable (audit catches it, user can override), but a
  * crash mid-dispatch is not.
+ *
+ * Root manifests only, by design: a monorepo caller passes the workspace
+ * root that carries the manifest it cares about. Note the consequence —
+ * a caller that always passes the repository root gets `plain` for a
+ * monorepo, so the caller owns scope selection, not the detector.
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
@@ -43,18 +61,59 @@ import * as path from 'node:path';
  */
 export const KNOWN_STACKS: ReadonlySet<string> = new Set([
     'blade-livewire-flux',
+    'blade-livewire',
+    'filament',
     'react-shadcn',
+    'react',
     'vue',
     'plain',
+    'unknown',
 ]);
 
-/** Fallback when no manifest signal matches. */
+/**
+ * Label for a project with no frontend markers at all.
+ *
+ * `plain` used to carry two meanings — "genuinely a plain HTML/Tailwind
+ * project" and "detection failed, here is generic tooling anyway" — which made
+ * a loud failure impossible without punishing real plain projects. The second
+ * meaning is now {@link UNSUPPORTED_STACK}.
+ */
 export const DEFAULT_STACK = 'plain';
 
+/**
+ * Label for a project whose frontend IS recognisable but is not modelled.
+ *
+ * Dispatch refuses on this label instead of degrading to generic tooling: a
+ * Filament or Svelte project silently routed to a Tailwind-only bundle is
+ * user-hostile precisely because the output looks like it worked.
+ */
+export const UNSUPPORTED_STACK = 'unknown';
+
 const _SHADCN_RADIX_PREFIX = '@radix-ui/';
 const _SHADCN_PACKAGE_NAMES: ReadonlySet<string> = new Set(['shadcn-ui', 'shadcn']);
 const _FLUX_PACKAGE = 'livewire/flux';
 const _LIVEWIRE_PACKAGE = 'livewire/livewire';
+const _FILAMENT_PACKAGE = 'filament/filament';
+
+/**
+ * Frontend markers this package recognises but does not model.
+ *
+ * One of these present means detection **succeeded** at recognising a
+ * framework and the package simply has no lane for it — the `unknown` case,
+ * not the `plain` case. Keep the list short and factual; a marker leaves it
+ * only when a real lane exists.
+ */
+const _UNMODELLED_MARKERS: ReadonlyArray<string> = [
+    'svelte',
+    '@angular/core',
+    'nuxt',
+    'astro',
+    'solid-js',
+    '@builder.io/qwik',
+    '@inertiajs/vue3',
+    '@inertiajs/react',
+    'inertiajs/inertia-laravel',
+];
 
 /**
  * A heterogeneous JSON object, mirroring a Python `dict[str, object]`.
@@ -109,14 +168,51 @@ export function detect_stack(project_root: string): StackResult {
         return new StackResult({ frontend: 'blade-livewire-flux', mtime });
     }
 
+    // Filament before bare Livewire: it pulls Livewire in transitively, so a
+    // Filament project would otherwise be labelled by its dependency rather
+    // than by the framework the developer actually works in.
+    if (_has_package(composer, ['require', 'require-dev'], _FILAMENT_PACKAGE)) {
+        return new StackResult({ frontend: 'filament', mtime });
+    }
+
+    // Livewire WITHOUT Flux is the common Laravel frontend, not an unknown
+    // one. It used to fail the `&&` above and land in `plain`.
+    if (_has_package(composer, ['require', 'require-dev'], _LIVEWIRE_PACKAGE)) {
+        return new StackResult({ frontend: 'blade-livewire', mtime });
+    }
+
     if (_is_react_shadcn(pkg, components_json)) {
         return new StackResult({ frontend: 'react-shadcn', mtime });
     }
 
+    // React without Radix/shadcn is a served stack, not an unknown one.
+    if (_has_package(pkg, _PKG_DEP_KEYS, 'react')) {
+        return new StackResult({ frontend: 'react', mtime });
+    }
+
     if (_has_vue(pkg)) {
         return new StackResult({ frontend: 'vue', mtime });
     }
 
+    // A recognised-but-unmodelled framework is NOT `plain`. Refusing here is
+    // the point: `plain` means "no frontend markers", and conflating the two
+    // is what let a Svelte or Inertia project receive Tailwind-only tooling
+    // and no warning.
+    if (_has_unmodelled_marker(composer, pkg)) {
+        return new StackResult({ frontend: UNSUPPORTED_STACK, mtime });
+    }
+
+    // Monorepo: no manifest at the root, but one sits in a workspace directory.
+    // That is a wrong-scope call, not a plain project — the caller owns scope
+    // selection, so say so instead of labelling the whole repo `plain` and
+    // dispatching generic tooling at it.
+    //
+    // A repo with no manifest ANYWHERE stays `plain`: that is greenfield, and
+    // the scaffold path depends on it.
+    if (mtime === 0.0 && _has_nested_manifest(project_root)) {
+        return new StackResult({ frontend: UNSUPPORTED_STACK, mtime });
+    }
+
     return new StackResult({ frontend: DEFAULT_STACK, mtime });
 }
 
@@ -185,6 +281,61 @@ function _all_dependencies(manifest: Manifest, ...keys: string[]): Manifest {
     return merged;
 }
 
+/** Dependency sections a `package.json` can carry. */
+const _PKG_DEP_KEYS: ReadonlyArray<string> = [
+    'dependencies',
+    'devDependencies',
+    'peerDependencies',
+    'optionalDependencies',
+];
+
+/** True when `name` appears in any of `manifest`'s named dependency sections. */
+function _has_package(
+    manifest: Manifest,
+    sections: ReadonlyArray<string>,
+    name: string,
+): boolean {
+    return name in _all_dependencies(manifest, ...sections);
+}
+
+/** Workspace directories a monorepo conventionally puts its packages in. */
+const _WORKSPACE_DIRS: ReadonlyArray<string> = ['packages', 'apps', 'services', 'libs'];
+
+/**
+ * True when no root manifest exists but a workspace directory holds one.
+ *
+ * Deliberately shallow — one `readdir` per conventional workspace directory,
+ * one `stat` per child. It answers "was this called at the wrong scope?", not
+ * "where is the real project", which stays the caller's job.
+ */
+function _has_nested_manifest(project_root: string): boolean {
+    for (const dir of _WORKSPACE_DIRS) {
+        const base = path.join(project_root, dir);
+        let entries: string[];
+        try {
+            entries = fs.readdirSync(base);
+        } catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (
+                _is_file(path.join(base, entry, 'composer.json')) ||
+                _is_file(path.join(base, entry, 'package.json'))
+            ) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+
+/** True when either manifest names a framework we recognise but do not model. */
+function _has_unmodelled_marker(composer: Manifest, pkg: Manifest): boolean {
+    const composer_deps = _all_dependencies(composer, 'require', 'require-dev');
+    const pkg_deps = _all_dependencies(pkg, ..._PKG_DEP_KEYS);
+    return _UNMODELLED_MARKERS.some((marker) => marker in composer_deps || marker in pkg_deps);
+}
+
 function _is_blade_livewire_flux(composer: Manifest): boolean {
     const deps = _all_dependencies(composer, 'require', 'require-dev');
     return _LIVEWIRE_PACKAGE in deps && _FLUX_PACKAGE in deps;

package/dist/agent-src/templates/scripts/work_engine/state.ts

@@ -629,10 +629,12 @@ function _validate_app_spec(app_spec: JsonValue): void {
  * agent-directive that populates it. An empty dict is the in-progress
  * shape after the skill returns but before the brief lands; the gate
  * treats it the same as `null`. Once populated, `design_confirmed`
- * (when present) must be a bool. Other keys (`layout`, `components`,
- * `states`, `microcopy`, `a11y`, `reused_from_audit`) are
- * validated by the design handler against the skill contract — the
- * schema only enforces shape, not content.
+ * (when present) must be a bool, and `states` (when present and not
+ * `null`) must be an object — the design gate's per-state loop is
+ * object-guarded, so a string or list would bypass all five checks.
+ * The remaining keys (`layout`, `components`, `microcopy`, `a11y`,
+ * `reused_from_audit`) are validated by the design handler against the
+ * skill contract — the schema only enforces shape, not content.
  */
 function _validate_ui_design(ui_design: JsonValue): void {
     if (ui_design === null) {
@@ -652,6 +654,21 @@ function _validate_ui_design(ui_design: JsonValue): void {
             'state.ui_design.design_confirmed must be a boolean when present',
         );
     }
+    // `states` is shape-checked here, not left to the handler. The design
+    // gate's per-state loop was guarded on "is this an object", so a string or
+    // list silently skipped all five required-state checks — the gate passed
+    // while covering no state at all. Rejecting the wrong shape at the schema
+    // boundary means the loop can no longer be bypassed by type.
+    if (
+        'states' in ui_design &&
+        ui_design['states'] !== null &&
+        !_isDict(ui_design['states'])
+    ) {
+        throw new SchemaError(
+            'state.ui_design.states must be a JSON object (one key per ' +
+                `required state) or null; got ${pyTypeName(ui_design['states'])}`,
+        );
+    }
 }
 
 /**

package/dist/agent-src/user-types/README.md

@@ -21,7 +21,7 @@ The two axes compose orthogonally:
 ```
 
 QA methodology applied through a truck-driver end-user lens. The
-split is locked in [`../../docs/contracts/adr-user-types-axis.md`](../../docs/contracts/adr-user-types-axis.md).
+split is locked in [`../docs/contracts/adr-user-types-axis.md`](../../docs/contracts/adr-user-types-axis.md).
 
 ## What a user-type is — and is NOT
 
@@ -37,13 +37,13 @@ split is locked in [`../../docs/contracts/adr-user-types-axis.md`](../../docs/co
   encodes this floor.
 - **Is NOT**: an install-time filter. The vocabulary overlaps with
   the install-time `user-types/` axis at the package root (see
-  [`../../docs/contracts/adr-install-user-type-axis.md`](../../docs/contracts/adr-install-user-type-axis.md)),
+  [`../docs/contracts/adr-install-user-type-axis.md`](../../docs/contracts/adr-install-user-type-axis.md)),
   but the two live in different directories and consume different
   config keys. Same word, different layer — by design.
 
 ## Schema
 
-Locked in [`../../docs/contracts/user-type-schema.md`](../../docs/contracts/user-type-schema.md).
+Locked in [`../docs/contracts/user-type-schema.md`](../../docs/contracts/user-type-schema.md).
 
 - **Spine** — 7 sections (Focus · Daily Workflow · Vocabulary ·
   Operational Constraints · Unique Questions · Ticket Red Flags ·
@@ -88,7 +88,7 @@ ticket-requirement signals.
 
 CLI-only in v1 — skills do NOT declare a default `user-types:`
 frontmatter key. The migration path to v2 (skill-level default key)
-is documented in [`../../docs/contracts/adr-user-types-axis.md § Consequences`](../../docs/contracts/adr-user-types-axis.md).
+is documented in [`../docs/contracts/adr-user-types-axis.md § Consequences`](../docs/contracts/adr-user-types-axis.md).
 
 ```
 /refine-ticket --user-type=truck-driver PROJ-123
@@ -113,12 +113,12 @@ review proceeds without simulation.
 No existing persona moves into this directory. The three seeds
 shipped here (`galabau-field-crew`, `metalworking-shop`,
 `truck-driver`) were born as user-types. Existing personas stay as
-personas. See [`../../docs/contracts/adr-user-types-axis.md § Migration`](../../docs/contracts/adr-user-types-axis.md).
+personas. See [`../docs/contracts/adr-user-types-axis.md § Migration`](../docs/contracts/adr-user-types-axis.md).
 
 ## Related
 
-- [`../../docs/contracts/user-type-schema.md`](../../docs/contracts/user-type-schema.md) — locked schema
-- [`../../docs/contracts/adr-user-types-axis.md`](../../docs/contracts/adr-user-types-axis.md) — the axis split decision
-- [`../../docs/contracts/adr-install-user-type-axis.md`](../../docs/contracts/adr-install-user-type-axis.md) — install-time `user_type` axis (distinct layer)
+- [`../docs/contracts/user-type-schema.md`](../../docs/contracts/user-type-schema.md) — locked schema
+- [`../docs/contracts/adr-user-types-axis.md`](../../docs/contracts/adr-user-types-axis.md) — the axis split decision
+- [`../docs/contracts/adr-install-user-type-axis.md`](../../docs/contracts/adr-install-user-type-axis.md) — install-time `user_type` axis (distinct layer)
 - [`../personas/README.md`](../personas/README.md) — sister axis (methodology vs end-user)
 - [`../rules/artifact-drafting-protocol.md`](../rules/artifact-drafting-protocol.md) — mandatory per new user-type

package/dist/agent-src/user-types/galabau-field-crew.md

@@ -10,67 +10,68 @@ source: project
 
 ## Focus
 
-Two- to four-person crew on a landscape / garden-build site —
-paver-laying, retaining walls, planting, irrigation. Phone or
-rugged tablet in a pouch, gloves on, lifting something heavy every
-fifteen minutes. Workday shaped by weather, delivery slots, and
-customer arriving unannounced for "just one more thing". No
-reliable signal on half the sites. Every customer-requested change
-is either billable later or silently swallowed; documentation at
-the moment of change is the only way that decision survives.
-
-Review lens only, never operational instruction source. No
-paver-laying procedure, no soil-prep chemistry, no structural
-advice on retaining walls.
+This lens simulates the two- to four-person crew on a landscape /
+garden-build site — paver-laying, retaining walls, planting,
+irrigation. Phone or rugged tablet in a pouch, gloves on, lifting
+something heavy every fifteen minutes. The workday is shaped by
+weather, delivery slots, and the customer arriving unannounced to
+ask for "just one more thing". No reliable signal on half the sites.
+Every change a customer asks for is either billable later or
+silently swallowed; documentation at the moment of the change is the
+only way that decision survives.
+
+This lens is a **review lens only**, never an operational
+instruction source. No paver-laying procedure, no soil-prep
+chemistry, no structural advice on retaining walls.
 
 ## Daily Workflow
 
 - 06:30 — depot pickup, materials loaded, route confirmed; lead
-  reads day plan once, on phone, gloves off.
-- 07:30–11:30 — execution on site; phone back in pouch. UI reads
-  happen at coffee breaks or when customer interrupts.
+  reads the day plan once, on phone, with gloves off.
+- 07:30–11:30 — execution on site; phone goes back in pouch. UI
+  reads happen at coffee breaks or when the customer interrupts.
 - 11:30 — billable-change moment: customer asks for an extra step,
-  crew lead captures it as timestamped photo + short note +
-  ideally signature, **before** next task starts.
+  crew lead must capture it as a timestamped photo + short note +
+  ideally a signature, **before** the next task starts.
 - 15:30 — end-of-day proof: photo of finished section, geotagged,
   uploaded if signal exists, queued offline if not.
-- 17:00 — depot return; office reconciles day from photos +
+- 17:00 — depot return; office reconciles the day from photos +
   notes, not from memory.
 
 ## Vocabulary
 
-- **Aufmass** — measured-on-site quantity that becomes invoice
+- **Aufmass** — measured-on-site quantity that becomes the invoice
   basis; never substitute with "estimate" or "measurement".
 - **Nachtrag** — billable change-request added to a running job;
   losing one = losing money, not just data.
 - **Sauberkeitsschicht** — gravel layer under pavers; plain-German,
   not "base course".
-- **Plain-German over engineer-German.** Crew is bilingual (often
-  DE / PL / TR); noun must be the one on the delivery slip, not
-  the one in the BOQ.
+- **Plain-German over engineer-German.** Crew is bilingual
+  (often DE / PL / TR); the noun has to be the one on the delivery
+  slip, not the one in the BOQ.
 
 ## Operational Constraints
 
 - **No signal on half the sites.** Every write must queue and sync;
-  every read must work from cache. Conflict resolution on sync is
-  a ticket requirement, not a nice-to-have.
+  every read must work from cache. Conflict resolution on sync is a
+  ticket requirement, not a nice-to-have.
 - **Capacitive touch fails with wet or dirty gloves.** Primary
   flows survive with stylus, knuckle, or large-target taps. No
   pinch-zoom on the critical path.
-- **Photo is the proof, not the form.** A billable-change flow
-  needing three text fields before camera opens loses changes
-  silently — crew defers, then forgets.
-- **Screen washout in direct sun.** High-contrast mode on by
+- **Photo is the proof, not the form.** A billable-change flow that
+  needs three text fields before the camera opens loses changes
+  silently — the crew defers, then forgets.
+- **Screen washout in direct sun.** High-contrast mode is on by
   default for outdoor flows, never opt-in via settings.
 - **Rugged hardware, slow CPU.** Animations and skeleton loaders
-  burn battery; crew runs 10+ hours per charge on the device.
+  burn battery; the crew runs 10+ hours per charge on the device.
 
 ## Unique Questions
 
 - Does this flow survive a 4-hour offline window plus a sync with
   conflicting edits from the office?
-- Can a gloved hand complete the primary action in one tap from
-  the home screen without typing?
+- Can a gloved hand complete the primary action in one tap from the
+  home screen without typing?
 - Is there a photo-first path for capturing a billable change, or
   does the form block the camera?
 - Is the noun on screen the one written on the delivery slip, in
@@ -96,5 +97,5 @@ advice on retaining walls.
   signal (gloves, signal-loss, Nachtrag, Aufmass).
 - **No engineer-vocabulary substitution.** Renaming Nachtrag to
   "change request" in the UI breaks the billing chain.
-- **No photo-after-form flows.** Photo must be reachable in one
-  tap from the moment customer asks for the change.
+- **No photo-after-form flows.** Photo must be reachable in one tap
+  from the moment the customer asks for the change.

package/dist/agent-src/user-types/metalworking-shop.md

@@ -10,47 +10,48 @@ source: project
 
 ## Focus
 
-Small-to-mid metalworking shop — laser-cut, press-brake, weld,
-finish. Two surfaces: shop-floor tablets bolted near machines
-(loud, dirty, gloves) and an office desktop where quoting,
-scheduling, and material-cert tracking happen. Shop runs on **job
-travelers** (route cards) — one per job following the work through
-every station, getting stamped, ending in the shipping bay.
-Material certificates (heat numbers, mill certs) must trace from
-incoming bar stock through to the customer; losing the chain
-breaks the audit and can void the order.
-
-Review lens only, never operational instruction source. No
-welding-procedure spec, no electrical guidance, no
-structural-engineering advice. Trade execution stays with the
-certified welder, the EHS officer, and the engineer.
+This lens simulates a small-to-mid metalworking shop — laser-cut,
+press-brake, weld, finish. Two surfaces: shop-floor tablets bolted
+near the machines (loud, dirty, gloves) and an office desktop where
+quoting, scheduling, and material-cert tracking happen. The shop
+runs on **job travelers** (route cards) — one per job that follows
+the work through every station, gets stamped, and ends in the
+shipping bay. Material certificates (heat numbers, mill certs) must
+trace from incoming bar stock through to the customer; losing the
+chain breaks the audit and can void the order.
+
+This lens is a **review lens only**, never an operational
+instruction source. No welding-procedure spec, no electrical
+guidance, no structural-engineering advice. Trade execution stays
+with the certified welder, the EHS officer, and the engineer.
 
 ## Daily Workflow
 
-- 06:00 — shift starts, lead reviews day's travelers at office
-  desktop; priority shifts printed and pinned at the station.
+- 06:00 — shift starts, lead reviews the day's travelers at the
+  office desktop; priority shifts get printed and pinned at the
+  station.
 - 07:00–15:30 — execution per station; each station scans the
-  traveler QR or punches job number on tablet to start / pause /
-  complete time on that step.
-- Material check-in — incoming bar stock photographed with mill
-  cert; heat number bound to lot at moment of receipt, not later
-  from memory.
-- Safety sign-off — process steps requiring PPE or second-person
+  traveler QR or punches the job number on the tablet to start /
+  pause / complete time on that step.
+- Material check-in — incoming bar stock is photographed with the
+  mill cert; heat number bound to the lot at the moment of
+  receipt, not later from memory.
+- Safety sign-off — process steps requiring PPE or a second-person
   check (overhead crane, confined-space weld) cannot start until
-  sign-off is recorded on the tablet.
+  the sign-off is recorded on the tablet.
 - 15:30 — end-of-shift, lead reconciles open travelers, flags any
   step where the material-cert chain is broken.
 
 ## Vocabulary
 
-- **Job traveler / route card** — single canonical record that
+- **Job traveler / route card** — the single canonical record that
   moves with the part; never substitute with "ticket" or "task".
 - **Heat number / mill cert** — material identity; lose the link
   and the part is unsellable to a regulated customer.
 - **Sign-off** — recorded, named, timestamped; "approved" without
   a name fails audit.
-- **Setup vs run time** — booked separately on the machine;
-  merging them destroys costing accuracy.
+- **Setup vs run time** — booked separately on the machine; merging
+  them destroys costing accuracy.
 
 ## Operational Constraints
 
@@ -59,15 +60,15 @@ certified welder, the EHS officer, and the engineer.
   high contrast on by default.
 - **PPE prevents fine touch.** Welding gloves + safety glasses;
   drop-down pickers with > 6 options are a fail mode.
-- **Machine-time is money.** A flow adding 30 seconds per
-  job-step start, run 200 times/day, costs the shop one
-  machine-hour per shift.
-- **Material-cert chain is regulatory.** Every step touching
-  material must capture or carry the heat-number link; breaking
-  it silently is the worst failure mode.
+- **Machine-time is money.** A flow that adds 30 seconds per
+  job-step start, run 200 times/day, costs the shop one machine-
+  hour per shift.
+- **Material-cert chain is regulatory.** Every step that touches
+  material must capture or carry the heat-number link; breaking it
+  silently is the worst failure mode.
 - **Two-surface split.** Office desktop has Excel-grade density;
-  shop tablet has one-action-per-screen. Same flow cannot share
-  a layout.
+  shop tablet has one-action-per-screen. The same flow cannot
+  share a layout.
 
 ## Unique Questions
 

package/dist/agent-src/user-types/truck-driver.md

@@ -10,20 +10,22 @@ source: project
 
 ## Focus
 
-Commercial truck driver doing regional or long-haul delivery —
-typically single driver, phone or in-cab tablet on a mount, gloves
-optional but hands often busy with the wheel, paperwork, or a
-pallet jack. Day is gated by **hours-of-service (HOS)** — legally
-bounded driving and rest windows that cannot be ignored without
-losing the licence. Cargo moves through warehouses, loading docks,
-customer yards; signal drops in tunnels, basements, rural
-stretches. Proof-of-delivery (photo + signature + GPS + timestamp)
-is the moment the invoice becomes collectable.
-
-Review lens only, never operational instruction source. No driving
-advice, no HOS legal interpretation, no vehicle-maintenance
-guidance, no hazmat procedure. Trade execution stays with the
-dispatcher, the safety officer, and the certified driver-trainer.
+This lens simulates a commercial truck driver doing regional or
+long-haul delivery — typically a single driver, a phone or
+in-cab tablet on a mount, gloves optional but hands often busy
+with the wheel, paperwork, or a pallet jack. The day is gated by
+**hours-of-service (HOS)** — legally bounded driving and rest
+windows that cannot be ignored without losing the licence. Cargo
+moves through warehouses, loading docks, customer yards; signal
+drops in tunnels, basements, and rural stretches. Proof-of-delivery
+(photo + signature + GPS + timestamp) is the moment the invoice
+becomes collectable.
+
+This lens is a **review lens only**, never an operational
+instruction source. No driving advice, no HOS legal
+interpretation, no vehicle-maintenance guidance, no hazmat
+procedure. Trade execution stays with the dispatcher, the safety
+officer, and the certified driver-trainer.
 
 ## Daily Workflow
 
@@ -40,8 +42,8 @@ dispatcher, the safety officer, and the certified driver-trainer.
 - Per delivery — photo of the pallet, customer signature
   on-screen, GPS pin, timestamp; the four-tuple is the invoice
   trigger.
-- End of duty — HOS clock closes; if next break-window starts
-  mid-route, system warns **before** the driver commits.
+- End of duty — HOS clock closes; if the next break-window starts
+  mid-route, the system warns **before** the driver commits.
 
 ## Vocabulary
 
@@ -66,7 +68,7 @@ dispatcher, the safety officer, and the certified driver-trainer.
 - **Dead zones are routine.** Tunnels, basements, rural roads;
   every write queues, every read works from cache, and POD
   uploads sync with photo intact when signal returns.
-- **One-handed operation.** Other hand on the wheel, paperwork,
+- **One-handed operation.** Other hand is on the wheel, paperwork,
   or pallet jack; bottom-thumb-reachable primary actions, no
   precision drag.
 - **Cold / wet / glare.** Outdoor docks in winter; gloves on,
@@ -95,8 +97,8 @@ dispatcher, the safety officer, and the certified driver-trainer.
   than a constraint on what stops can be accepted.
 - Sync described as online-only; no queue + retry sketched for
   dead-zone delivery.
-- Dock-dwell capture left to manual tap with no arrival-trigger
-  fallback.
+- Dock-dwell capture left to manual tap with no
+  arrival-trigger fallback.
 
 ## Anti-Patterns
 
@@ -106,7 +108,7 @@ dispatcher, the safety officer, and the certified driver-trainer.
 - **No generic prose.** "Consider mobile usability" fails the
   Anti-Generic Quality Bar — every observation cites HOS, POD,
   dock-dwell, dead-zone, or hands-busy.
-- **No in-motion typing on the critical path.** A flow needing
+- **No in-motion typing on the critical path.** A flow that needs
   the driver to type while driving is rejected outright.
 - **No partial POD acceptance.** Missing any element of the
   four-tuple = unbilled; the flow must hold the action open