@structupath/pi-steel 0.2.1 → 0.2.3

package/skills/steel-estimate/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: steel-estimate
+description: "Build a deterministic, review-gated steel estimate package from canonical estimate JSON. Use when a complete takeoff-to-nest-to-draft-RFQ workflow is needed with validation, lineage, QA, and isolated run artifacts."
+---
+
+# Steel Estimate Package
+
+## Boundary
+
+This skill produces estimating and draft purchasing artifacts for human review.
+It does not send an RFQ, select a vendor, approve substitutions, award work, or
+authorize a purchase. The workbook remains `DRAFT — NOT SENT OR AWARDED`.
+
+## Required inputs
+
+- Canonical estimate-package JSON at schema version `1.0.0`.
+- Explicit prepared and RFQ issue dates.
+- A runtime company profile accepted by `steel-rfq`.
+- Plate stock compatible with every plate part by material, grade, thickness,
+  and usable dimensions.
+
+Use `references/estimate-package-example.json` as a synthetic input example.
+The company profile resolution and approval rules are documented by
+`../steel-rfq/SKILL.md`.
+
+## Workflow and gates
+
+The orchestrator composes the shared estimate validator, deterministic nesting
+engine, RFQ compiler, and run publisher. It does not duplicate their
+calculations.
+
+1. Normalize and validate the canonical package.
+2. Build the typed BOM projection without converting exclusions or allowances
+   into vendor quantities.
+3. Nest plate parts only within compatible stock groups.
+4. Verify placements and retain diagnostic nest artifacts.
+5. Compile a draft RFQ only when validation, placement, and company-profile
+   gates pass.
+6. Publish an isolated run manifest and QA report.
+
+Validation failures, unplaced parts, invalid company data, failed nest
+verification, or required rendering dependencies block workbook generation.
+Complete bounding-box nests for irregular geometry may produce a workbook, but
+the run and workbook remain explicitly review-required. Reference DXF is never
+burn-ready DXF.
+
+## Run
+
+```bash
+python3 scripts/build-estimate-package.py \
+  --input <estimate-package.json> \
+  --out <publication-root> \
+  --prepared-date <YYYY-MM-DD> \
+  --issued-date <YYYY-MM-DD> \
+  --project-location "Example City, ST"
+```
+
+Use `--no-render` when only JSON and workbook artifacts are needed. Use
+`--no-bake` to defer formula calculation to spreadsheet open. Explicit dates
+and unchanged input/configuration yield stable semantic artifacts.
+
+Exit codes:
+
+- `0`: package is ready for human RFQ review.
+- `2`: a draft exists, but warnings or reference-only geometry require review.
+- `3`: blocked; diagnostics are published and no workbook is produced.
+- `4`: a required runtime dependency is missing; no workbook is produced.
+- `1`: usage, file, or input parsing error.
+
+See `references/output-contract.md` for artifact and status semantics.
+
+## Review acknowledgements
+
+The acknowledgement helper records a decision already made by a named human.
+It never infers a disposition, chooses an actor or timestamp, or changes source
+facts. Read the finding in `qa-report.json`, then supply every decision field
+explicitly and write a new package:
+
+```bash
+python3 scripts/acknowledge-finding.py \
+  --input <estimate-package.json> \
+  --output <reviewed-estimate-package.json> \
+  --finding-id <finding-id> \
+  --input-hash <finding-relevant-hash> \
+  --actor "<reviewer name>" \
+  --timestamp <ISO-8601-date-time> \
+  --disposition accepted
+```
+
+Allowed dispositions are `accepted`, `rejected`, and `deferred`. An accepted
+warning is cleared only while its relevant input hash still matches. Recording
+acceptance of a blocker does not waive that blocker. Re-run the estimate
+pipeline with the newly written package and inspect the new QA report.
+
+## Dependency recovery
+
+If a command reports exit `4` or names a missing capability, run the package
+doctor from the package root:
+
+```bash
+python3 scripts/doctor.py --json
+```
+
+Install the calculation, workbook, PNG, and DXF dependencies from
+`requirements.txt`. Full PDF and LibreOffice-assisted checks also require the
+system tools documented by `requirements-render.txt`.
+`requirements-tested.txt` records the exact dependency versions exercised by
+CI; it is a reproducibility reference, not the general installation range. Run
+the doctor again after installation before retrying the estimate.
+
+## Delivery checks
+
+- Read `run-manifest.json` and `qa-report.json`; do not infer readiness from a
+  workbook filename.
+- Confirm there are no blocker findings or unplaced parts.
+- Confirm material, grade, thickness, source IDs, and replacement lineage.
+- Surface every warning and approximation to the reviewer.
+- Treat all workbook and rendered artifacts according to their manifest
+  readiness labels.

