@structupath/pi-steel 0.2.1 → 0.2.3

package/skills/steel-nest/SKILL.md

@@ -1,15 +1,15 @@
 ---
 name: steel-nest
-description: "Nest steel parts onto stock plates and estimate material — the plate-layout / cutting step that CAM software (SigmaNEST, Hypertherm, FANUC) does. Use this skill whenever someone mentions nesting, plate layout, plate optimization, cut list, cutting plan, yield, drop/remnant, how many sheets/plates a job needs, how much plate to buy, or laying parts out on a sheet. Also trigger when a new order/SO comes in and someone asks 'how much material', 'how many plates', 'what's the yield', or 'lay these parts out' — even if they don't say the word 'nest'. Produces a nesting layout (PDF + PNG), a cut list, yield/scrap/remnant numbers, material cost, and a DXF of the nest. Rectangular parts nest exactly; irregular parts nest by bounding box."
+description: "Nest steel parts onto compatible stock plates and estimate material — the plate-layout / cutting step that CAM software does. Use this skill whenever someone mentions nesting, plate layout, plate optimization, cut list, cutting plan, yield, remnant candidates, how many sheets/plates a job needs, how much plate to buy, or laying parts out on a sheet. Produces a verified result, packing utilization, net material yield, guarded layouts, and optional cost totals only when an explicit basis exists."
 ---
 
 # Steel Plate Nesting & Estimate
 
 ## What This Skill Does
 
-This is the in-house version of the plate-nesting step a CAM package (SigmaNEST / Hypertherm / FANUC) performs: it takes a list of parts and the plate stock on hand, packs the parts onto as few plates as possible, and tells you the yield, the drops you can reuse, the material weight, and the cost. It also draws the layout and exports a DXF.
+This is an estimating-oriented version of the plate-nesting step performed by CAM software. It validates and separates material/grade/thickness groups, packs them onto compatible stock, independently verifies placements, and reports two different metrics: bounding-footprint packing utilization and net material yield. Leftover rectangles are remnant candidates, not certified reusable stock.
 
-It exists so that the moment an order lands, anyone in the shop can get a fast, repeatable material number for quoting and a layout the cutter can follow — without waiting on the CAM seat.
+It exists so an estimator can get a fast, repeatable material number and a reviewable layout. It does not replace CAM setup or operator verification.
 
 ## What It Does Well vs. What It Doesn't
 
@@ -17,18 +17,22 @@ Be honest with the user about the boundary — it protects the shop from over-tr
 
 **Reliable:**
 - Rectangular / plate-blank parts nest **exactly** (MaxRects bin-packing with rotation).
-- Multiple plate sizes, kerf + gap spacing, edge margin (grip/clamp keep-out).
-- **Holes and rectangular cutouts** on any part — subtracted from weight/cost, rotated with the part, and cut as real geometry in the output.
-- Yield %, scrap weight, largest reusable **drop** per plate.
-- Material weight and cost (by $/lb — which also values scrap — or by $/sheet).
+- Multiple compatible plate sizes with independently verified bounds, non-overlap, and material grouping.
+- Explicit clearance ownership: edge margin is the plate-to-part keep-out; kerf plus part gap is the minimum edge-to-edge clearance between parts. No trailing kerf/gap is required at the usable plate boundary.
+- **Holes and rectangular cutouts** on verified rectangular parts — subtracted from weight/cost, rotated with the part, and emitted as cut geometry only when the complete job passes the output gate.
+- Separate packing-utilization and net-material-yield percentages with approximation labels.
+- Remnant candidates per plate, explicitly not certified reusable drops.
+- Material weight and optional cost by one explicit basis per stock entry (`cost_per_lb` or `cost_per_sheet`, never both).
 - Labeled layout (PDF + one PNG per plate).
-- **Burn-table files**: one DXF **per sheet** (`burn_plate_N.dxf`) with part outlines on layer `PROFILE` and holes on layer `HOLES`, origin at the sheet corner — ready to import into the table's CAM. Plus `nest.dxf`, an all-sheets overview.
+- **Reference files**: `reference_nest.dxf` plus `reference_plate_N.dxf`, with sheet outlines, bounding boxes, holes, and labels for estimating review.
+- **Guarded cut-geometry files**: one DXF per sheet (`burn_plate_N.dxf`) containing only closed part outlines on `PROFILE` and holes/cutouts on `HOLES`, with origin at the sheet corner. They exist only when every part is rectangular, every required part fits, and every supported hole stays inside its part.
 
 **Approximate — always flag it:**
 - **Irregular parts** (gussets, brackets, curved profiles, parts with holes) are nested by their **bounding box**, not true shape. Real yield is a little better than reported. For exact weight/cost on those, get the true cut area (in²) into the part's `area` field. This is NOT true-shape nesting like a dedicated CAM engine.
