@protoboardai/ext-hardware 0.0.0-stage → 0.2.0

package/skills/harness-author/SKILL.md

@@ -0,0 +1,232 @@
+---
+name: harness-author
+description: Author the physical carriers of a UHD system's links — wire harnesses (connector ends, conductors, lengths, gauges; soldered ends as link-scoped compositions) and mechanical joints as fastener stacks (stack-up arithmetic, hardware selection, nut-engagement check, tightening torque, supplier-cited hardware). Use after system-compose has the links, whenever a link has no carrier, a joint has no hardware, or UHD_ASSEMBLY / UHD_HARNESS_CONNECTOR / UHD_FASTENER_TORQUE fire; follow with harness-verify.
+---
+
+# Harness author
+
+In UHD a harness is a module (`kind: "harness"`) that physically carries
+connections: a cable carries conductors between its connector ends, a set of
+screws, spacers and nuts carries a mechanical joint. The BOM, the assembly
+guide and the checks all see the physical parts.
+
+Worked examples: `examples/quadcopter-5in/src/harnesses/harnesses.uhd.ts`
+(the cables and six fastener stacks) and `hardware.uhd.ts` (the hardware
+parts, each with a fetched supplier listing); how every cable was worked out,
+modelled, routed and drawn: `examples/quadcopter-5in/docs/harnesses-and-cad.md`.
+Model reference: `@deltarobotics/uhd` `docs/connectors-and-harnesses.md`.
+
+## Purpose
+
+Give every link a physical carrier, so the BOM, the assembly guide, the work
+order and the checks see the cables, screws, spacers and nuts that are
+actually bought and fitted. Use it after **system-compose** has the links,
+whenever a link has no carrier or a joint has no hardware, and when
+`UHD_ASSEMBLY`, `UHD_HARNESS_CONNECTOR` or `UHD_FASTENER_TORQUE` fire. In
+**build-a-project** it is part of stage 4; **harness-cad** (stage 7) then
+gives each cable its routed geometry.
+
+## Inputs
+
+| Input | Where | From |
+| --- | --- | --- |
+| The system's links and mates | the root system and sub-assemblies in `src/` | **system-compose** |
+| Parts' sockets, pads and frames | the parts' connector composites and geometry (`npx protoboard inspect <instance>`) | **uhd-part-author**, catalog parts |
+| Manuals' wiring orders, pinouts | `parts/evidence/<id>/`, catalog files in `parts/catalog/<id>/` | **uhd-part-research** |
+| Peak currents | `npx protoboard check --format json` (`UHD_PROPULSION_CURRENT` details, supply budgets) | the checks |
+| Supplier listings for hardware | fetched pages, dated | this skill, step 2 (item 3) |
+| Structure thicknesses | plate modules' mechanical metadata | **frame-cad**, **enclosure-cad** |
+
+## Steps
+
+### 1. Wire harnesses (physical)
+
+A cable is one physical thing, so it is modelled physically:
+
+- each **end is a connector composite** (`Connector()`), positions in the
+  printed order;
+- the **conductors are an internal link** between the ends (`self` ↔ `self`),
+  straight through unless `childLinks` state a crossover;
+- the system **links each end** to the part's socket (a connector composite
+  on the part), or, for a **soldered end**, to a **link-scoped composition**
+  of the pads it lands on (`compose`).
+
+UHD then derives the functional links (power, UART, I2C, S.Bus…) by tracing
+the conductors, and every system check runs on them. Do not also store those
+functional links.
+
+```ts
+export const DJI_O4_3IN1_CABLE: ModuleDef = {
+  id: "dji-o4-3in1-cable", name: "DJI O4 3-in-1 cable", kind: "harness", topology: "wire",
+  manufacturer: "DJI",
+  interfaces: [
+    Connector({ id: "end_fc", connector: "dji_6pin", gender: "plug", pins: ["10V", "G", "T5", "R5", "G", "Sbus"] }),
+    Connector({ id: "end_o4", connector: "dji_3in1_cable_6pin", pins: ["VCC", "GND", "RX", "TX", "GND", "S.Bus"] }),
+  ],
+  links: [{ id: "wires", a: { self: true, interfaceId: "end_fc" }, b: { self: true, interfaceId: "end_o4" } }],
+  traits: [{ type: "usage_note", params: { note: "Wire order VCC, GND, RX, TX, GND, S.Bus (O4 user manual).", included_with: "dji-o4-air-unit" } }],
+};
+
+// in the system
+link("dji_fc", "DJI socket", ["stack", "dji_socket"], ["dji_cable", "end_fc"]),
+link("dji_o4", "O4 cable socket", ["dji_cable", "end_o4"], ["video", "fc_cable_socket"]),
+// a soldered end: the FC has no connector there, so the link composes the pads
+{ id: "gnss_pads", a: { child: "gnss_lead", interfaceId: "end_fc" },
+  b: { child: "stack", interfaceId: "gnss_pads",
+       compose: { p1: "rail_4v5", p2: "fc:uart1_tx", p3: "fc:uart1_rx", p4: "fc:i2c1_scl", p5: "fc:i2c1_sda", p6: "gnd" } } },
+```
+
+If a part has a socket but no connector composite for it, fix the part
+(**uhd-part-author** rule), do not compose around it.
+
+For every harness decide and record, each from a source or as an assumption:
+
+| Fact | Where | Rule |
+| --- | --- | --- |
+| Topology | `topology: "wire" \| "bus" \| "split" \| "or"` | wire = point to point; bus = shared (all boards on the same bolts); split = one source, several drops. |
+| Ends and connectors | one `Connector()` per end: type, gender, positions in printed order | The type must match the part's socket (`connector_mismatch`), genders must differ (`connector_gender`), counts must agree (`connector_positions`). A soldered end is `solder_leads` and links to a composition. |
+| Conductors | the internal `self` link; `childLinks` only for a non 1:1 cable | Copy the order from the manual; straight-through (1:1) is a claim too. A wrong conductor inside a UART/I2C shows as `harness_wiring` on the derived link. |
+| Length | `performance` trait `{ kind: "cable", length_mm }` | Measure along the route between the placed ends (assembly positions) plus a service loop; a bought cable's length is its listing's. **harness-cad** reports the shortest clear route. |
+| Gauge | `performance` trait `wire_gauge_awg` | From the peak current the links carry (the system checks give it: `UHD_PROPULSION_CURRENT` details, supply budgets). Cite the ampacity table used; short silicone leads carrying bursts are an assumption to state, not a table value. |
+| Supplied with a part | `usage_note` `included_with: "<part id>"` | Included cables need no separate sources; the part's evidence covers them. |
+
+The harness is a child of the module that declares the links to its ends.
+Power and its ground travel in the same harness.
+
+Check the derived links:
+
+```bash
+npx protoboard check --format json         # UHD_LINK_STATE on derived links names the cable links they run through
+```
+
+Every functional connection you expect through the cable must be there, in
+state `configured` (`deriveLinks(system, lookup)` from `@deltarobotics/uhd`
+lists them).
+
+Give every cable its routed 3D geometry with **harness-cad**
+(`@protoboardai/ext-harness-cad`): add a `cable_build` trait (colours, twisted
+or flat, diameter when the gauge is unknown), a `cad.config.ts` in
+`src/harnesses/<harness id>/`, run `npx protoboard run harness-cad`, and set
+a cut-to-length cable's `length_mm` from the shortest route it reports.
+
+See [wire harnesses](references/wire-harnesses.md) for the checklist and the quad's cables.
+
+### 2. Fastener stacks (mechanical joints)
+
+A mechanical harness lists the hardware as children with quantities, one
+`bolt_pattern` interface (role `component`) matching the joint, and a
+`fastenerStack`: where each part sits along the normal of the joint's
+**structure-side frame**, measured from the structure face (mm), repeated at
+every hole of its bolt pattern.
+
+```ts
+fastenerStack: [
+  { child: "screws",  atMm: -5 },            // head under the 5 mm plate, shank up (+normal)
+  { child: "spacers", atMm: 0 },             // 6 mm nylon spacer 0–6
+  { child: "spacers", atMm: 10 },            // after the 4 mm ESC grommet (6–10): 10–16
+  { child: "nuts",    atMm: 20, torque },    // after the FC grommet (16–20): 20–24
+],
+```
+
+`atMm` is where the part's own origin sits (a screw's origin is under its
+head, a nut's and spacer's at one face); `direction: -1` flips the part (a
+screw inserted from above). `positions` overrides the hole list (the O4
+camera: two holes per side plate).
+
+1. **Draw the stack-up** from the structure face outward: plate thickness,
+   each spacer/standoff, each board or grommet (the clamped thickness, not the
+   board's), the nut. Every thickness is a cited value or an `assumption`.
+2. **Choose lengths.** Screw length ≥ grip (everything between the head and
+   the nut's far face) + about 1–2 thread pitches beyond the nut; for a blind
+   thread (motor base, standoff, tapped hole, heat-set insert) ≤ the available
+   thread depth and ≥ ~1.5 × diameter engagement where the material allows
+   (derate for aluminium or plastic; honour a maker's maximum, e.g. DJI's
+   3.10 mm for the O4 camera).
+3. **Select real hardware** with a supplier listing you fetched: standard,
+   size, length, material, part number, pack quantity. Put the listing on the
+   part as a `usage_note` with `source` (and packaging as a `performance`
+   trait). Dimensions the listing does not give (M2 nyloc height) are
+   nominal-standard assumptions, stated as such. A local hardware module also
+   needs the sizes the hardware CAD generator reads (**frame-cad** step 6):
+   `npx protoboard run hardware-cad --input module=<id>`.
+4. **Tightening torque** on the item you turn: `torque: { torqueNm, source }`
+   when a maker states it, else `{ torqueNm, assumption, reference: [...] }`
+   with the supplier table rows it was derated from (soft clamps, aluminium
+   threads and PCBs need far less than a steel-nut table value).
+   `UHD_FASTENER_TORQUE` warns on joints without one.
+5. **Check** with the stack-up script and `protoboard check`:
+
+```bash
+npx tsx node_modules/@protoboardai/ext-hardware/skills/harness-author/scripts/stackup.ts   # [harness-id ...] [--json]
+npx protoboard check
+```
+
+The script prints every item's span, the thread each screw leaves beyond each
+nut's far face (negative: the screw stops inside the nut), and harness
+quantities that differ from the positions the stack places. `assemble` makes
+the same nut check (`UHD_ASSEMBLY: … ends 0.4 mm short of the far face of nuts`).
+
+The quad's six stacks, worked through line by line: [stack-up worked examples](references/stack-up.md).
+
+### 3. After a structure change
+
+A change in plate thickness, standoff height or pattern (e.g. via
+**frame-cad** or **enclosure-cad**) invalidates every stack that references
+that face: the checks catch a screw that no longer reaches its nut, but not a
+screw head that now sits inside a thicker plate or a blind thread that is now
+too short. Re-derive each affected stack and re-run the script.
+
+## Decision points
+
+| Decision | Rule |
+| --- | --- |
+| Connector end or soldered end | A connector composite when the part has a socket; `solder_leads` and a link-scoped `compose` only when the part has bare pads. Never compose around a socket the part model lacks: fix the part. |
+| Topology | `wire` point to point; `bus` when several boards share it; `split` when one source drops to several. |
+| Bought or cut cable | A cable included with a part (`included_with`) or bought at a listed length keeps that length; a cut cable takes the routed length plus a service loop. |
+| Gauge | From the peak current of the derived links and a cited ampacity table; otherwise an assumption. |
+| Screw length | The shortest standard length that leaves 1–2 pitches beyond the nut, or that stays within a blind thread's depth and any maker maximum. |
+| Torque | The maker's value when stated; otherwise derated from a supplier table, as an assumption with the rows it came from. |
+
+## Outputs
+
+| Output | Where |
+| --- | --- |
+| Harness modules (cables, fastener stacks) | `src/harnesses/` (the quad: `harnesses.uhd.ts`) |
+| Hardware parts with supplier listings | `src/harnesses/hardware.uhd.ts`, nominal CAD in `src/harnesses/cad/` |
+| Per-cable provider directories | `src/harnesses/<harness id>/cad.config.ts` (routes by **harness-cad**) |
+
+## Verification
+
+```bash
+npx protoboard check --format json         # no UHD_ASSEMBLY, UHD_HARNESS_CONNECTOR, UHD_FASTENER_TORQUE, PB_UNKNOWN_HARNESS
+npx tsx node_modules/@protoboardai/ext-hardware/skills/harness-author/scripts/stackup.ts --json   # exit 0
+```
+
+Every expected derived link is present and `configured`. Then
+**harness-verify**, by a fresh agent.
+
+## Failure handling
+
+| Code or symptom | Means | Do |
+| --- | --- | --- |
+| `UHD_LINK_STATE` `connector_mismatch` / `connector_gender` / `connector_positions` | The plug does not fit the socket | Fix the cable end's connector type, gender or position count from the manual |
+| `UHD_LINK_STATE` `compose_unknown_slot` | A composition names a position the cable end lacks | Fix the composition |
+| `UHD_LINK_STATE` `harness_wiring` | A conductor lands on the wrong pad inside a UART/I2C | Fix the conductor order or the composition |
+| `UHD_HARNESS_CONNECTOR` | A harness end does not match the interface it mates | Fix the end or the connector choice |
+| `UHD_ASSEMBLY` "… short of the far face of nuts" | The screw stops inside the nut | Choose a longer screw; never shorten the model's stack |
+| `UHD_ASSEMBLY` harness quantity ≠ stack positions | Quantities and holes disagree | Fix the quantities |
+| `UHD_FASTENER_TORQUE` | No torque, or one without source or assumption | Add it on the turned item |
+| `PB_UNKNOWN_HARNESS` | A link names a harness that is not a child | Add the harness child, or fix the name |
+| `HARDWARE_CAD_PARAMS` | A fastener module lacks a size | Add it from the listing |
+| `stackup.ts` exits 1 | A screw stops inside a nut or none passes through one | As for `UHD_ASSEMBLY` |
+
+Every other code: **system-compose** [diagnostic codes](../system-compose/references/diagnostic-codes.md).
+
+## Hard rules
+
+1. Every length and thickness in a stack is cited or an `assumption`.
+2. Never shorten the model's stack to make the nut check pass; change the
+   hardware.
+3. One harness per physical carrier; do not hide a cable inside a module.
+4. Hardware you buy is a part with a supplier listing; hardware included with
+   a part says `included_with`.

package/skills/harness-author/references/stack-up.md

@@ -0,0 +1,70 @@
+# Stack-up worked examples (quadcopter-5in)
+
+All positions in mm along the structure-side frame's normal, from the
+structure face (z = 0), as `fastenerStack` states them and as
+`scripts/stackup.ts` prints them. Plate thicknesses: bottom plate 5, top plate
+2 (frame module metadata `plate_thickness_mm`).
+
+## Stack hardware — M3 × 30, spacers, grommets, nyloc (bus: ESC and FC share the bolts)
+
+| z from … to | Item | Source of the thickness |
+| --- | --- | --- |
+| −5 … 0 | bottom plate (screw head under it) | frame design value |
+| −5 … 25 | M3 × 30 screw (`atMm: -5`, up) | ISO 4762 length |
+| 0 … 6 | 6 mm nylon spacer | Ettinger 005.83.060 listing |
+| 6 … 10 | ESC in its M3 grommet (4 mm clamp) | assumption on the grommet clamp (DolphinRC stack) |
+| 10 … 16 | 6 mm nylon spacer | Ettinger listing |
+| 16 … 20 | FC in its grommet | as the ESC |
+| 20 … 24 | M3 nyloc nut, 0.3 N·m (snug: soft grommets) | ISO 10511 nominal height |
+
+Grip = 5 + 6 + 4 + 6 + 4 + 4 = 29 mm; the M3 × 30 ends at 25: **1 mm beyond
+the nut's far face**. An M3 × 25 would stop 4 mm short: the nut check fails.
+The mates follow the same numbers: the 1.6 mm ESC PCB sits centred in its
+4 mm grommet, so its underside is at 6 + (4 − 1.6) / 2 = 7.2 mm
+(`gapMm: 7.2`), the FC's at 17.2.
+
+## GPS hardware — M2 × 12 down through the board into a nut under the top plate
+
+| z | Item |
+| --- | --- |
+| −2 … 0 | top plate |
+| −4.8 … −2 | M2 nyloc nut (`atMm: -2`, `direction: -1`) — 2.8 mm nominal (the listing gives no M2 dimensions: assumption) |
+| 0 … 5 | 5 mm nylon spacer (the GH6P sockets stand 4.35 mm proud; vendor STEP) |
+| 5 … 5.62 | GPS PCB, 0.62 mm |
+| 5.62 … −6.38 | M2 × 12 screw, head on the board (`atMm: 5.62`, `direction: -1`) |
+
+Grip 0.62 + 5 + 2 + 2.8 = 10.42 mm. M2 × 12 leaves **1.58 mm beyond the far
+face**; M2 × 10 would stop 0.42 mm inside the nut (`UHD_ASSEMBLY … ends 0.4 mm
+short`; the `short-gps-screws` fault scenario). Torque 0.1 N·m, an assumption
+well under the M2 class 4.6 table value (0.17 N·m) so the PCB and spacers are
+not crushed.
+
+## Air-unit hardware — M2 × 18 up through the plate, airflow spacers, module, nut
+
+−5 … 0 plate · −5 … 13 M2 × 18 · 0 … 3 spacer · 3 … 9 module mounting ear
+(6 mm) · 9 … 11.8 nut. Grip 16.8 mm: **1.2 mm beyond**. The 3 mm spacer is the
+DJI airflow requirement (mate `gapMm: 3`).
+
+## Frame hardware — two blind threads in a 30 mm standoff
+
+−5 … 3 M3 × 8 from below: 3 mm into the standoff's thread · 0 … 30 standoff ·
+30 … 32 top plate · 24 … 32 M3 × 8 from above (`direction: -1`): 6 mm into the
+standoff. No nut: the check is the thread depth, which the standoff listing
+must give. Torque 0.6 N·m, derated for the aluminium thread from the A2-70
+steel-nut table value (0.95 N·m).
+
+## Motor hardware — M3 × 8 up into the motor base (included with the motor)
+
+−5.5 … 2.5: 5 mm plate + 0.5 mm raised pad, then 2.5 mm into the motor base,
+whose thread depth (3 mm) the part note records; longer screws reach the
+windings. `included_with` the motor, so no separate listing.
+
+## Camera hardware — M2 × 5 into the O4 camera, both side plates
+
+Side plates' outer faces at ±9 (plates ±7 … ±9 around the 14 mm camera),
+screws at `atMm: ∓9` with `positions: [[0, -8], [0, 8]]`. A 5 mm screw through
+a 2 mm plate leaves 3.0 mm for the camera's thread; DJI's maximum engagement
+is 3.10 mm. The part's own note says "2.2 mm into the camera": reconcile the
+two before building (washer? thread depth?). A 0.1 mm margin to a maker's
+maximum is worth a second look — this is the kind of finding
+**harness-verify** exists for.

package/skills/harness-author/references/wire-harnesses.md

@@ -0,0 +1,35 @@
+# Wire harnesses
+
+## Checklist per cable
+
+- [ ] `kind: "harness"`, `topology`, `manufacturer` (or "(custom)"), `description` naming both ends.
+- [ ] One `Connector()` per end, positions in the printed order, `gender` when known.
+      Connector names are shared vocabulary: use the type the mating part's socket declares (`jst_sh_8`, `xt60`, `dji_6pin`); a soldered end is `solder_leads`.
+- [ ] Conductors: an internal `self` ↔ `self` link between the ends; `childLinks` only when the cable is not 1:1. The order comes from the manual or listing (cited in a usage_note).
+- [ ] `performance` trait `{ kind: "cable", length_mm, wire_gauge_awg }`, each cited or in an `assumption`.
+- [ ] Current: the highest current any carried link sees (supply budgets, `UHD_PROPULSION_CURRENT` details `totalPeak`),
+      compared with the conductor's rating from a cited table or the cable maker. Burst-only margins are an `assumption` with the reason.
+- [ ] System links: each end linked to the part's socket, or a soldered end to a link-scoped composition of the pads (`compose`). No stored functional links for what the cable carries: they are derived.
+- [ ] Derived links (`deriveLinks`) list every expected connection, all `configured`; no `harness_wiring`.
+- [ ] `included_with: "<part id>"` when the cable ships with a part; otherwise sources/verification like any purchased part.
+- [ ] `protoboard check`: no link errors (`connector_*`, `compose_unknown_slot`, `harness_wiring` appear as `UHD_LINK_STATE`), no `PB_UNKNOWN_HARNESS`.
+
+## The quadcopter's cables
+
+| Harness | Ends (system links) | Derived | Facts and sources |
+| --- | --- | --- | --- |
+| `dolphinrc-sh8-fc-esc-cable` | FC `esc_socket` ↔ ESC `fc_socket` (inside the stack) | `fc:esc_port ↔ esc:fc_port` | 50 mm SH1.0 8-pin, straight-through (BAT GND CUR VOID M1 M2 M3 M4); stack manual; included with the FC. |
+| `dji-o4-3in1-cable` | FC `dji_socket` ↔ O4 `fc_cable_socket` | 10 V → VCC, GND ×2, UART5 ↔ MSP DisplayPort, S.Bus | Wire order VCC, GND, RX, TX, GND, S.Bus (O4 user manual); included with the O4. |
+| `dolphinrc-xt60-battery-lead` | battery `xt60` ↔ ESC pads (composition `battery_pads`) | `battery_out → bat_in`, `battery_gnd → bat_neg` | 12 AWG, 120 mm, XT60 male (product page); included with the ESC. The bulk capacitor is soldered across the same pads (links without a harness: a solder joint at the pads). |
+| `matek-gh6p-gnss-lead` | GNSS `gh6p_1` ↔ FC pads (composition `gnss_pads`) | UART1, I2C1, 4.5 V, GND | The M9N's included 20 cm GH6P lead, one plug cut off and soldered (the FC's GPS socket has no I2C). |
+
+The receiver is soldered directly to FC pads with no separate lead in the
+reference project; if a lead is added, model it like the GNSS lead.
+
+## Lengths from the model
+
+The assembly places every module (`assemble(...).placements`), so the straight
+distance between two linked interfaces is known once both ends have frames;
+the route adds bends and a service loop. Record the length you chose and why
+(`assumption`: "routed along the left arm, +20 mm service loop"). A length the
+cable listing states wins over a computed one.

package/skills/harness-author/scripts/stackup.ts

@@ -0,0 +1,104 @@
+/**
+ * Fastener stack-up table for the project's mechanical harnesses.
+ *
+ *   npx tsx <this file> [harness-id ...] [--json]
+ *
+ * For every harness with a `fastenerStack`: each item's span along the joint
+ * normal (from the structure-side face, mm), its torque, and for each nut
+ * the thread the screw leaves beyond the nut's far face (negative = the
+ * screw stops inside the nut; UHD's assemble reports that as an error).
+ * A nut on a threaded shaft (a prop nut) has the shaft as its screw.
+ * Harness quantities are compared with the number of positions the stack
+ * places. Positions are per hole of the structure's bolt pattern unless an
+ * item lists its own `positions`.
+ */
+import type { ModuleDef } from "@deltarobotics/uhd";
+import { loadProject } from "@protoboardai/core";
+
+const args = process.argv.slice(2);
+const json = args.includes("--json");
+const only = args.filter((a) => !a.startsWith("--"));
+const p = await loadProject(process.cwd(), { checks: false, extensions: false });
+
+const lengthOf = (def: ModuleDef) =>
+  def.interfaces.flatMap((i) => i.parameters ?? []).find((x) => x.id === "length")?.value ?? 0;
+const kindOf = (def: ModuleDef) => (["nut", "screw", "standoff", "spacer"] as const).find((k) => def.tags?.includes(k)) ?? "part";
+const holesOf = (h: ModuleDef) => h.interfaces.flatMap((i) => i.parameters ?? []).find((x) => x.id === "hole_count")?.value ?? 4;
+
+const harnesses = [...new Set(p.instances.map((i) => i.definition))]
+  .map((id) => p.lookup(id)!)
+  .filter((d) => d?.fastenerStack?.length && (!only.length || only.includes(d.id)))
+  .sort((a, b) => a.id.localeCompare(b.id));
+
+/**
+ * The threaded shaft a harness's nut runs on (a prop nut on a motor shaft): the joint the harness carries
+ * is a shaft link whose structure end (a) states a thread in its `shaft` trait. UHD's assemble takes that
+ * shaft as the nut's screw; so does this table.
+ */
+function threadedShaftOf(h: ModuleDef): string | undefined {
+  for (const rec of p.definitions.values()) {
+    const parent = rec.def;
+    for (const l of parent.links ?? []) {
+      const ref = parent.children?.find((c) => c.id === l.harness);
+      if (!ref || ref.moduleDefId !== h.id || !("child" in l.a)) continue;
+      const end = l.a as { child: string; interfaceId: string };
+      const child = parent.children?.find((c) => c.id === end.child);
+      const iface = child && p.lookup(child.moduleDefId)?.interfaces.find((i) => i.id === end.interfaceId);
+      const thread = iface?.protocols?.some((x) => x.type === "shaft") ? iface.traits?.find((t) => t.type === "shaft")?.params?.thread : undefined;
+      if (typeof thread === "string") return `${child!.moduleDefId}:${iface!.id} (${thread})`;
+    }
+  }
+  return undefined;
+}
+
+const report = harnesses.map((h) => {
+  const items = h.fastenerStack!.map((item) => {
+    const ref = h.children?.find((c) => c.id === item.child);
+    const def = ref ? p.lookup(ref.moduleDefId) : undefined;
+    const len = def ? lengthOf(def) : 0;
+    const dir = item.direction ?? 1;
+    return {
+      child: item.child,
+      part: def?.id ?? `(unknown child ${item.child})`,
+      kind: def ? kindOf(def) : "part",
+      from: Math.min(item.atMm, item.atMm + dir * len),
+      to: Math.max(item.atMm, item.atMm + dir * len),
+      direction: dir,
+      positions: item.positions?.length ?? holesOf(h),
+      torqueNm: item.torque?.torqueNm,
+      torqueBasis: item.torque ? (item.torque.source ? "source" : item.torque.assumption ? "assumption" : "unsupported") : undefined,
+    };
+  });
+  const nuts = items
+    .filter((x) => x.kind === "nut")
+    .map((nut) => {
+      const screw = items.find((s) => s.kind === "screw" && s.from <= nut.to && s.to >= nut.from);
+      const shaft = !screw && nut.from >= 0 ? threadedShaftOf(h) : undefined;
+      if (shaft) return { nut: nut.child, screw: `threaded shaft ${shaft}`, beyondFarFaceMm: null, onShaft: true };
+      if (!screw) return { nut: nut.child, screw: null, beyondFarFaceMm: null };
+      // the far face is the one the screw reaches last
+      const up = screw.direction === 1 ? screw.to - nut.to : nut.from - screw.from;
+      return { nut: nut.child, screw: screw.child, beyondFarFaceMm: Number(up.toFixed(2)) };
+    });
+  const placed = new Map<string, number>();
+  for (const x of items) placed.set(x.child, (placed.get(x.child) ?? 0) + x.positions);
+  const quantities = (h.children ?? []).map((c) => ({ child: c.id, listed: c.quantity ?? 1, placed: placed.get(c.id) ?? 0 }));
+  return { harness: h.id, name: h.name, items, nuts, quantities };
+});
+
+if (json) console.log(JSON.stringify(report, null, 2));
+else {
+  for (const r of report) {
+    console.log(`\n${r.harness}  ${r.name ?? ""}`);
+    for (const x of r.items) {
+      console.log(
+        `  ${x.child.padEnd(10)} ${x.part.padEnd(40)} ${x.from.toFixed(2).padStart(7)} … ${x.to.toFixed(2).padEnd(7)} ${x.direction === 1 ? "+" : "-"}  ×${x.positions}${x.torqueNm !== undefined ? `  ${x.torqueNm} N·m (${x.torqueBasis})` : ""}`,
+      );
+    }
+    for (const n of r.nuts) {
+      console.log("onShaft" in n ? `  nut ${n.nut}: on the ${n.screw} (the shaft's thread length is the motor's fact; check it covers the nut)` : n.screw ? `  nut ${n.nut}: ${n.screw} ${n.beyondFarFaceMm! >= 0 ? `protrudes ${n.beyondFarFaceMm} mm beyond the far face` : `STOPS ${-n.beyondFarFaceMm!} mm SHORT of the far face`}` : `  nut ${n.nut}: NO SCREW passes through it`);
+    }
+    for (const q of r.quantities.filter((q) => q.listed !== q.placed)) console.log(`  quantity ${q.child}: listed ${q.listed}, stack places ${q.placed}`);
+  }
+}
+process.exitCode = report.some((r) => r.nuts.some((n) => !("onShaft" in n) && (n.beyondFarFaceMm === null || n.beyondFarFaceMm < 0))) ? 1 : 0;

package/skills/harness-verify/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: harness-verify
+description: Independently audit a project's harnesses — re-derive every fastener stack-up from cited thicknesses, re-check thread engagement, torques and hardware listings, and every cable's connectors, conductor map, gauge and length against the sources. Run by a fresh agent after harness-author, and after any structure change; records findings, never edits the model.
+---
+
+# Harness verify
+
+The author's arithmetic is a claim. Re-derive it from the sources, not from
+the model's own numbers.
+
+## Purpose
+
+Prove that every joint will assemble and hold and every cable connects what
+the manuals say, by re-deriving the facts independently. Use it after
+**harness-author**, after any structure change (a plate, enclosure or
+standoff that moved), and before a release. In **build-a-project** it closes
+stage 4 and is repeated in stage 8. It records findings; it never edits the
+model.
+
+## Inputs
+
+| Input | Where | From |
+| --- | --- | --- |
+| Harness modules and hardware parts | `src/harnesses/` | **harness-author** |
+| Structure thicknesses | plate and enclosure modules' metadata and `out/body.manifest.json` | **frame-cad**, **enclosure-cad** |
+| Sources | supplier listings (`usage_note` sources), part datasheets and manuals (`parts/evidence/`, `parts/catalog/<id>/`) | **harness-author**, the part skills |
+| Check results and the stack-up report | the commands in step 1 | the project |
+
+## Steps
+
+### 1. Automated
+
+```bash
+npx protoboard check --format json          # UHD_ASSEMBLY, UHD_HARNESS_CONNECTOR, UHD_FASTENER_TORQUE, PB_UNKNOWN_HARNESS
+npx tsx node_modules/@protoboardai/ext-hardware/skills/harness-author/scripts/stackup.ts --json
+```
+
+Both must be clean (the script exits 1 when a screw stops inside a nut or no
+screw passes through one). Clean is necessary, not sufficient: the checks
+compare the model with itself.
+
+### 2. Fastener stacks, per harness
+
+1. Rebuild the stack-up from the structure face using thicknesses taken from
+   the **sources** (plate thickness from the structure module, spacer and nut
+   heights from the listings, board thickness from the datasheet, grommet
+   clamp from the stack manual). Mark each as sourced or assumed.
+2. Compare with the model's `fastenerStack` positions. Any difference over
+   0.1 mm is a finding.
+3. Thread: nut joints need the screw at least flush with the nut's far face
+   (the check) plus about a pitch; blind threads need engagement within the
+   thread depth and any maker maximum. Re-derive; note the margin.
+4. Heads: a screw head must bear on a face, not sit inside a plate or a pad
+   that grew (the checks do not see this).
+5. Torque: the value is on the turned item, cites a source or states an
+   assumption with reference rows, and is plausible for the weakest material
+   in the clamp.
+6. Hardware: open each supplier listing (the `usage_note` source); size,
+   length, material and part number match the part; quantities × packs cover
+   the harness quantities.
+
+### 3. Cables
+
+Each end is a connector composite whose type, gender and position order match
+the mating socket and the manual; a soldered end's composition (`compose`)
+puts each wire on the pad the manual names. The conductors (internal link,
+`childLinks` for a crossover) match the manual's pinout. List the derived
+links (`deriveLinks` from `@deltarobotics/uhd`) and confirm each expected
+connection is there and `configured`, and that nothing unexpected is (a wire
+on the wrong pad shows up as an extra or incompatible derived link, or
+`harness_wiring`). The gauge carries the peak current of the derived links
+per a cited table or the maker; the length reaches between the placed ends
+with a service loop. Where **harness-cad** has routed the cable, compare the
+modelled length with `length_fit.route_mm` in its `out/body.manifest.json`.
+
+### 4. Write the findings
+
+`docs/reviews/harness-verify-<YYYY-MM-DD>.md` with a table per harness:
+`item | model | re-derived | source | margin | finding`, then the findings
+list `{ id, severity, harness, finding, evidence, fix }`.
+
+## Decision points
+
+| Decision | Rule |
+| --- | --- |
+| Severity | **blocker** for anything that would not assemble or would strip or crush; **major** for a claim not supported by a source; **minor** for traceability. |
+| A difference between model and re-derivation | Over 0.1 mm in a stack, or any wrong conductor, is a finding. |
+| A source and the model's own note disagree | A finding either way: name both. The quad's camera screws are a good calibration case: the model's positions leave 3.0 mm of thread in the camera against DJI's 3.10 mm maximum, while the part's note says 2.2 mm. |
+
+## Outputs
+
+| Output | Where |
+| --- | --- |
+| The verification report | `docs/reviews/harness-verify-<YYYY-MM-DD>.md` |
+
+## Verification
+
+The report has a table for every harness in `src/harnesses/`, every row
+cites its source, and step 1's commands were clean when it was written (say
+so, with their exit codes). No model file changed.
+
+## Failure handling
+
+| Code or symptom | Means | Do |
+| --- | --- | --- |
+| `UHD_ASSEMBLY` or `stackup.ts` exit 1 | The model does not assemble | Stop; hand back to **harness-author** before auditing |
+| `UHD_FASTENER_TORQUE` | A joint without a sourced or assumed torque | Finding (major) |
+| `UHD_HARNESS_CONNECTOR`, `UHD_LINK_STATE` on a cable link | An end does not fit, or a conductor is on the wrong pad | Finding (blocker) |
+| `HARNESS_ROUTE_LENGTH` | Modelled and routed length differ | Finding; the author regenerates or fixes the length (**harness-cad**) |
+| A supplier listing no longer loads | The source is gone | Record it unverifiable, with the date; the author replaces the source |
+
+Every other code: **system-compose** [diagnostic codes](../system-compose/references/diagnostic-codes.md).