package/skills/steel-estimate/references/estimate-package-example.json

@@ -0,0 +1,91 @@
+{
+  "schema_version": "1.0.0",
+  "project": {
+    "project_id": "SYNTHETIC-EXAMPLE-001",
+    "name": "Synthetic Estimate Example",
+    "revision": {
+      "revision_id": "SYNTHETIC-REV-A",
+      "source_document": "SYNTHETIC-SOURCE-001"
+    }
+  },
+  "unit_system": "imperial",
+  "items": [
+    {
+      "intent": "fabricated_part",
+      "source_id": "SYNTHETIC-SRC-P1",
+      "item_id": "item:synthetic-example-p1",
+      "quantity": 2,
+      "mark": "P1",
+      "description": "Synthetic rectangular plate",
+      "material": "carbon_steel",
+      "grade": "A36",
+      "geometry": {
+        "shape": "rect",
+        "width": 8,
+        "height": 6,
+        "thickness": 0.5,
+        "holes": [],
+        "rotatable": true
+      },
+      "source_evidence": [
+        {
+          "source": "SYNTHETIC-SOURCE-001",
+          "locator": "SYNTHETIC-DETAIL-P1"
+        }
+      ]
+    },
+    {
+      "intent": "purchased_stock",
+      "source_id": "SYNTHETIC-SRC-S1",
+      "item_id": "item:synthetic-example-s1",
+      "quantity": 1,
+      "description": "Synthetic stock plate purchase",
+      "material": "carbon_steel",
+      "grade": "A36",
+      "specification": "PLATE",
+      "dimensions": {
+        "category": "PLATE STOCK",
+        "width": 24,
+        "height": 12,
+        "thickness": 0.5,
+        "size": "24 x 12 x 0.5",
+        "replaces_item_ids": [
+          "item:synthetic-example-p1"
+        ]
+      },
+      "source_evidence": [
+        {
+          "source": "SYNTHETIC-SOURCE-001",
+          "locator": "SYNTHETIC-STOCK-S1"
+        }
+      ]
+    }
+  ],
+  "stock": [
+    {
+      "stock_kind": "purchasable",
+      "inventory_id": "SYNTHETIC-STOCK-A36",
+      "material": "carbon_steel",
+      "grade": "A36",
+      "width": 24,
+      "height": 12,
+      "thickness": 0.5,
+      "quantity": 1,
+      "status": "available"
+    }
+  ],
+  "commercial_basis": {
+    "currency": "USD",
+    "costs": []
+  },
+  "review": {
+    "status": "validated",
+    "findings": [],
+    "acknowledgements": []
+  },
+  "lineage": {
+    "source_type": "synthetic_example",
+    "source_hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+    "configuration_hash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
+  }
+}

package/skills/steel-estimate/references/output-contract.md

