willtools-demo/docs/handoff.md

Handoff

For an agent picking this repo up cold.

Read in this order: README.md for what the tool is and which buttons exist, CLAUDE.md for the rules and the layout, docs/lift-check.md for the mechanics of the handling check, then this.

What this file is now. It was written as the orientation document and it is no longer the best one for that — the README carries the current button set and docs/architecture-migration.md carries the current state of the code. What it still holds, and nothing else does, is the engineering part: the ranked open questions, what is knowingly approximate, what the last full sweep found, and what to pick up first. Read it for that. Where it describes the shape of the tool, check the README before believing it.

Corrected 2026-08-31; a stale section is marked below rather than deleted.

Nothing here repeats CLAUDE.md. The one rule worth saying twice anyway: never reload pyRevit. It kills Revit outright, our code never runs, and no amount of care downstream helps. Restart Revit instead.

---

Where the work stands

Reorganised 2026-09-05. Tools.panel now holds one pulldown, Modeling (Reinforce Suggestion, Reinforcing QC, Ticket QC), plus Snapshot as the one remaining large icon. Panel Lift Check moved onto Design.panel's DesignHub pulldown, alongside Panel Analysis — both finished, grouped there because the owner wants the analysis tools together, not because either is unfinished. Five set-up commands still live behind the Config pulldown on Setup.panel — Project Config, Design Extract, Self Check, Job Recon, Takeoff. Gravity, Lateral, Beam Analysis and Connection Analysis are the four unfinished rows left on DesignHub, and they are quarantined there with (WIP) in their titles. The README's table is the authority on that list.

Reinforcing QC is new: a cut-down Ticket QC for a panel whose reinforcing is finished but whose ticketing has not started. It shares its engine with Ticket QC through lib/vibe/ticketqc_run.py (a mode parameter) and runs only the ticketchecks.CHECKS whose evidence is the panel's modelled content — see ticketchecks.REINFORCING_CHECKS / REINFORCING_EXCLUDED for the check-by-check classification.

Design Extract and Ticket QC are arithmetic against a human-corrected spec, and they are boring in the way finished things are. Panel Lift Check has since joined them: docs/architecture-migration.md's "Never" table lists it as already migrated and as the model the whole migration plan copies, and the batch path, the --no-recommend flag and the multi-worker run are all shipped. (Until 2026-08-31 this section called it "the one under development". That was a release out of date.)

What follows is still mostly about the handling check, because that is where the open engineering questions are. It is a PCI Chapter 8 handling check: stripping, transportation, erection, with prestress credited and blockouts cutting strands. It runs in two halves across a language boundary — vibe.liftexport measures the piece in IronPython inside Revit and writes a job file; panellift reads that job file on CPython and does every piece of mechanics. The job file is kept beside the report because it is the complete input: any number in any report can be re-run on a machine with no Revit and no licence.

That boundary is the single most useful decision in the repo. Keep it. Anything about mechanics goes on the CPython side where there are tests; anything about this model goes on the Revit side.

What the check will not tell you

It refuses more than it answers, on purpose -- see "When it will not answer" in lift-check.md for the full list. What remains knowingly approximate:

The plant's rigging choice is data, not a guess. Per-stage rig_mode is built (11d626d) and the mechanics of rolling and static are different solvers with tests. The tool refuses to choose between them: a plant file that leaves a stage blank inherits the global mode, and the report's load path column says which solver produced each number.

Transportation without a dunnage rule. When a plant's knowledge file has no handling.dunnage entry, transportation still runs the old lift path and the report says so in a warning box. A plant that states lifter_rows or fraction gets a real support solve instead. See question 2.

The full-width section question (old question 3) is settled -- see below. The direction that matters has not changed: every remaining approximation below is labelled rather than silent.

---

Open engineering questions, ranked

1. Per-stage rigging mode -- settled mechanically, plant answer outstanding

Known. Ours is rolling everywhere. A commercial check (Eriksson Wall) uses Static Lift for stripping and transport and Rolling Block for erection. On the same piece with the same inserts, ours gives a stripping moment of 23.8 k-ft against their 14.1 — a factor of 1.7, and by far the largest known discrepancy in the tool.

Suspected. The whole of that gap is the rigging idealisation, not the section or the load factor. It is the first thing to fix because every stripping verdict in the tool is currently conservative by roughly that factor, which is the fastest way to lose a user's trust: a tool that fails pieces the plant has been shipping for years gets switched off.

