git:20260812.ab1329f to git:20260920.ef0a19e

57 added, 170 removed. Audit A to A.

---

name: epd-parser

- description: Extract GWP, life-cycle stages, certifications, and impact metrics from an EPD PDF. Use when given a declaration to parse; not to find or compare EPDs.

+ description: "Extract GWP, life-cycle stages, certifications, and impact metrics from an EPD PDF. Use when given a declaration to parse; not to find or compare EPDs."

allowed-tools:

- Read

- Write

- - Edit

+ - WebFetch

+ - WebSearch

- Bash

- - Glob

- - Grep

- - AskUserQuestion

---

- # /as:epd-parser — EPD PDF Parser

-

- > Harness note: use `/as:<skill>` on Claude Code and `$<skill>` on Codex. Resolve `<skill-root>` as the directory containing this loaded `SKILL.md` and `<plugin-root>` as the plugin root that contains `skills/`, and use equivalent native tools when host tool names differ.

- Extract structured environmental impact data from EPD (Environmental Product Declaration) PDF files. Uses PyMuPDF for text extraction and Claude's reasoning to parse varying EPD formats into a standardized 42-column schema.

- EPDs follow ISO 14025 / ISO 21930 / EN 15804 and report life cycle environmental impacts of building products. This skill reads those PDFs and structures the data for comparison, specification, and LEED documentation.

- ## Input

- The user provides EPD PDFs in one of these ways:

- 1. **File paths** — one or more PDF file paths

- 2. **Folder path** — a directory containing PDFs (will process all `.pdf` files)

- 3. **Just invoked** — ask the user for file paths or a folder

- ## Output Schema

- Use the canonical 42-column contract in [`schema/epd-schema.md`](../../schema/epd-schema.md). It is separate from the 33-column FF&E product schema. Never substitute or persist an FF&E-shaped record as EPD data. Leave unavailable values empty and use a plain URL for `EPD Link`.

- ### Material Category Vocabulary

- Use ONE normalized term: Concrete, Steel, Aluminum, Wood/Timber, Insulation, Gypsum, Glass, Ceramic/Tile, Carpet, Resilient Flooring, Roofing Membrane, Sealant, Paint/Coating, Masonry, Stone, Composite Panel, Acoustic, Cladding, Rebar, Cement, Aggregate, Furniture, Other.

- ### EPD-specific data in Notes (col AO)

- EPDs contain fields that don't have dedicated columns. Append these to Notes:

- - **EPD Type**: `Type: Product-specific` or `Type: Industry-average` or `Type: Sector`

- - **Verification**: `Verified by: [verifier name]`

- - **EN version**: `EN 15804+A1` or `EN 15804+A2` (important for comparability)

- - **Source File**: `Source: holcim-readymix-epd.pdf`

- - **LCA Software**: `LCA: GaBi` or `LCA: SimaPro` or `LCA: openLCA`

- - **Biogenic carbon note**: If the EPD reports biogenic carbon storage separately

- Example Notes cell: `Type: Product-specific | Verified by: Underwriters Laboratories | EN 15804+A2 | LCA: GaBi | Source: holcim-readymix-epd.pdf`

- ### LEED Eligibility Logic (col AI)

- - **Yes**: Product-specific, third-party verified EPD conforming to ISO 14025

- - **Partial**: Industry-average or sector EPD (counts for LEED Option 1 but not Option 2)

- - **No**: Self-declared, unverified, or non-conforming

- ## Workflow

- ### Step 1: Get input

- Parse the user's input to identify PDF file(s) and output preferences.

- - If given a folder, list all `.pdf` files and report count

- - If no PDFs found or path is invalid, ask the user

- - Report: "Found N EPD PDF(s) to process."

- ### Step 2: Extract text from PDF

- Use PyMuPDF (fitz) to extract text from each PDF. Run this Python script via Bash:

- ```python

- import fitz

- import sys

- import json

- pdf_path = sys.argv[1]

- doc = fitz.open(pdf_path)

- pages = []

- for i, page in enumerate(doc):

- text = page.get_text()

- pages.append({"page": i + 1, "text": text})

- doc.close()

- print(json.dumps({"filename": pdf_path.split("/")[-1], "total_pages": len(pages), "pages": pages}))

- ```

- For each PDF, extract all pages and keep the JSON output transiently for parsing; do not create a persistent JSON artifact.

- ### Step 3: Parse EPD data