@@ -0,0 +1,47 @@
+# Estimate package output contract
+
+Each invocation publishes an immutable directory at `runs/<run-id>/` and
+updates `latest-run.json` only after the run is complete. Read the manifest
+before using any artifact.
+
+## Core artifacts
+
+| Artifact | Purpose | Produced when |
+| --- | --- | --- |
+| `estimate-package.json` | Deterministically ordered canonical input | Always |
+| `normalized-bom.json` | Typed BOM and calculated weight projection | Always |
+| `nest-result.json` | Placements, verification, utilization, and unplaced parts | Valid input contains plate parts |
+| `rfq-nesting.json` | Versioned nesting lineage for RFQ compilation | A nest was attempted |
+| `inventory-consumption.json` | Confirmed on-hand sheets consumed and corresponding RFQ demand reduction | Eligible on-hand inventory was consumed |
+| `qa-report.json` | Findings, approximations, gate decisions, and recalculation status | Always |
+| `run-manifest.json` | Input/configuration hashes and artifact hashes/readiness | Always |
+| `<project>_RFQ_Material_List.xlsx` | Draft RFQ workbook | All blocking gates pass |
+| `workbook-semantic.json` | Stable workbook content projection | Workbook exists |
+
+Rendered PDF, PNG, and DXF files are optional. Reference artifacts are not
+fabrication authority. Burn DXF is eligible only for a fully ready run with
+verified exact geometry.
+
+## Outcomes
+
+- `ready` / `rfq_ready_for_review`: all gates pass; the workbook is still a
+  draft requiring human review.
+- `review_required` / `rfq_draft_review_required`: a workbook exists, but
+  warnings or reference-only geometry must be resolved or accepted by a human.
+- `blocked`: diagnostics exist, but no workbook exists.
+- `dependency_missing`: required rendering support is absent and no workbook
+  exists.
+
+Unplaced parts use `blocked` with package status `nested_partial`; their nest
+diagnostics remain available. A validation failure stops before nesting.
+
+## Determinism and lineage
+
+Canonical JSON is sorted before publication. The manifest records the canonical
+input hash, effective configuration hash, tool/schema versions, explicit dates,
+and SHA-256 for each artifact. Run IDs and filesystem paths are volatile and do
+not affect the semantic hash. A changed revision, quantity, profile, date, or
+nest setting changes the applicable downstream lineage.
+
+Never treat warnings, approximations, exclusions, allowances, or source
+evidence as presentation-only metadata. They are part of the review contract.

package/skills/steel-estimate/scripts/acknowledge-finding.py

