@structupath/pi-steel 0.2.1 → 0.2.3

package/skills/steel-rfq/SKILL.md

@@ -1,179 +1,97 @@
 ---
 name: steel-rfq
-description: "Generate standardized Request for Quotation (RFQ) spreadsheets from steel estimate takeoff files. Use this skill whenever someone mentions RFQ, request for quote, vendor quote, material quote, sending a material list to vendors, quoting steel, or getting pricing from a supplier. Also trigger when someone uploads a steel estimate or takeoff spreadsheet and wants to send it out for pricing. Even if they just say 'I need to send this to my vendor' or 'get me prices on this material' — that's an RFQ."
+description: "Compile a deterministic draft steel RFQ workbook from a validated canonical estimate package or an exact-header legacy workbook. Use for material quote lists, RFQ spreadsheets, or versioned nesting references. Produces artifacts only; it never sends, awards, or authorizes purchasing."
 ---
 
-# Steel RFQ Generator
-
-## What This Skill Does
-
-This skill takes a steel estimate/takeoff spreadsheet (.xlsx) and produces a clean, standardized RFQ spreadsheet that can be sent directly to steel vendors. The output is always an Excel file with a consistent layout so every vendor gets the same professional format regardless of who creates it.
-
-The RFQ format was designed around how steel vendors actually work — materials grouped by type (W-shapes, plates, flat bar) so vendors can quickly identify what they have in stock, quote pricing, and flag what they don't carry.
-
-## Company Profile (required setup)
-
-The RFQ carries the requesting company's identity. Load it from
-`assets/company-profile.json` in this skill's directory (copy
-`company-profile.example.json` and edit). If the file is missing, ask the
-user for their company name, city/state, and payment terms before
-generating, and offer to save the answers as `company-profile.json` for
-next time.
-
-Profile fields:
-- `company_name` — appears in the header and terms & conditions
-- `city_state` — appears in the header (e.g., "Denver, CO")
-- `payment_terms` — default "Net 30 from date of delivery"
-- `quote_validity_days` — default 30
-- `logo` — optional filename in `assets/` to embed top-left
-
-Never invent company details. If the profile is incomplete, ask.
-
-## Input
-
-Always a steel estimate spreadsheet (.xlsx). These files typically have:
-- A "Steel Takeoff" sheet (or similar) with line items for structural members, plates, and connection hardware
-- Item numbers (A-01, B-01, C-01, etc.), categories, descriptions, sizes, quantities, stock lengths, and weights
-- Items marked "BY OTHERS" (typically purlins) that are NOT part of the fabricator's scope
-
-The first step is always to read and understand the takeoff data before generating the RFQ.
-
-## Reading the Estimate
-
-1. Use pandas to read all sheets: `pd.ExcelFile(path)` then inspect sheet names
-2. Find the takeoff sheet (look for "Takeoff", "Steel Takeoff", "Material List", "BOM", or the sheet with item-level steel data)
-3. Read the full sheet with `header=None` to capture all rows including section headers
-4. Identify the data structure:
-   - Section headers (e.g., "A. MAIN BUILDING — W-SHAPES")
-   - Column headers (Item, Category, Description, Size, Qty, Length, Weight, Stock Purchase, Purchase Wt, Notes)
-   - Line items with actual material data
-   - Items with "BY OTHERS" in the description — these get **excluded**
-   - Subtotal and total rows
-
-## RFQ Output Format
-
-The output is always a single .xlsx file with this exact structure:
-
-### Header Block (Rows 1–3)
-- **Row 1**: "REQUEST FOR QUOTATION — Structural Steel" — dark blue background (#1F3864), white bold Arial 14pt, merged across all columns
-- **Row 2**: "[Project Name] | [Company Name] — [City, ST]" — same dark blue, white bold Arial 11pt
-- **Row 3**: "Date Issued: [today] | Response Requested By: _______________ | Project Location: [location]" — same dark blue, white Arial 10pt
-
-### Vendor Info Block (Rows 4–6)
-Fillable fields for the vendor:
-- Row 5: Company Name (merged A–B, input in C–E yellow) | Contact Name (merged F–G, input in H–J yellow)
-- Row 6: Phone/Email (merged A–B, input in C–E yellow) | Quote Valid Until (merged F–G, input in H–J yellow)
-
-### Instructions Row (Row 7)
-Single merged row with italic gray text explaining how to fill out the yellow columns. Text:
-> "Instructions: Please fill in the YELLOW columns (Unit Price, Total Price, Availability, Lead Time, Alternate Size, Notes). Mark Availability as 'In Stock', 'Lead Time', or 'Unavailable'. If suggesting an alternate size, list it and adjust pricing accordingly."
-
-### Column Headers (Row 8)
-14 columns with medium blue background (#2E75B6), white bold Arial 10pt:
-
-| Column | Header | Width | Purpose |
-|--------|--------|-------|---------|
-| A | Item | 7 | Item number from estimate (A-01, C-02, E-01, etc.) |
-| B | Category | 13 | Columns, Girders, Plate, Flat Bar, etc. |
-| C | Description | 38 | Full description including which structure it belongs to |
-| D | Size / Designation | 22 | AISC shape or plate dimensions |
-| E | Grade | 12 | A992 Gr.50, A572 Gr.50, A36, etc. |
-| F | Qty | 6 | Number of pieces or sticks needed |
-| G | Stock Length / Size | 20 | How it's being purchased (e.g., "3 sticks × 30′") |
-| H | Est. Purchase Wt (lbs) | 20 | Weight from the estimate |
-| I | Unit Price ($) | 14 | **VENDOR FILLS** — yellow background |
-| J | Total Price ($) | 14 | **VENDOR FILLS** — yellow background |
-| K | Availability | 14 | **VENDOR FILLS** — yellow background |
-| L | Lead Time (days) | 14 | **VENDOR FILLS** — yellow background |
-| M | Alternate Size | 18 | **VENDOR FILLS** — yellow background |
-| N | Notes | 30 | **VENDOR FILLS** — yellow background |
-
-Vendor columns (I–N) get a darker gold header (#BF8F00) to distinguish them from the material data columns.
-
-### Material Data Rows
-
-**Grouping**: Always group by material type, not by structure. The three groups are:
-1. **W-SHAPES — [Grade]** (columns and girders from all structures combined)
-2. **PLATE STOCK — [Grade]** (all plate material)
-3. **FLAT BAR STOCK — [Grade]** (all flat bar material)
-
-Each group gets a section header row: merged across all columns, medium blue background, white bold text.
-
-**Data rows**:
-- Alternate row shading: light blue (#D6E4F0) and white
-- Vendor columns (I–N) always have yellow background (#FFF2CC) regardless of row
-- Weight column (H) formatted as `#,##0`
-- Price columns (I–J) formatted as `$#,##0.00`
-- All cells have thin borders
-
-**Filtering rules**:
-- EXCLUDE any item where the description contains "BY OTHERS" (purlins, etc.)
-- EXCLUDE any item where Qty = 0
-- If the estimate has a "Stock Purchase" section (Section E or similar) with consolidated purchase items for plates/flat bar, use those instead of the individual connection plate items. The stock purchase items represent what's actually being ordered (full sheets, full bars), which is what the vendor needs to quote.
-- Keep individual W-shape items because each shape/length combination matters for vendor stock
-
-### Totals Row
-- "TOTAL PURCHASE WEIGHT / PRICE" label merged A–G, right-aligned bold
-- Column H: `=SUM(H[first]:H[last])` formula for total weight, green background (#E2EFDA)
-- Column J: `=SUM(J[first]:J[last])` formula for total price, green background
-
-### Nesting / Drop Reference Table
-Below the totals (skip a row), add a reference section:
-- Header: "NESTING / DROP REFERENCE (For Fabricator Use)" — dark blue bold text
-- Three columns: Material | Nesting Plan | Drop Notes
-- Column headers with medium blue background
-- One row per material showing the nesting layout and expected drop from the estimate
-- This helps cross-check vendor stock lengths against the cutting plan
-
-### Standard Terms & Conditions
-Below the nesting table (skip a row), add:
-- Header: "TERMS & CONDITIONS" — dark blue bold text
-- Include these standard terms, each on its own row, substituting the company name and payment terms from the company profile:
-
-1. **Delivery**: All material to be delivered FOB jobsite unless otherwise agreed. Vendor to confirm freight costs separately.
-2. **Mill Certifications**: Mill test reports (MTRs) required for all structural steel per AISC/AWS standards. Certs must accompany delivery.
-3. **Payment Terms**: [payment_terms from profile] unless otherwise negotiated in writing.
-4. **Material Standards**: All wide-flange shapes to meet ASTM A992. All plate and bar to meet grade specified on this RFQ (A572 Gr.50 or A36).
-5. **Substitutions**: No substitutions without prior written approval from [Company Name]. If quoting alternate sizes, clearly note in the "Alternate Size" column.
-6. **Quote Validity**: Quoted prices to remain firm for [quote_validity_days] days from date of quote unless otherwise stated.
-7. **Inspection**: [Company Name] reserves the right to inspect material upon delivery and reject material not meeting specifications.
-8. **Cancellation**: Orders may be cancelled without penalty if material has not shipped. Restocking fees, if any, to be stated in quote.
-
-### Branding / Logo
-If the company profile names a logo file and it exists in the skill's `assets/` directory, insert it in cell A1 area (top-left) and adjust the header text to not overlap. Otherwise use the text header as described above.
-
-## Print Setup
-- Orientation: Landscape
-- Fit to width: 1 page
-- Fit to height: 0 (auto)
-- Print title rows: Row 8 (column headers repeat on each page)
-
-## File Naming
-Output file: `[ProjectName]_RFQ_Material_List.xlsx`
-- Extract project name from the estimate file (look in "Project Info" sheet or the first rows of the takeoff)
-- Replace spaces with underscores
-- Example: `Cherokee_Boys_RFQ_Material_List.xlsx`
-
-## Step-by-Step Workflow
-
-1. Load the company profile (or collect it from the user — see Company Profile above)
-2. Read the uploaded estimate file with pandas to understand its structure
-3. Identify the takeoff sheet and parse all line items
-4. Filter out "BY OTHERS" items and zero-quantity items
-5. Group remaining items by material type (W-shapes → Plates → Flat Bar)
-6. If there's a stock purchase section, use those for plates/flat bar instead of individual pieces
-7. Build the RFQ spreadsheet using openpyxl following the format above
-8. Add formulas for totals and verify the SUM ranges cover exactly the data rows
-9. Add nesting/drop reference from the estimate notes — or, if the `steel-nest` skill has been run for this job, read its `rfq_nesting.json` output straight into the table
-10. Add standard terms & conditions with profile values substituted
-11. Insert logo if configured
-12. Save the file, then run `python3 scripts/recalc.py <output.xlsx>` so formula values are computed (openpyxl writes formulas but never calculates them)
-13. Verify no formula errors and present the file to the user
-
-## Common Variations
-
-**Multiple structures in one project**: Combine all materials into one RFQ, but note which structure each item belongs to in the Description column (e.g., "W12×65 Columns (Bldg A)").
-
-**Plate stock with nesting**: When plates are purchased as full sheets and then cut, show the full sheet as the line item (that's what the vendor ships) and put the cutting plan in the nesting reference table.
-
-**Mixed grades**: Group by material type first, then note the grade in each row. If a project has A992, A572, and A36, they all appear in the appropriate material type section with grade clearly marked.
+# Steel RFQ Compiler
+
+## Boundary
+
+This skill creates a reviewable draft workbook. It does not contact vendors,
+send RFQs, select a quote, approve substitutions, award work, or authorize a
+purchase. Every workbook and manifest records `DRAFT — NOT SENT OR AWARDED`.
+
+## Required inputs
+
+- Canonical estimate-package JSON `1.0.0`, or the conservative exact-header
+  legacy XLSX contract in `references/rfq-input.md`.
+- Explicit issue date.
+- A runtime company profile with company name, city/state, and an approved,
+  hash-bound terms template.
+- Optional versioned nesting handoff `1.0.0`.
+
+Resolve the company profile from `PI_STEEL_CONFIG`, project-local ignored
+`.pi-steel/company-profile.json`, then the platform user-config directory.
+Never write runtime identity, terms, or logos into this installed skill.
+
+The shipped `assets/company-profile.example.json` is deliberately unapproved.
+Copy it to a runtime config location, supply reviewed terms and approval
+metadata, recompute the exact UTF-8 SHA-256, then change status to `approved`.
+
+## Deterministic scope and purchasing rules
+
+- Canonical `intent` controls scope. Description text cannot exclude an item.
+- `allowance`, `exclusion`, and `by_others` never become vendor quantities.
+- Zero quantity in the legacy adapter maps to excluded scope.
+- Consolidated purchased stock replaces fabricated pieces only through explicit
+  `dimensions.replaces_item_ids`.
+- Lines remain traceable by source and item ID.
+- Groups and nesting references remain separate by material, grade, thickness,
+  size, and stock identity.
+- Missing identity, approved terms, supported versions, or valid input blocks
+  workbook generation.
+
+## Workbook contract
+
+The compiler owns:
+
+- `RFQ Draft` and hidden `RFQ Metadata` sheets.
+- Dark-blue title block, fillable vendor block, fixed A:N headers, grouped
+  purchase lines, yellow vendor-response cells, formulas, borders, widths, and
+  alternating row fills.
+- Exact total formulas covering the deterministic material range.
+- Versioned nesting/remnant reference rows with visible reference-only labels.
+- Approved terms content and approval lineage.
+- Landscape print setup, one-page width, repeated row-8 headers, and stable
+  project-derived filename.
+
+A missing optional logo falls back to the text header and does not invent
+branding.
+
+## Run
+
+```bash
+python3 scripts/generate-rfq.py \
+  --input <estimate-package.json-or-exact-legacy.xlsx> \
+  --nest <optional-rfq_nesting.json> \
+  --issued-date <YYYY-MM-DD> \
+  --project-location "Example City, ST" \
+  --out <publication-root>
+```
+
+Each invocation publishes an isolated run with `run-manifest.json`,
+`qa-report.json`, the draft `.xlsx` when gates pass, and
+`workbook-semantic.json`.
+
+Exit codes:
+
+- `0`: draft RFQ ready for human review.
+- `2`: draft generated with review-required warnings or reference-only nesting.
+- `3`: blocked; diagnostics only, no workbook.
+- `1`: usage or internal input error.
+
+## Formula calculation status
+
+The compiler always requests full recalculation on open. If LibreOffice is
+available and succeeds, QA says `baked_via_libreoffice`. Otherwise QA says
+`deferred_recalculate_on_open`; it never claims cached formula values were
+computed.
+
+## Verification before delivery
+
+- Confirm the manifest outcome and artifact allow-list.
+- Confirm workbook metadata remains draft-only.
+- Confirm every purchase line is traceable and typed in scope.
+- Confirm totals formulas span the intended material rows.
+- Confirm nesting rows preserve material/grade/thickness/size boundaries.
+- Report deferred formula caching and reference-only nesting visibly.

package/skills/steel-rfq/assets/company-profile.example.json

@@ -1,7 +1,13 @@
 {
-  "company_name": "Acme Steel Fabrication",
-  "city_state": "Denver, CO",
-  "payment_terms": "Net 30 from date of delivery",
-  "quote_validity_days": 30,
-  "logo": null
+  "company_name": "Example Fabricator",
+  "city_state": "Example City, ST",
+  "logo": null,
+  "terms_template": {
+    "template_id": "EXAMPLE-TERMS-UNAPPROVED",
+    "content": "ENTER SYNTHETICALLY APPROVED TERMS TEMPLATE",
+    "content_hash": "607418ebf6466ee2f5f45b7ea63603baba276b5f95860cd8a079dfa1d652fe6b",
+    "approver": "ENTER APPROVER",
+    "approval_date": null,
+    "status": "draft"
+  }
 }

package/skills/steel-rfq/references/rfq-input.md

@@ -0,0 +1,58 @@
+# RFQ compiler input contract
+
+The deterministic compiler accepts either:
+
+1. A canonical estimate package at schema version `1.0.0`.
+2. A legacy `.xlsx` workbook with a sheet named exactly `Steel Takeoff` and
+   these exact row-1 headers:
+
+   `Source_ID`, `Item_ID`, `Scope`, `Description`, `Material`, `Grade`,
+   `Thickness`, `Size`, `Qty`, `Currency`, `Purchase Weight`.
+
+The legacy adapter is intentionally narrow. `Scope` must be exactly `IN SCOPE`,
+`BY OTHERS`, or `EXCLUDED`; descriptions never control scope. Missing stable
+IDs, renamed columns, inferred section headers, and ambiguous quantities are
+rejected for explicit mapping outside the compiler.
+
+Canonical filtering uses `intent`. Allowances, exclusions, and by-others items
+never become vendor lines. A purchased-stock or hardware item replaces
+fabricated items only when its `dimensions.replaces_item_ids` explicitly names
+those canonical item IDs.
+
+The optional nesting input is the versioned `rfq_nesting.json` object:
+
+```json
+{
+  "schema_version": "1.0.0",
+  "source_nest_result_version": "1.0.0",
+  "geometry_readiness": "geometry_verified",
+  "rows": []
+}
+```
+
+Unknown versions are blocked. Rows stay separate by stock identity, material,
+grade, thickness, and sheet size.
+
+The company profile is resolved in this order:
+
+1. File named by `PI_STEEL_CONFIG`.
+2. Ignored project file `.pi-steel/company-profile.json` beside the input.
+3. Platform user configuration at `pi-steel/company-profile.json`.
+
+Runtime profiles must not be saved under the installed package. The profile
+requires company identity and an approved `terms_template` whose SHA-256
+matches its exact UTF-8 content. Editing terms invalidates approval. A missing
+optional logo uses the text header.
+
+The command requires an explicit issue date:
+
+```bash
+python3 scripts/generate-rfq.py \
+  --input estimate-package.json \
+  --nest rfq_nesting.json \
+  --issued-date 2026-07-28 \
+  --out published/
+```
+
+Every workbook is marked `DRAFT — NOT SENT OR AWARDED`. The compiler contains
+no send, award, vendor-selection, or purchase-authorization action.