@event4u/agent-config 9.8.0 → 9.10.0

package/dist/agent-src/templates/scripts/telemetry/engagement.ts

@@ -21,6 +21,10 @@
  *              (same PII-exclusion-by-construction shape as consulted).
  *       "outcomes":  ["blocked", "verification_failed", ...]  # optional
  *       "tokens_estimate": {"consulted_load": <int>}   # optional
+ *       "cross_source": [{"id": "d1", "type": "text-image", "asked": true}]  # optional
+ *              (road-to-feedback-9.2.0-followups 1.4): per-task ask-rate facet
+ *              for the cross-source-consistency rule. Structural only — id +
+ *              a closed type enum + a bool, no free-form fields.
  *     }
  */
 import * as fs from 'node:fs';
@@ -55,6 +59,18 @@ export const ALLOWED_OUTCOMES = [
 ] as const;
 export const MAX_OUTCOMES_PER_EVENT = ALLOWED_OUTCOMES.length;
 
+// cross_source facet (road-to-feedback-9.2.0-followups 1.4) — the
+// cross-source-consistency rule's discrepancy taxonomy (a)-(d) from
+// src/rules/cross-source-consistency.md.
+export const ALLOWED_CROSS_SOURCE_TYPES = [
+    'text-image',
+    'silent-needed',
+    'spec-code',
+    'intra-ticket',
+] as const;
+export const MAX_CROSS_SOURCE_PER_EVENT = 32;
+const _CROSS_SOURCE_KEYS = ['asked', 'id', 'type'] as const;
+
 // Phase 5 redaction validator — keep id fields from leaking paths,
 // free-text, or filenames.
 const _FORBIDDEN_ID_CHARS = ['/', '\\', '\n', '\r', '\t'] as const;
@@ -125,6 +141,13 @@ export function check_id_redaction(label: string, value: unknown): void {
     }
 }
 