@@ -0,0 +1,193 @@
+#!/usr/bin/env python3
+"""Record one explicit human review decision in a canonical estimate package."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import tempfile
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+
+SHARED_ROOT = Path(__file__).resolve().parents[2] / "_shared"
+if str(SHARED_ROOT) not in sys.path:
+    sys.path.insert(0, str(SHARED_ROOT))
+from bootstrap import bootstrap_shared  # noqa: E402
+
+bootstrap_shared(__file__)
+from pi_steel import canonical_json_bytes  # noqa: E402
+from pi_steel.validation import (  # noqa: E402
+    acknowledge_finding,
+    validate_estimate_package,
+)
+
+
+class AcknowledgementInputError(ValueError):
+    """Raised when an explicit acknowledgement cannot be recorded safely."""
+
+
+def _valid_timestamp(value: str) -> bool:
+    try:
+        parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError:
+        return False
+    return "T" in value and parsed.tzinfo is not None
+
+
+def _findings_for_decision(
+    package: dict[str, Any], current_hash: str
+) -> list[dict[str, Any]]:
+    generated = validate_estimate_package(package).findings
+    supplied = package.get("review", {}).get("findings", [])
+    combined: dict[tuple[str, str], dict[str, Any]] = {}
+    for finding in [*generated, *supplied]:
+        finding_id = finding.get("finding_id")
+        relevant_hash = finding.get("relevant_hash")
+        if isinstance(finding_id, str) and isinstance(relevant_hash, str):
+            combined[(finding_id, relevant_hash)] = finding
+    return [
+        finding
+        for finding in combined.values()
+        if finding.get("relevant_hash") == current_hash
+    ]
+
+
+def record_acknowledgement(args: argparse.Namespace) -> dict[str, Any]:
+    input_path = Path(args.input).resolve()
+    output_path = Path(args.output).resolve()
+    if input_path == output_path:
+        raise AcknowledgementInputError(
+            "--output must be a new file; the source package is never overwritten"
+        )
+    if output_path.exists():
+        raise AcknowledgementInputError(
+            f"output already exists: {output_path}"
+        )
+    if not args.actor.strip():
+        raise AcknowledgementInputError("--actor must name the human reviewer")
+    if not _valid_timestamp(args.timestamp):
+        raise AcknowledgementInputError(
+            "--timestamp must be an explicit ISO-8601 date-time"
+        )
+
+    try:
+        package = json.loads(input_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise AcknowledgementInputError(
+            f"estimate package could not be read: {exc}"
+        ) from exc
+    if not isinstance(package, dict):
+        raise AcknowledgementInputError("estimate package must be a JSON object")
+
+    validation = validate_estimate_package(package)
+    if args.input_hash != validation.input_hash:
+        raise AcknowledgementInputError(
+            "--input-hash is stale for the current estimate input"
+        )
+    matches = [
+        finding
+        for finding in _findings_for_decision(package, validation.input_hash)
+        if finding["finding_id"] == args.finding_id
+    ]
+    if not matches:
+        stale = [
+            finding
+            for finding in package.get("review", {}).get("findings", [])
+            if finding.get("finding_id") == args.finding_id
+        ]
+        if stale:
+            raise AcknowledgementInputError(
+                "finding exists but is stale for the current estimate input hash"
+            )
+        raise AcknowledgementInputError(
+            "finding ID is not active for the current estimate input"
+        )
+    if len(matches) != 1:
+        raise AcknowledgementInputError(
+            "finding ID is ambiguous for the current estimate input"
+        )
+    finding = matches[0]
+    duplicate = any(
+        acknowledgement.get("finding_id") == args.finding_id
+        and acknowledgement.get("input_hash") == validation.input_hash
+        and acknowledgement.get("actor") == args.actor.strip()
+        and acknowledgement.get("timestamp") == args.timestamp
+        and acknowledgement.get("disposition") == args.disposition
+        for acknowledgement in package.get("review", {}).get(
+            "acknowledgements", []
+        )
+    )
+    if duplicate:
+        raise AcknowledgementInputError(
+            "this exact acknowledgement is already recorded"
+        )
+
+    acknowledgement = acknowledge_finding(
+        package,
+        finding,
+        actor=args.actor.strip(),
+        timestamp=args.timestamp,
+        disposition=args.disposition,
+    )
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    file_descriptor, temporary_name = tempfile.mkstemp(
+        prefix=f".{output_path.name}.", dir=output_path.parent
+    )
+    try:
+        with os.fdopen(file_descriptor, "wb") as stream:
+            stream.write(canonical_json_bytes(package))
+        os.link(temporary_name, output_path)
+    finally:
+        if os.path.exists(temporary_name):
+            os.unlink(temporary_name)
+    return acknowledgement
+
+
+def parser() -> argparse.ArgumentParser:
+    result = argparse.ArgumentParser(description=__doc__)
+    result.add_argument("--input", required=True)
+    result.add_argument("--output", required=True)
+    result.add_argument("--finding-id", required=True)
+    result.add_argument(
+        "--input-hash",
+        required=True,
+        help="Relevant estimate input hash copied from the reviewed finding.",
+    )
+    result.add_argument("--actor", required=True)
+    result.add_argument("--timestamp", required=True)
+    result.add_argument(
+        "--disposition",
+        required=True,
+        choices=("accepted", "rejected", "deferred"),
+    )
+    return result
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parser().parse_args(argv)
+    try:
+        acknowledgement = record_acknowledgement(args)
+    except AcknowledgementInputError as exc:
+        print(f"Acknowledgement failed: {exc}", file=sys.stderr)
+        return 1
+    print(
+        json.dumps(
+            {
+                "finding_id": acknowledgement["finding_id"],
+                "disposition": acknowledgement["disposition"],
+                "input_hash": acknowledgement["input_hash"],
+                "recorded": True,
+            },
+            sort_keys=True,
+            separators=(",", ":"),
+        )
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())