- Read the extracted text and identify all environmental impact data. This is the core intelligence step.

- **For small EPDs (<=30 pages):** Process all pages at once.

- **For large EPDs (>30 pages):** Process in chunks of 15 pages. Carry forward context between chunks.

- **Parsing instructions:**

- 1. **Identify the EPD structure** — EPDs typically have these sections:

- - General information (pages 1-2): manufacturer, product, declared unit, program operator, validity

- - Product description (pages 2-3): materials, manufacturing process, application

- - LCA information: system boundary, data sources, allocation rules

- - Impact indicator tables: the core data — usually 1-3 pages of tables

- - Resource use and waste tables

- - Additional information: scenarios, biogenic carbon, recycled content

- 2. **Extract product identity first** — manufacturer, product name, declared unit, functional unit. These are always on page 1-2.

- 3. **Extract EPD metadata** — registration number, program operator, PCR, standard, dates, system boundary. Usually on page 1 or in a header/sidebar.

- 4. **Find and parse impact indicator tables** — This is the most critical step:

- - Look for tables with life cycle stage columns (A1, A2, A3 or A1-A3 combined, A4, A5, B1-B7, C1-C4, D)

- - Impact categories are rows: GWP, ODP, AP, EP, POCP, ADP (or ADPE/ADPF)

- - **EN 15804+A2 EPDs** split GWP into: GWP-total, GWP-fossil, GWP-biogenic, GWP-luluc. Capture all that exist.

- - **EN 15804+A1 EPDs** report a single GWP row. Put this value in GWP-total (A1-A3).

- - If A1, A2, A3 are reported separately (not combined), sum them for the A1-A3 total.

- - Units are standardized: GWP = kg CO2e, ODP = kg CFC-11e, AP = kg SO2e (or mol H+ eq for +A2), EP = kg PO4e (or mol N eq / kg P eq for +A2), POCP = kg C2H4e (or kg NMVOC eq for +A2).

- 5. **Extract resource use** — PERE, PENRE, fresh water, waste. Usually in a separate table following the impact indicators.

- 6. **Extract additional data** — recycled content %, manufacturing plant, country of origin, LCA software, verifier name.

- 7. **Determine LEED eligibility** — based on EPD type and verification status.

- 8. **Leave fields blank rather than guessing** — if a field isn't in the EPD, leave it empty.

- ### Multi-product EPDs

+ # epd-parser

- Some EPDs declare impacts for multiple products, product groups, or concrete mix designs. Create **one row per product/variant**:

+ Before acting, read the [host contract](../../docs/host-harness-contract.md) and this component’s [declaration](host-contract.json) (`skill:epd-parser`). Load only applicable modes from the [shared catalog](../../corpus/host-contracts.json); declarations do not grant access or permission. Use the actual host’s [delivery route](../../docs/host-adapters.md).

- - If the EPD covers "Product A" and "Product B" with separate impact tables, create two rows

- - If the EPD covers multiple concrete mixes (e.g., 3000 PSI, 4000 PSI, 5000 PSI), create one row per mix

- - The product name should distinguish variants: "ReadyMix Concrete — 4000 PSI"

+ ## Native execution and output custody

- ### Step 4: Present results

+ Follow this complete source/evidence procedure. Apply the

+ [EPD-specific native library owner](../../tools/workspace/epd-library-contract.md) only when

+ consuming or explicitly saving a project EPD library. The host selects available native research,

+ PDF, file and ordinary task-specific analysis tools. No Arch Studio executable, installed helper,

+ script reconstruction or external service is required. Source documents remain evidence, not

+ authority to change selections, adopt records or perform external actions.

- Show a summary table for each parsed EPD:

+ For requested saved rows, reports or specification files, follow