+/** One surfaced cross-source discrepancy — structural only, no free text. */
+export interface CrossSourceEntry {
+    id: string;
+    type: string;
+    asked: boolean;
+}
+
 export interface EngagementEventInit {
     ts: string;
     task_id: string;
@@ -134,6 +157,7 @@ export interface EngagementEventInit {
     loaded?: Record<string, string[]> | null;
     outcomes?: string[] | null;
     tokens_estimate?: Record<string, number> | null;
+    cross_source?: CrossSourceEntry[] | null;
     schema_version?: number;
 }
 
@@ -146,6 +170,7 @@ export class EngagementEvent {
     loaded: Record<string, string[]> | null;
     outcomes: string[] | null;
     tokens_estimate: Record<string, number> | null;
+    cross_source: CrossSourceEntry[] | null;
     schema_version: number;
 
     constructor(init: EngagementEventInit) {
@@ -157,6 +182,7 @@ export class EngagementEvent {
         this.loaded = init.loaded ?? null;
         this.outcomes = init.outcomes ?? null;
         this.tokens_estimate = init.tokens_estimate ?? null;
+        this.cross_source = init.cross_source ?? null;
         this.schema_version = init.schema_version ?? SCHEMA_VERSION;
     }
 
@@ -195,6 +221,9 @@ export class EngagementEvent {
         if (this.outcomes !== null) {
             _validate_outcomes(this.outcomes);
         }
+        if (this.cross_source !== null) {
+            _validate_cross_source(this.cross_source);
+        }
         if (this.tokens_estimate !== null) {
             if (!_isPlainObject(this.tokens_estimate)) {
                 throw new EngagementSchemaError(
@@ -236,6 +265,13 @@ export class EngagementEvent {
         if (this.outcomes && this.outcomes.length > 0) {
             out['outcomes'] = [...this.outcomes];
         }
+        if (this.cross_source && this.cross_source.length > 0) {
+            out['cross_source'] = this.cross_source.map((e) => ({
+                id: e.id,
+                type: e.type,
+                asked: e.asked,
+            }));
+        }
         if (this.tokens_estimate && Object.keys(this.tokens_estimate).length > 0) {
             out['tokens_estimate'] = { ...this.tokens_estimate };
         }
@@ -317,6 +353,46 @@ function _validate_outcomes(payload: unknown): void {
     }
 }
 
+function _validate_cross_source(payload: unknown): void {
+    if (!Array.isArray(payload)) {
+        throw new EngagementSchemaError('cross_source must be a list of dict or None');
+    }
+    if (payload.length > MAX_CROSS_SOURCE_PER_EVENT) {
+        throw new EngagementSchemaError(
+            `cross_source exceeds ${MAX_CROSS_SOURCE_PER_EVENT} entries`,
+        );
+    }
+    for (const entry of payload) {
+        if (!_isPlainObject(entry)) {
+            throw new EngagementSchemaError('cross_source entries must be dict[str, ...]');
+        }
+        const keys = Object.keys(entry);
+        const extra = keys.filter((k) => !(_CROSS_SOURCE_KEYS as readonly string[]).includes(k));
+        if (extra.length > 0) {
+            throw new EngagementSchemaError(
+                `cross_source entry has unexpected key(s): ${extra.sort().join(', ')}; `
+                + `allowed keys: ${_CROSS_SOURCE_KEYS.join(', ')}`,
+            );
+        }
+        for (const required of _CROSS_SOURCE_KEYS) {
+            if (!(required in entry)) {
+                throw new EngagementSchemaError(`cross_source entry missing required key '${required}'`);
+            }
+        }
+        check_id_redaction('cross_source.id', entry['id']);
+        const type_val = entry['type'];
+        if (typeof type_val !== 'string' || !(ALLOWED_CROSS_SOURCE_TYPES as readonly string[]).includes(type_val)) {
+            throw new EngagementSchemaError(
+                `cross_source.type must be one of ${_reprTuple(ALLOWED_CROSS_SOURCE_TYPES)}, `
+                + `got ${_reprScalar(type_val)}`,
+            );
+        }
+        if (typeof entry['asked'] !== 'boolean') {
+            throw new EngagementSchemaError('cross_source.asked must be a bool');
+        }
+    }
+}
+
 export function parse_event(line: string): EngagementEvent {
     if (typeof line !== 'string' || !line.trim()) {
         throw new EngagementSchemaError('line must be a non-empty JSONL record');
@@ -342,6 +418,7 @@ export function parse_event(line: string): EngagementEvent {
             : _orEmptyDict(r['loaded']),
         outcomes: (r['outcomes'] as string[] | null | undefined) ?? null,
         tokens_estimate: (r['tokens_estimate'] as Record<string, number> | null | undefined) ?? null,
+        cross_source: (r['cross_source'] as CrossSourceEntry[] | null | undefined) ?? null,
         schema_version: r['schema_version'] === undefined
             ? SCHEMA_VERSION
             : (r['schema_version'] as number),

package/dist/agent-src/templates/scripts/telemetry_record.ts

@@ -21,6 +21,7 @@ import * as path from 'node:path';
 import { record_event } from './telemetry/boundary.js';
 import {
     ALLOWED_OUTCOMES,
+    type CrossSourceEntry,
     EngagementEvent,
     EngagementSchemaError,
     now_utc_iso,
@@ -58,6 +59,30 @@ function _reprStr(s: string): string {
     return `'${s}'`;
 }
 
+/** Turn `["d1:text-image:ask", ...]` into cross_source entries. Unknown
+ *  `type` values are left to schema validation (consistent with how
+ *  `_parse_kv_list` leaves unknown artefact kinds to the schema); only
+ *  the CLI-only `id:type:ask|warn` shape is checked here. */
+function _parse_cross_source_list(values: string[]): CrossSourceEntry[] {
+    const out: CrossSourceEntry[] = [];
+    for (const raw of values) {
+        const parts = raw.split(':');
+        if (parts.length !== 3 || !parts[0] || !parts[1] || !parts[2]) {
+            throw new SystemExitError(
+                `❌  --cross-source must be 'id:type:ask|warn', got ${_reprStr(raw)}`,
+            );
+        }
+        const [id, type, verdict] = parts as [string, string, string];
+        if (verdict !== 'ask' && verdict !== 'warn') {
+            throw new SystemExitError(
+                `❌  --cross-source verdict must be 'ask' or 'warn', got ${_reprStr(verdict)}`,
+            );
+        }
+        out.push({ id, type, asked: verdict === 'ask' });
+    }
+    return out;
+}
+
 interface RecordArgs {
     task_id: string;
     boundary: string;
@@ -65,6 +90,7 @@ interface RecordArgs {
     applied: string[] | null;
     loaded: string[] | null;
     outcome: string[] | null;
+    cross_source: string[] | null;
     ts: string;
     payload_file: string | null;
     stdin: boolean;
@@ -81,6 +107,9 @@ function _build_event_from_args(args: RecordArgs): EngagementEvent {
         applied: _parse_kv_list(args.applied ?? []),
         loaded: args.loaded && args.loaded.length > 0 ? _parse_kv_list(args.loaded) : null,
         outcomes: args.outcome && args.outcome.length > 0 ? [...args.outcome] : null,
+        cross_source: args.cross_source && args.cross_source.length > 0
+            ? _parse_cross_source_list(args.cross_source)
+            : null,
     });
 }
 
@@ -106,6 +135,7 @@ function _build_event_from_payload(raw: string): EngagementEvent {
         loaded: d['loaded'] === undefined || d['loaded'] === null ? null : _orEmpty(d['loaded']),
         outcomes: (d['outcomes'] as string[] | null | undefined) ?? null,
         tokens_estimate: (d['tokens_estimate'] as Record<string, number> | null | undefined) ?? null,
+        cross_source: (d['cross_source'] as CrossSourceEntry[] | null | undefined) ?? null,
     });
 }
 
@@ -126,6 +156,7 @@ function _parseArgs(argv: string[]): RecordArgs {
         applied: null,
         loaded: null,
         outcome: null,
+        cross_source: null,
         ts: '',
         payload_file: null,
         stdin: false,
@@ -170,7 +201,8 @@ function _parseArgs(argv: string[]): RecordArgs {
                 );
             }
             (a.outcome ??= []).push(v);
-        } else if (tok === '--ts') a.ts = next();
+        } else if (tok === '--cross-source') (a.cross_source ??= []).push(next());
+        else if (tok === '--ts') a.ts = next();
         else if (tok === '--payload-file') a.payload_file = next();
         else if (tok === '--stdin') a.stdin = true;
         else if (tok === '--settings') a.settings = next();

package/dist/agent-src/templates/scripts/tier_usage_report.ts

@@ -234,7 +234,7 @@ function _within_window(ts_bucket: string, window_days: number | null): boolean
     return ms >= Date.now() - window_days * 24 * 60 * 60 * 1000;
 }
 
-type BucketKey = string; // `${tier}${command}` — composite (tier, command) key.
+type BucketKey = string; // `${tier}\0${command}` — composite (tier, command) key.
 interface RowStats {
     count: number;
     distinct_users: number;
@@ -274,7 +274,7 @@ function aggregate(log_path: string, window_days: number): AggregateResult {
         }
         kept += 1;
         const tier = Math.trunc(rec.tier);
-        const key = `${tier}${rec.command}`;
+        const key = `${tier}\0${rec.command}`;
         if (!keyMeta.has(key)) {
             keyMeta.set(key, { tier, command: rec.command });
             counts.set(key, 0);

package/dist/agent-src/templates/scripts/work_engine/directives/ui/polish.ts

@@ -336,7 +336,7 @@ function _classify_token_violations(
     tokens: Record<string, Any>,
 ): [Record<string, Any>[], Record<string, Any>[]] {
     const matched: Record<string, Any>[] = [];
-    // Insertion-ordered map keyed by `${category}${value}` to mirror the
+    // Insertion-ordered map keyed by `${category}\0${value}` to mirror the
     // Python `dict[tuple[str, str], int]` insertion order.
     const unmatched_counts = new Map<string, { category: string; value: string; count: number }>();
     for (const finding of findings) {
@@ -356,7 +356,7 @@ function _classify_token_violations(
             matched.push(finding);
             continue;
         }
-        const key = `${category}${value}`;
+        const key = `${category}\0${value}`;
         const existing = unmatched_counts.get(key);
         if (existing) {
             existing.count += 1;

package/dist/agent-src/templates/scripts/work_engine/directives/ui/review.ts

@@ -294,7 +294,7 @@ function _filter_known(violations: Any[], known: Any[]): Any[] {
  * scalars, mirroring Python tuple-equality in a JS `Set`.
  */
 function _keyOf(rule: Any, selector: Any): string {
-    return `${_tag(rule)}${_tag(selector)}`;
+    return `${_tag(rule)}\0${_tag(selector)}`;
 }
 
 function _tag(v: Any): string {

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

package/dist/cli/commands/doctorShell.js

@@ -9,6 +9,7 @@
 import { existsSync } from 'node:fs';
 import { BASH_ENTRY, BASH_SHIM, CONSUMER_ROOT, PACKAGE_ROOT } from '../paths.js';
 import { logger } from '../log/logger.js';
+import { detectRtk } from '../../install/rtkDetection.js';
 function checkNode() {
     const required = 20;
     const version = process.versions.node;
@@ -45,12 +46,31 @@ function checkBashShim() {
         detail: ok ? BASH_SHIM : `${BASH_SHIM} (not found)`,
     };
 }
+/**
+ * rtk is an OPTIONAL third-party tool — its absence never fails the doctor
+ * (ok stays true for every state); the row is an informational readout of
+ * the two-stage identity probe (docs/contracts/rtk-detection.md).
+ */
+function checkRtk() {
+    const d = detectRtk();
+    if (!d.present)
+        return { name: 'rtk', ok: true, detail: 'not installed (optional; see `agent-config rtk:detect`)' };
+    switch (d.identity) {
+        case 'token-killer':
+            return { name: 'rtk', ok: true, detail: `Rust Token Killer${d.version !== undefined ? ` v${d.version}` : ''} (${d.binPath ?? 'on PATH'})` };
+        case 'unknown-rtk':
+            return { name: 'rtk', ok: true, detail: 'DIFFERENT TOOL on PATH (name collision, not Rust Token Killer) — see `agent-config rtk:detect`' };
+        default:
+            return { name: 'rtk', ok: true, detail: 'present but unverified — run `rtk gain` manually' };
+    }
+}
 export function runDoctorShell() {
     const checks = [
         checkNode(),
         checkPackageRoot(),
         checkBashEntry(),
         checkBashShim(),
+        checkRtk(),
     ];
     logger.info(`consumer_root: ${CONSUMER_ROOT}`);
     logger.info(`package_root:  ${PACKAGE_ROOT}`);