The mechanism is built (11d626d). handling.stages[] carries rig_mode alongside multiplier, pci_case, strength and groups; blank inherits the job's mode, so nothing moved when it landed; anything that is neither rolling nor static nor blank is refused rather than quietly inherited. It is surfaced in the project config file under decisions.rig_mode, and the report's stage table carries a load path column so two stages solved on different mechanics cannot look alike on the page.

What is left is not code. Somebody has to say how this plant actually rigs each stage, and it is deliberately not defaulted to Eriksson's answer — their combination is their default, not a fact about this yard. Once it is set, re-run the piece above: if stripping lands near 14.1 k-ft on static, the 1.7× is explained and the question is closed.

2. Transportation is supports, not a lift -- settled and built

Settled. Where the piece sits on the trailer is plant knowledge, read from handling.dunnage in the plant layer:

mode	meaning
lifter_rows	dunnage under the same lines the stripping rows use
fraction	two lines inset fraction * L from each end

One plant sits on the stripping rows; another insets a fixed fraction of the span from each end. The numbers themselves live in the plant knowledge files, not in this repository.

When either mode is configured, the transportation stage carries a supports list instead of lifters. panellift solves it as a continuous beam on rigid supports -- two lines are determinate, more follow stiffness, no sling angle, no cable groups, no insert capacity check -- and the report shows dunnage lines and their reactions instead of a pick table. A blank handling.dunnage keeps the old lift path, and the report says so in a warning box; the button refuses on a misconfigured mode rather than falling back quietly.

What is left is the plant files themselves. Each plant needs its own dunnage: block in its plant knowledge file -- one rule may be the stripping rows, another a fixed fraction -- because that is exactly the layer that must not be published.

3. Effective width when the piece spans its short direction

Known. panellift/src/panellift/section.py builds the section from the full panel width minus blockouts, and statics.py distributes load across that same width. There is no reduction anywhere for how far apart the inserts are.

The worry was that this makes a panel look safer than it is. A horizontal panel erected spans its width, say 11.5 ft, while being 26.8 ft across, and it hangs from a handful of anchors along one edge rather than off a continuous line. The strip between two anchors has to carry its load sideways to reach one, and that transverse bending is nowhere in the model.

Settled, and no FE was needed. With a line support every 1-ft strip carries its own load straight to the support and the full width is right by inspection; the only question is what the discrete anchors cost. That path is a beam whose depth is the span dimension — which is why it is so stiff that the answer is not close.

Worked on a real piece, 26.83 × 11.50 ft × 8 in, four erection anchors on the top row at 3.5 / 10.5 / 16.33 / 24.08 ft:

worst gap between anchors	8.0 ft
weight per ft of edge	1,150 lb/ft
transverse beam	138 in deep × 8 in wide, S = 25,392 in³
M = wL²/8	9,200 lb-ft
transverse tension	4.3 psi, against 444 psi allowable

One percent of allowable. The full width is effective — not "probably", by two orders of magnitude — and no plate solution changes a number that small.

Where it does bite: an opening that interrupts the transverse path. The one piece with a 9.3 × 8.3 ft blockout has that 143 in depth cut to about 43 in over 9.3 ft of its edge, and the two remaining strips are separated. That is still roughly ten times the margin, but it is the geometry to redo this arithmetic on rather than assume. Note that the main span section at an opening is already modelled — NetSection — so this is only about the path sideways to an anchor.

Worth turning into a check rather than leaving as a note in a document; it is one span, one section modulus, and the numbers are already in the job file.

Related and already known: "Transverse equilibrium" and "Flexural capacity (φMn)" in the Open list at the bottom of lift-check.md.

---

The sweep

tools/sweep.py checks every WP assembly in the open model and ranks what is wrong with it. Two halves:

python tools/sweep.py            measure in Revit, then check
python tools/sweep.py --check    re-check the saved job files, no Revit

The measuring half drives tools/sweep_in_revit.py through the bridge, ten pieces a call, and only reads the model. It is resumable — a meta file means that piece is done — so stop it and start it again freely. Output goes beside the model in <model>/_ticketqc/sweep/, not into this checkout.

The --check half is the one to reach for. A job file is the complete input, so after any change to the mechanics the whole model is re-checked in about a minute with Revit closed. That is what the job files are for.