+- Any irregular part suppresses all fabrication-style DXFs for that job. The remaining PDF, PNG, report, JSON, and `reference_nest.dxf` outputs are estimating aids, not cutting instructions.
 
 **Do NOT pretend to do:**
-- **Machine-ready G-code / NC** with kerf compensation, pierce points, and lead-ins for a specific controller. That is machine-specific and safety-critical and must come from the real post-processor. The burn DXF from this skill is a geometry/import file — the table's CAM (Hypertherm ProNest, FastCAM, SigmaNEST, Lantek, or the controller's own importer) applies kerf comp, lead-ins and pierce. Say so plainly if asked for G-code; offer the DXF as the correct hand-off.
+- **Machine-ready G-code / NC** with kerf compensation, pierce points, and lead-ins for a specific controller. That is machine-specific and safety-critical and must come from the real post-processor. When a burn DXF is emitted, it is still an import geometry file that requires operator and CAM verification. Say so plainly if asked for G-code.
 
 ## Inputs to Gather
 
@@ -36,8 +40,8 @@ Everything drives a single job JSON (schema in `references/job_template.json`; a
 
 Gather three things:
 
-1. **Parts** — for each unique part: name, width × height (inches; use the bounding box for odd shapes), quantity, whether it's `rect` or `irregular`, and whether rotation is allowed (`rotatable: false` locks grain/rolling direction for anisotropic material or directional finish). If a part has **holes or cutouts** and you want them cut in the burn file (and netted out of weight), add a `holes` list — each hole's `x,y` is its center from the part's lower-left corner: round = `{"dia":, "x":, "y":}`, rectangular cutout = `{"w":, "h":, "x":, "y":}`. Holes are optional; skip them if you only need the layout/estimate.
-2. **Stock** — plate size(s) on hand (width × height × thickness), how many sheets are available (or `unlimited` to buy as needed), and price (`cost_per_lb` preferred; `cost_per_sheet` works too).
+1. **Parts** — for each unique part: name, width × height (inches; use the bounding box for odd shapes), quantity, whether it's `rect` or `irregular`, and whether rotation is allowed (`rotatable: false` locks grain/rolling direction for anisotropic material or directional finish). If a rectangular part has **holes or cutouts**, add a `holes` list — each hole's `x,y` is its center from the part's lower-left corner: round = `{"dia":, "x":, "y":}`, rectangular cutout = `{"w":, "h":, "x":, "y":}`. A supported hole must remain fully inside its part or fabrication-style DXFs are suppressed. Holes are optional; skip them if you only need the layout/estimate.
+2. **Stock** — plate size(s), explicit material, grade, and thickness, plus finite quantity or `unlimited`. A price is optional; if provided, use exactly one approved basis (`cost_per_lb` or `cost_per_sheet`) and retain its source outside this legacy JSON boundary.
 3. **Cut settings** — kerf, part gap, edge margin, material density. Sensible defaults are in the template; only ask if the user hasn't implied them. Common kerf: plasma ~0.06", oxy-fuel ~0.10", laser ~0.02", waterjet ~0.03".
 
 If a spreadsheet is provided, read it with pandas first, map columns to the part fields, and confirm your interpretation before nesting. Do not silently guess quantities or dimensions.
@@ -55,33 +59,56 @@ Write the job JSON, then run the engine:
 python3 scripts/nest.py --job <job.json> --out <outdir>
 ```
 
-Outputs land in `<outdir>/`:
+The legacy job JSON shape and command arguments remain accepted. Material, grade,
+thickness, and imperial unit basis must now be explicit at job level or on each
+part/stock entry; the engine never infers those facts from a display name. `<outdir>` is a
+publication root rather than a flat artifact directory. Every invocation creates
+`<outdir>/runs/<run-id>/` and atomically updates `<outdir>/latest-run.json`; follow
+that pointer to find the current run. This prevents an older burn file from appearing
+current after a blocked rerun.
+
+Use `--geometry-verified-only` when reference-only geometry does not satisfy the
+request. The command still publishes its QA diagnostics, but exits unsuccessfully.
+
+Each run contains:
+
+- `run-manifest.json` and `qa-report.json` — outcome, readiness, hashes, warnings, and the exact artifact allow-list
 - `layout.pdf` — every plate drawn (holes shown) + a summary page (the main deliverable)
 - `plate_1.png`, `plate_2.png`, … — one image per plate
-- `burn_plate_1.dxf`, `burn_plate_2.dxf`, … — **one DXF per sheet for the burn table** (PROFILE + HOLES layers, origin at sheet corner)
-- `nest.dxf` — all sheets side-by-side, one overview file
-- `rfq_nesting.json` — the Material / Nesting Plan / Drop Notes block for the `steel-rfq` hand-off (see below)
+- `burn_plate_1.dxf`, `burn_plate_2.dxf`, … — geometry-verified cut entities only; absent for review-required or blocked runs
+- `reference_nest.dxf` and `reference_plate_N.dxf` — explicitly reference-only layouts
+- `rfq_nesting.json` — versioned `1.0.0` Material / Nesting Plan / Remnant Candidate rows for the `steel-rfq` hand-off; absent on blocked runs
 - `report.txt` — the text report
-- `result.json` — structured result (plates, placements, holes, yield, cost) for downstream use
+- `result.json` — schema-versioned result with normalized input/configuration hashes, algorithm version, placements, verifier findings, both metrics, and cost status
+
+Exit meanings:
+
+- `0` — `ready`; requested artifacts were published and cut geometry is verified within the supported rectangular scope
+- `2` — `review_required`; safe reference outputs were published, but no burn DXF exists
+- `3` — `blocked`; validation or unplaced material prevented fabrication-style output
+- `4` — a required runtime capability is missing
+- `1` — usage or internal error
 
-The engine has no third-party build dependencies beyond `ezdxf`, `matplotlib`, and `numpy`. Install once if missing: `pip install --break-system-packages ezdxf matplotlib numpy`.
+Install the declared dependencies from the package root with
+`python3 -m pip install -r requirements-dev.txt`. Formula baking remains an optional
+capability reported by `python3 scripts/doctor.py`.
 
 ## What to Deliver
 
-Always deliver the **PDF layout** and give the headline numbers in the message: plates used, overall yield %, total material cost, and any parts that **did not fit** (the report flags these — never hide them; it means they need more or bigger stock). Offer the DXF and per-plate PNGs. If the parts were irregular, restate the bounding-box caveat so the quote isn't over-trusted.
+Always deliver the **PDF layout** and give the headline numbers in the message: plates used, packing utilization, net material yield, cost status, and aggregated quantities that did not fit. Offer the reference DXF and per-plate PNGs. Offer burn DXFs only when they were emitted by the guard, and still state that CAM/operator verification is required.
 
-Verify before presenting: the engine already checks that no parts overlap and all fit in-bounds, but sanity-check the yield and cost against the plate count (e.g., cost = plates × sheet cost, or plate weight × $/lb). If a plate shows very low yield, mention it — it's usually the tail plate and may be worth holding parts for the next order.
+Verify before presenting: require `verification.status = verified`, reconcile known cost to its recorded per-sheet or per-pound basis, and never turn a missing or incomplete cost into `$0`.
 
 ## Integration with steel-rfq
 
-The `steel-rfq` skill has a "Nesting / Drop Reference" table. This engine writes exactly that data to `rfq_nesting.json` on every run — one row per plate material with `material`, `nesting_plan`, `drop_notes`, plus `sheets_needed` (for cross-checking the estimate's assumed sheet count) and `total_cost`. When an RFQ involves plate, `steel-rfq` builds a nest job from the plate parts, runs this engine, and reads `rfq_nesting.json` straight into its table. Keep this JSON shape stable — the RFQ skill depends on those field names.
+The `steel-rfq` skill has a "Nesting / Drop Reference" table. The engine writes the versioned object `{schema_version, source_nest_result_version, rows}`. Rows remain separate by stock identity, material, grade, thickness, and sheet size, even when display names match. Resolve the current run through `latest-run.json` and reject unknown handoff versions.
 
 ## Common Variations
 
-**Mixed thickness / grade in one order** — nest each thickness as its own job (parts of different thickness can't share a plate). Run the engine once per thickness and combine the numbers in the summary.
+**Mixed thickness / grade in one order** — provide the basis on each part and stock entry. The engine creates independent compatible groups and never opens an incompatible plate.
 
-**"Just tell me how many sheets"** — still run it; the plate count is the answer, and you get the yield and cost for free. Don't estimate sheet count by dividing areas — packing loss makes that wrong.
+**"Just tell me how many sheets"** — still run it; the plate count is the answer. Cost remains absent unless an explicit basis is supplied.
 
-**Remnant/drop reuse** — add the leftover drop from a previous job as another `stock` entry (its size, `qty: 1`) so the engine tries to consume it first-ish. Note: with multiple stock sizes the engine fills them in the order listed, so list drops/offcuts first if you want them used up.
+**Remnant reuse** — output rectangles are candidates only. Measure, identify, status, and approve a candidate as inventory before supplying it as a distinct stock entry in a later estimate.
 
 **Grain / directional material** — set `rotatable: false` on those parts so the nester won't spin them 90°.

package/skills/steel-nest/references/FIXTURE_PROVENANCE.md

@@ -0,0 +1,12 @@
+# Fixture Provenance
+
+`example_job.json` and `job_template.json` are synthetic public examples created
+from scratch for pi-steel documentation and tests. They are not copied, transformed,
+rounded, renamed, or anonymized from a company, customer, vendor, bid, drawing,
+takeoff, inventory record, or production job.
+
+- Creator: StructuPath pi-steel maintainers
+- Creation method: deliberately invented geometry and identifiers
+- Public-data review: 2026-07-28
+- Commercial data: none
+- Private source artifacts: none

package/skills/steel-nest/references/example_job.json

@@ -1,6 +1,9 @@
 {
-  "job_name": "SO-4471  Conveyor Frame Brackets",
-  "customer": "Rocky Mtn Aggregate",
+  "job_name": "SYNTHETIC-DEMO-001  Generated Training Geometry",
+  "customer": "Example Customer",
+  "material": "carbon_steel",
+  "grade": "A36",
+  "unit_system": "imperial",
   "settings": {
     "kerf_in": 0.06,
     "part_gap_in": 0.25,
@@ -10,38 +13,31 @@
   },
   "stock": [
     {
-      "name": "A36 Plate 1/2\"",
-      "width": 96,
-      "height": 48,
+      "name": "Synthetic Plate",
+      "width": 60,
+      "height": 30,
       "thickness": 0.5,
-      "qty": 6,
-      "cost_per_lb": 0.92
+      "qty": 3
     }
   ],
   "parts": [
-    { "name": "Base Plate BP1", "width": 14, "height": 10, "qty": 6, "shape": "rect",
+    { "source_id": "SYNTHETIC-SRC-RECT-A", "name": "Training Rect A", "width": 11, "height": 7, "qty": 3, "shape": "rect",
       "holes": [
-        { "dia": 0.875, "x": 2,  "y": 2 },
-        { "dia": 0.875, "x": 12, "y": 2 },
-        { "dia": 0.875, "x": 2,  "y": 8 },
-        { "dia": 0.875, "x": 12, "y": 8 }
+        { "dia": 0.75, "x": 2, "y": 2 },
+        { "dia": 0.75, "x": 9, "y": 5 }
       ] },
-    { "name": "Column Cap CC1", "width": 16, "height": 16, "qty": 4, "shape": "rect",
+    { "source_id": "SYNTHETIC-SRC-RECT-B", "name": "Training Rect B", "width": 13, "height": 9, "qty": 2, "shape": "rect",
       "holes": [
-        { "dia": 1.0625, "x": 3,  "y": 3 },
-        { "dia": 1.0625, "x": 13, "y": 3 },
-        { "dia": 1.0625, "x": 3,  "y": 13 },
-        { "dia": 1.0625, "x": 13, "y": 13 }
+        { "dia": 0.625, "x": 3, "y": 3 },
+        { "dia": 0.625, "x": 10, "y": 6 }
       ] },
-    { "name": "Stiffener ST1", "width": 9, "height": 6, "qty": 20, "shape": "rect" },
-    { "name": "Gusset G1", "width": 12, "height": 12, "qty": 12, "shape": "irregular", "area": 72 },
-    { "name": "Flat Bar FB1", "width": 30, "height": 4, "qty": 10, "shape": "rect" },
-    { "name": "Cover CV1", "width": 24, "height": 18, "qty": 3, "shape": "rect",
+    { "source_id": "SYNTHETIC-SRC-IRREGULAR-C", "name": "Training Irregular C", "width": 9, "height": 8, "qty": 4, "shape": "irregular", "area": 28 },
+    { "source_id": "SYNTHETIC-SRC-RECT-D", "name": "Training Rect D", "width": 17, "height": 5, "qty": 5, "shape": "rect" },
+    { "source_id": "SYNTHETIC-SRC-RECT-E", "name": "Training Rect E", "width": 19, "height": 11, "qty": 2, "shape": "rect",
       "holes": [
-        { "w": 6, "h": 4, "x": 12, "y": 9 }
+        { "w": 5, "h": 3, "x": 9.5, "y": 5.5 }
       ] },
-    { "name": "Clip CL1", "width": 5, "height": 3, "qty": 24, "shape": "rect",
-      "holes": [ { "dia": 0.5625, "x": 2.5, "y": 1.5 } ] },
-    { "name": "Web Plate WP1", "width": 40, "height": 12, "qty": 4, "shape": "rect" }
+    { "source_id": "SYNTHETIC-SRC-RECT-F", "name": "Training Rect F", "width": 6, "height": 4, "qty": 7, "shape": "rect",
+      "holes": [ { "dia": 0.5, "x": 3, "y": 2 } ] }
   ]
 }

package/skills/steel-nest/references/job_template.json

@@ -1,8 +1,11 @@
 {
-  "job_name": "SO-XXXX  Short description",
-  "customer": "Customer name",
+  "job_name": "SYNTHETIC-DEMO-XXX  Short description",
+  "customer": "Example Customer",
+  "material": "carbon_steel",
+  "grade": "A36",
+  "unit_system": "imperial",
 
-  "_comment_settings": "Cut/gap in inches. kerf = torch cut width (plasma ~0.06, oxy ~0.1, laser ~0.02). part_gap = clearance between parts on top of kerf. edge_margin = keep-out from plate edge (clamp/grip zone). density lb/in^3: A36 steel = 0.2836, aluminum = 0.098, stainless 304 = 0.289.",
+  "_comment_settings": "Cut/gap in inches. kerf + part_gap is the minimum edge-to-edge clearance between parts. edge_margin alone is the plate-edge keep-out; no trailing kerf/gap is required at that boundary. density lb/in^3 must match the explicit material basis.",
   "settings": {
     "kerf_in": 0.06,
     "part_gap_in": 0.25,
@@ -11,28 +14,27 @@
     "density_lb_in3": 0.2836
   },
 
-  "_comment_stock": "One entry per plate size you have on hand. qty = how many sheets available (or set \"unlimited\": true to buy as many as needed). Price EITHER by cost_per_lb OR cost_per_sheet — cost_per_lb is preferred because it also values the scrap.",
+  "_comment_stock": "One entry per distinct plate size/material/grade/thickness. qty = finite sheets available or set unlimited=true. Add either cost_per_lb or cost_per_sheet from an approved project input, never both; public templates intentionally contain no pricing.",
   "stock": [
     {
       "name": "A36 Plate 1/2\"",
       "width": 96,
       "height": 48,
       "thickness": 0.5,
-      "qty": 4,
-      "cost_per_lb": 0.92
+      "qty": 4
     }
   ],
 
   "_comment_parts": "One entry per unique part. width/height in inches (bounding box for irregular parts). qty = pieces needed. rotatable=false to lock grain/rolling direction. shape: \"rect\" nests exactly; \"irregular\" nests by bounding box — add \"area\" (true cut area in^2) for exact weight/cost on those.",
   "_comment_holes": "Optional per-part \"holes\": each hole's x,y is its CENTER measured from the part's lower-left corner. Round hole = {\"dia\": D, \"x\":, \"y\":}. Rectangular cutout = {\"w\":, \"h\":, \"x\":, \"y\":}. Holes are subtracted from weight/cost, rotate with the part, and are cut as real geometry on the HOLES layer of the burn-table DXF.",
   "parts": [
-    { "name": "Part A", "width": 12, "height": 8,  "qty": 6,  "shape": "rect",
+    { "source_id": "SYNTHETIC-SRC-PART-A", "name": "Part A", "width": 12, "height": 8,  "qty": 6,  "shape": "rect",
       "holes": [
         { "dia": 0.875, "x": 2, "y": 2 },
         { "dia": 0.875, "x": 10, "y": 6 }
       ] },
-    { "name": "Part B", "width": 10, "height": 10, "qty": 4,  "shape": "irregular", "area": 62 },
-    { "name": "Part C", "width": 24, "height": 3,  "qty": 10, "shape": "rect", "rotatable": false,
+    { "source_id": "SYNTHETIC-SRC-PART-B", "name": "Part B", "width": 10, "height": 10, "qty": 4,  "shape": "irregular", "area": 62 },
+    { "source_id": "SYNTHETIC-SRC-PART-C", "name": "Part C", "width": 24, "height": 3,  "qty": 10, "shape": "rect", "rotatable": false,
       "holes": [ { "w": 3, "h": 1, "x": 12, "y": 1.5 } ] }
   ]
 }