Pilot: buyer-gated product agent and local union fringe proof

PRODUCT_AGENT.md

@@ -0,0 +1,77 @@
+# SafeAgent product agent: operating contract
+
+Goal: find an existing, funded, costly operational problem where SafeAgent's
+cross-source evidence and execution receipts add value. The current first
+hypothesis is **independent union fringe remittance proof** for contractors.
+Do not describe a market as validated until an outside operator supplies
+authorized records, confirms a previously unknown actionable discrepancy or
+meaningful time saved, and pays for continued use.
+
+## Buyer loop (daily research)
+
+1. Search public operator and buyer sources: contractor finance associations,
+   benefit fund audit forums, published procurement requests, named customer
+   accounts, and vendor case studies. Record source date, URL, exact firsthand
+   problem, current spend, buyer role, existing workaround, and whether the
+   writer is an operator, a vendor, or another tool builder.
+2. Score a candidate higher for a current paid workaround and a record-backed
+   cross-system discrepancy; lower for generic interest or an easily solved
+   spreadsheet/check-constraint problem. Avoid contacts without a visible
+   budget owner or means to inspect real records.
+3. Propose at most three named, verifiable buyer candidates per run. Describe
+   a specific no-call, read-only pilot for each and an explicit reason the
+   existing tools might already solve it. State when there are none.
+4. Never send mail, messages, invitations, or public comments as part of
+   scouting. Never scrape private contacts or use employer data. Surface
+   draft outreach for review, with exact recipient identity and source URL.
+
+## Build loop (weekly)
+
+1. Re-evaluate product direction using buyer evidence, including evidence
+   against the current hypothesis. Prefer a small supported change over
+   additional generic SafeAgent features. Existing software such as
+   LaborAid and LCPcertified already performs important validation.
+2. Reproduce a real, bounded discrepancy with synthetic or authorized data.
+   Keep inputs local and read-only. Confirm explicit fund-specific calculation
+   and rounding rules with a domain operator; never infer them from marketing.
+3. Work on a new branch based on current `main`, run a meaningful regression,
+   and open a draft PR with the observed failure, behavior change, tests,
+   limitations, and buyer evidence. Never merge or deploy automatically.
+4. Review the operating contract itself when evidence changes the priorities;
+   propose edits in the same draft PR with reasons and an exit criterion.
+5. Stop the build for that run if no new buyer evidence or reproducible failure
+   supports a change. Report the finding instead of generating busywork.
+
+## Product acceptance gates
+
+- Accuracy: Missing, conflicting, or stale rates create findings. A report
+  can only claim that provided records matched. A fund total receipt does not
+  prove individual worker credit, and a local calculation is not legal advice.
+- Scale: replace SafeAgent Control's known factorial matching path before
+  large datasets. Demonstrate period-sized input without silently dropped
+  rows or incorrect ambiguity resolution.
+- Security: use synthetic fixture data in GitHub; process real worker records
+  only with operator authorization in a controlled local environment.
+- Commercial: seek one paid continuation after a reproducible discrepancy or
+  documented recurring time saving. Publishing packages, gaining installs,
+  receiving technical reviews, and gaining social followers do not count.
+
+## Existing assets to reuse when justified
+
+SafeAgent Control's independent matching and source adapters; the Python
+package for local processing; claim/settle for a later human sign-off gate;
+n8n for scheduled ingestion; evidence bundles and the dashboard for review.
+The n8n v0.2.5 node is limited to ten test calls per IP and is not a production
+path. x402 pay-per-call is not an enterprise contract mechanism. Preserve
+cryptographic source digests without publishing payroll data. The Stripe
+EC-009 test is a payment boundary experiment, not customer validation.
+
+## Starting buyer and incumbent sources
+
+- [DOL WH-347 instructions](https://www.dol.gov/agencies/whd/forms/wh347)
+- [SMACNA Miami Valley chapter directory](https://portal.smacna.org/eweb/DynamicPage.aspx?webcode=ChapterDirectory)
+- [CFMA chapters](https://beta.cfma.org/chapters)
+- [IFEBP collection procedures](https://www.ifebp.org/education---events/educational-program-schedule/collection-procedures-institute)
+- [LaborAid contractor product](https://laboraid.com/contractor)
+- [LCPcertified product](https://lcptracker.com/lcpcertified/)
+- [ThirdLine named contingency audit](https://www.thirdline.io/case-studies/virginia-beach-contingency-audit)

products/fringe_proof/.gitignore

@@ -0,0 +1,2 @@
+__pycache__/
+*.pyc

products/fringe_proof/BUYER_EVIDENCE.md

@@ -0,0 +1,22 @@
+# Firsthand buyer signals (research leads, not customers)
+
+As of 2026-09-25, these people publicly described actual operational work.
+None has requested SafeAgent, supplied data, or agreed to pay. Verify that
+the issue is still open and that existing software does not already fix it.
+Do not send outreach from an unattended agent.
+
+| Priority | Operator's public statement | Pilot hypothesis and important counterpoint |
+| --- | --- | --- |
+| 1 | [Thomas Cornellier, CEO of TSI/Exterior Wall Systems](https://cafe.cfma.org/discussion/payroll-software-for-union-contractors-1?hlmlt=VT), wrote on 2025-10-15 that the company runs union payroll in house and existing solutions leave manual work. | Ask whether comparing time, payroll, remittance and fund receipt for one period would uncover a discrepancy. The thread recommended Foundation, Sage, and Miter; determine whether a purchase since resolved the problem. |
+| 2 | [Shawn Erickson, CFO of C.J. Erickson Plumbing](https://cafe.cfma.org/discussion/updating-employee-wagesfringes-in-lcp-tracker-1?hlmlt=VT), asked on 2025-06-10 whether a new union rate requires updating each worker's LCPtracker record individually. A reply described weekly uploads plus manual fringe record changes. | Offer a pre-submission rate-change check across payroll and reported fringe for a pay period. The question is over a year old and may already be solved; do not assume current demand. |
+| 3 | [Nicholas Siano, controller of Northstar Refrigeration](https://cafe.cfma.org/discussion/miter-for-union-shop-payroll-buildopssage-intacct), described on 2025-11-11 an existing BuildOps → Sage Intacct setup and evaluation of Miter for complex union and certified payroll. | Ask about records that diverge across the three tools before importing any data. Forum replies in 2026 report Miter works well elsewhere; existing software may remove this gap. |
+
+Other firsthand signal: an [anonymous construction owner](https://www.reddit.com/r/Payroll/comments/1ra0mhd/need_help_fixing_davisbacon_certified_payroll/)
+described subcontractor sign-in sheets disagreeing with certified payroll,
+and was weighing an employee versus an outsourced service. Identity, budget,
+and authenticity have not been verified; do not count as a named lead.
+
+Price and incumbent context: [LaborAid publishes contractor pricing](https://laboraid.com/contractor),
+and [LCPcertified](https://lcptracker.com/lcpcertified/) already validates
+reports. Published pricing and public forum questions show category spending
+and workarounds, not SafeAgent product-market fit.

products/fringe_proof/README.md

@@ -0,0 +1,62 @@
+# SafeAgent Control: Fringe Proof (pilot slice)
+
+A local, read-only check of **provided** payroll hours, effective-dated fund
+rates, worker-level remittance lines, and aggregate fund receipts. It never
+initiates payroll or payment. No employer or worker data is sent to SafeAgent.
+
+The included synthetic example demonstrates a $8.00 discrepancy: a fund
+acknowledges exactly the submitted $160.00, while the approved rate schedule
+and covered hours imply $168.00 for that worker after a mid-period rate change.
+An acknowledgment for an aggregate fund amount cannot establish worker-level
+credit or a legally compliant contribution.
+
+Run with Python 3.10+ and no third-party dependencies:
+
+```bash
+cd products/fringe_proof
+python reconcile.py \
+  --payroll fixtures/payroll.csv --rates fixtures/rates.csv \
+  --remittance fixtures/remittance.csv --fund-ack fixtures/fund_ack.csv \
+  --period-start 2026-09-01 --period-end 2026-09-07 \
+  --output /tmp/fringe-proof-report.json
+```
+
+Exit code 2 means the report contains findings. Exit code 0 means the
+**provided records** matched within this narrow comparison; it does not
+certify wage compliance, fund credit, or completeness of the input exports.
+Input SHA-256 digests and a canonical report digest are saved in the JSON.
+Keep real input files and reports in an access-controlled local location;
+never commit them to GitHub.
+
+## Required columns
+
+| CSV | Columns |
+| --- | --- |
+| payroll | `employee_id,work_date,local,classification,covered_hours` |
+| rates | `local,classification,fund,effective_from,effective_to,rate_per_hour` |
+| remittance | `employee_id,local,classification,fund,reported_hours,reported_amount` |
+| fund_ack | `local,fund,amount_received` |
+
+Rates must be supplied and approved by the operator. `effective_to` may be
+blank. One unambiguous rate for each fund and work date is required. Remittance
+amounts/hours may be negative for corrections; this pilot aggregates them by
+worker, local, classification and fund. Fund receipts are compared by local
+and fund for this period; if the fund issues separate batches, aggregate them
+under the operator's documented process before using this CSV. The pilot uses
+half-up rounding at the worker/fund period total. An operator must confirm
+the applicable fund agreement uses that rule before interpreting amounts.
+
+The product question is whether independent cross-source checks catch a
+previously unknown, actionable discrepancy, or remove meaningful manual
+review time. Current competitors already validate payroll reports and automate
+remittances. This code is a test of a narrower gap, not market validation.
+
+## Next engineering gate
+
+SafeAgent Control's existing matching prototype has a reported factorial
+slowdown above nine claims. Replace that matching path and establish a
+representative large-period benchmark before adapting it for a real employer.
+Do not add automatic certification or fund payments without a verified source
+of rules and an explicit human review workflow. The existing SafeAgent
+claim/settle layer can then gate a sign-off; n8n, Python, MCP, dashboard,
+and evidence receipts can import, display, or preserve the reviewed result.

products/fringe_proof/fixtures/fund_ack.csv

@@ -0,0 +1,2 @@
+local,fund,amount_received
+LOCAL-24,HEALTH,190.00

products/fringe_proof/fixtures/payroll.csv

@@ -0,0 +1,4 @@
+employee_id,work_date,local,classification,covered_hours
+WORKER-001,2026-09-01,LOCAL-24,journeyworker,8
+WORKER-001,2026-09-02,LOCAL-24,journeyworker,8
+WORKER-002,2026-09-02,LOCAL-24,apprentice,8

products/fringe_proof/fixtures/rates.csv

@@ -0,0 +1,4 @@
+local,classification,fund,effective_from,effective_to,rate_per_hour
+LOCAL-24,journeyworker,HEALTH,2026-01-01,2026-09-01,10.00
+LOCAL-24,journeyworker,HEALTH,2026-09-02,,11.00
+LOCAL-24,apprentice,HEALTH,2026-01-01,,5.00

products/fringe_proof/fixtures/remittance.csv

@@ -0,0 +1,3 @@
+employee_id,local,classification,fund,reported_hours,reported_amount
+WORKER-001,LOCAL-24,journeyworker,HEALTH,16,160.00
+WORKER-002,LOCAL-24,apprentice,HEALTH,6,30.00