The stages come from liftexport.default_stages — what the grouping rules imply with nobody having clicked anything. Good enough to find what breaks across a model, not good enough to sign. See the next section.

What the last full sweep found

228 assemblies. 194 measured cleanly; 34 refused because their design has no spec yet, so there is no initial tension and prestress cannot be credited — run Extract Design on those designs and they unblock. Of the 194, 184 are horizontal (the assembly origin stands the width up) and 10 are vertical.

The sweep immediately earned itself. Every one of the 184 horizontal panels failed erection on the aspect-ratio check, which turned out to be a bug rather than a fact about the panels: the check read width/length, transpose() swaps those two to stand a piece up, so the ratio came back inverted — above 1.00 for every piece longer than it is wide — and a 2.33-to-1 panel was refused as "close to square". Fixed in 2663cbc by taking short over long, which has the property the check was missing: turning a piece cannot change whether it is square.

Behind that, the findings worth chasing:

WP139, WP345	genuinely over the stripping tension limit — 1.42 and 1.24 of allowable, both with CRACK. These span their length with prestress credited, so they are the most trustworthy numbers in the sweep.
WP109, WP114, WP121, WP314	no lifting inserts modelled at all. The check raises rather than refuses politely, which is worth tidying, but the finding is real: WP314 is a full-size piece with nothing to pick it up by.
WP187, WP192, WP313, WP409, WP411	the weight gate fired — measured geometry does not weigh what the model says. Usually a blockout or a thickness read wrong, and it makes the section modulus wrong in the direction that says a panel is fine.
WP215, WP217, WP318, WP322, WP326	INSERT findings at erection.

---

Deliberately not automated

The user picks the inserts, by hand, in Revit, once per stage. The button isolates the assembly in the view they are already in, ghosts everything that is not an insert to 85% transparency, and asks them to click. It does not switch views and it does not create one.

This replaced a checklist of rows the tool had grouped itself, and the reason matters: a row is the tool's guess about which inserts share a hook, and its label named one family when the row held two. Picking three lines where four were meant is unconservative and the report looks entirely normal — that is how a panel came back at 184% on three rows when it has four.

stage_audit still says when the defaults look wrong, but it is advisory now, not a veto: with every insert clicked, a bad default costs clicks rather than an answer.

So: the sweep uses the defaults because 228 pieces cannot be clicked, and its output is a map of where to look — never a signed check.

The Eriksson comparison

One piece was checked against Eriksson Wall in full, and the agreement on the parts that overlap is close:

	ours	theirs
stress at the governing station	417.4 psi	417.6
compression at stripping	667.5 psi	667.4

Those are with their moment fed into our section, which is the comparison that isolates the section from the rigging — and it is why question 1 above is about rigging and not about geometry.

The gap that cannot be closed by matching them harder: Eriksson Wall cannot model a horizontal panel at all. Its file format carries one longitudinal axis for the whole file and has no per-stage span field, so a piece that spans one way at stripping and the other at erection has nowhere to say so. Rotating the piece into a second file is unconservative, because strands are implicitly along the longitudinal axis and would come with it. 184 of the 194 pieces in this model are exactly that case, which is the reason this tool exists rather than a licence.

Eriksson Sync (the Revit exporter) was also evaluated and is not usable here as-is: its family map is a template from another job, so families in this model do not match, strands export as nothing, and the lifters in the output were invented by a default layout rather than read from the model.

---

Start here

1. Get decisions.rig_mode and handling.dunnage set in each plant's knowledge. The fields exist and work; what is missing are the plants' answers. Rigging first because it is the largest known error — a 1.7× factor on every stripping number — and nothing else is worth calibrating underneath it. This is a question for the plant, not a task for whoever reads this: ask, do not pick.

2. Run Extract Design on the designs that have no spec, then python tools/sweep.py. Second because it costs no design work and turns 34 refusals into 34 checked pieces — including every insulated horizontal panel, which is a shape the tool has never been run against. Expect it to find something; that is what happened last time.

3. Turn section 3's arithmetic into a check. Third because the engineering is already settled — the transverse path to a discrete anchor costs about 1% of allowable on a solid panel — and what is left is making the tool say so on the pieces where it might not hold, which is the ones with a large opening across the anchor line. One span, one section modulus, both already in the job file.

Do not start by adding features. span/transpose is the most load-bearing logic in the tool and until the last sweep it had only really been exercised on one piece.