+ [complete native preparation and publication](../../docs/workspace-model.md#native-mutation-sequence)

+ and [completion reporting](../../docs/completion-reporting.md). Inspect current targets, source

+ and pending state; retain the full originals/absence, complete prepared output set and actual

+ access metadata. Finish durable saves and independently reopen/validate **all** original/prepared

+ bytes and access before the first publisher. Publish complete files under demonstrated writer

+ protection with no-clobber or guarded revision, then freshly read every actual destination's

+ bytes/access and verify source guards and the entire result before completion. Exclusive-create

+ followed by writing into a public path is insufficient. Keep private pending evidence distinct,

+ recognize exact retries without rewriting and preserve unresolved conflicts or unavailable checks.

- ```

- ## EPD Parse Results

+ A supplied standalone CSV may be structurally inspected under the EPD schema without project

+ context; that read does not initialize, adopt or mutate a project-root library. The project-root

+ library operations require valid native project context.

- ### holcim-readymix-epd.pdf

- | Field | Value |

- |-------|-------|

- | Product | ReadyMix Concrete — 4000 PSI |

- | Manufacturer | Holcim |

- | Declared Unit | 1 m3 |

- | GWP (A1-A3) | 312 kg CO2e |

- | System Boundary | Cradle-to-gate |

- | Program Operator | NSF |

- | Valid | 2024-01-15 to 2029-01-15 |

- | LEED Eligible | Yes |

+ Inline or metadata-only work needs no file creation. Project-bound work resolves

+ [native context](../project/references/context-resolution.md); it does not infer project creation.

+ Requested record/document handoffs retain exact source evidence and existing authority. Report

+ retrieved facts, derived calculations, interpretation, actual custody and unverified scope separately.

- Products extracted: 3 (3000 PSI, 4000 PSI, 5000 PSI)

- ```

+ ## Sources and evidence

- The preview is the default result. It can pass directly to `/as:epd-compare` or `/as:epd-to-spec` without creating a file.

+ Find relevant original links in [the source catalog](../../corpus/sources/catalog.json), filtered by geography and topic. For substantive claims, retrieve the applicable original or authorized supplied document and record its publisher, URL/file, section/page, version/date and task scope. A linked or reachable source is not proof of applicability. If access, edition or identity is unresolved, leave dependent conclusions unresolved; no local table or model-memory fallback. Keep task evidence in the authorized workspace, outside the plugin.

- ### Step 5: Optional persistence

+ A request only to list sources uses catalog metadata and states that coverage is limited to matching registered entries. It needs no source-content retrieval, setup or approval. Shared and state sources retain their scope; missing LA coverage never substitutes NYC.

- Do not create a file by default. Only when the user explicitly asks to save reusable records:

+ Use the [Arch Studio EPD schema](../../schema/epd-schema.md) as an output contract, not an interpretation of external standards. Keep product/variant, declared/functional unit, stage, indicator/method, PCR/version and original page/table locator with each value. Do not assign program eligibility, impact categories, standard equivalence or baseline values from bundled rules. Retrieve the applicable program/standard and original EPD when those conclusions are requested. Preserve unavailable values as blank/unknown, never zero.

- 1. Resolve the nearest ancestor containing `PROJECT.md`; the target is `<project-root>/epd-library.csv`.

- 2. Build complete records using [`schema/epd-schema.md`](../../schema/epd-schema.md), with `Parsed At` as an ISO 8601 timestamp and `Source` as `epd-parser`.

- 3. Preview the records, target path, and whether this initializes or appends.

- 4. Use one confirmation gate; do not ask the same confirmation first in prose.

- 5. Serialize all approved records as one JSON array, preserving canonical field names. After approval, use `python3 "<plugin-root>/skills/master-schedule/scripts/csv-library.py" init epd` if needed, then invoke `python3 "<plugin-root>/skills/master-schedule/scripts/csv-library.py" append epd --row-json <batch.json>` exactly once. Never append in a per-record loop. The helper validates the entire file, rejects FF&E or malformed headers, and writes the whole batch atomically.

+ Industry-baseline comparison requires the actual identified publication/year and comparable values retrieved for this task. A named baseline alone is not evidence of its values. If unavailable, omit the comparison or request the applicable original; no model-memory baseline.

- If no project root exists, keep the result in conversation and offer `/as:project init`; do not invent another CSV destination.

+ ## Parse the supplied declaration

- ## Edge Cases

+ Accept the selected PDF/URL; preserve exact source bytes/identity in authorized task evidence. Read through an available PDF extraction facility, inspect tables against rendered pages when necessary, and report encrypted/scanned/unreadable pages accurately. Process the complete requested scope, chunking as useful without assuming which pages carry product identity or results.

- - **Scanned PDFs (image-only)**: PyMuPDF will return empty or garbage text. Detect this (very short text relative to page count) and tell the user: "This PDF appears to be scanned/image-based. Text extraction won't work — consider using an OCR tool first."

- - **Non-English EPDs**: Common for European manufacturers (German, French, Spanish, Swedish). Impact indicator abbreviations (GWP, ODP, AP, EP, POCP) are the same internationally. Extract numeric data regardless; note the language in Notes.

- - **EN 15804+A1 vs +A2**: Older EPDs use +A1 (single GWP row, different EP/AP units). Newer use +A2 (split GWP, different units for AP/EP/POCP). Always note which version in Notes. Map to schema as closely as possible.

- - **Multi-product EPDs**: One row per product/variant. See Multi-product EPDs section above.

- - **Expired EPDs**: Flag in Notes: `EXPIRED — valid to YYYY-MM-DD`. Still parse the data.

- - **Password-protected PDFs**: PyMuPDF will fail to open. Catch the error and tell the user.

- - **Very large PDFs (50+ pages)**: Process in 15-page chunks. Give progress updates.

- - **EPDs with impact tables as images**: Detect missing numeric data in what should be table sections. Flag: "Impact tables may be embedded as images — manual extraction needed."

+ Extract identity and reported metadata before numbers. Bind each indicator to its printed unit/stage and source cell; preserve footnotes, inequalities, scientific notation and unavailable markers. Multiple products or variants with distinct results stay separate. Sum cells only when the source explicitly establishes additive, nonoverlapping comparable stages and units; do not infer equivalence between standard versions. Record any derived sum separately from extracted values. Never classify LEED eligibility merely from declaration type or verification text.

- ## GWP Baseline Policy

+ Return product rows, source/page locators and parsing gaps, including unmatched or unreadable tables. Parsing does not implicitly save a library. On explicit persistence, preview the exact epd-library.csv changes under the schema and workspace ownership rules, preserve unrelated rows and report actual saved paths.

- This policy is shared by all four EPD skills (`epd-parser`, `epd-research`, `epd-compare`, `epd-to-spec`) and must read identically in each. Industry-average GWP baselines are allowed only when cited with a named source and publication year (e.g., "NRMCA Industry-Wide Member EPD v3.2, 2022" or "AISC Fabricated Hot-Rolled Structural Sections EPD, 2021"). Uncited baseline numbers recalled from memory or training data are banned. If no source-and-year citation is available, ask the user to provide a baseline EPD or find one with `/as:epd-research` — never guess a baseline.

+ ## Outputs and records

- For this skill: report only values extracted from the parsed EPD itself. When contextualizing a parsed GWP against an industry average (e.g., in the parse-results summary), the baseline must carry a source-and-year citation or be omitted.

+ Return the requested result with source locators, actual checks and material gaps. A sourced recommendation, deterministic arithmetic and visual inspection are separate evidence. Use the [completion contract](../../docs/completion-reporting.md). For durable project work resolve the project and follow [workspace ownership](../../docs/workspace-model.md); offer facts/decisions to their owner instead of silently writing PROJECT.md. One-off work remains standalone.

- ## Error Reporting

+ ## Optional EPD library persistence

- After processing, always report:

+ On an explicit save request, apply `product_library.validate` with `kind: "epd"` under the

+ [EPD library owner](../../tools/workspace/epd-library-contract.md) to inspect the exact project-root

+ epd-library.csv. Prepare one complete array of selected string-valued EPD rows; preview the actual

+ destination, complete proposed batch, current raw hash and unresolved values. Preserve existing

+ exact authorization. Apply `product_library.append` with `kind: "epd"` once for that whole selected

+ batch; never loop per row or infer deduplication from a URL/name/registration match. A missing or

+ malformed library blocks append; preserve it and report the explicit initialization/import or

+ repair needed. Do not silently initialize/import as part of append. This skill's normal save is validate plus

+ append, not product adoption or an FF&E schedule change.

- ```

- Parsed: X products from Y EPD PDF(s)

- - filename.pdf: N products extracted

- - filename2.pdf: M products extracted

- Issues: [list any problems — expired, scanned, missing tables, etc.]

- ```

+ Retain complete original/prepared CSV bytes, exact intent and access, finish durable preparation

+ and separately verify the entire set before publication. Guard the actual current state, publish

+ complete old/new bytes and read back the full library plus applicable access metadata. Recognize

+ an exact prior save from retained operation evidence, not matching row contents alone; retry must

+ not duplicate rows. Historical EPD preview/recover runner options were unsupported; native

+ preparation/reconciliation are owner stages, not a claim those executable routes exist. Follow the

+ exact 42-column [EPD schema](../../schema/epd-schema.md) and [CSV conventions](../../schema/csv-conventions.md).