From a53f277a093e8f36842d16e33b3f22a4428fe86e Mon Sep 17 00:00:00 2001 From: anusbutt Date: Sat, 25 Jul 2026 16:12:48 +0500 Subject: [PATCH] fix(008): stop publishing prospect data and correct stale profile guidance MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Doc/consistency audit of the public repo against the shipped features. **Prospect data was public.** `candidates.csv` — 108 real businesses, 52 with scraped email addresses, 108 distinct real domains — was tracked. It was added by 0c5ac04, the commit that removed the other internal artifacts, so it slipped in while the surrounding cleanup happened. It is also the default `--out` of `prospector source`, so a normal run drops it in the working tree ready to be committed by accident. Untracked and gitignored, along with the DM ledger and `*.local.csv`. Session 1 deliberately redacted prospect lists from this repo; this restores that decision. NOTE: untracking removes it from HEAD only — the file remains in git history and must be treated as already disclosed. **The drafting instructions gated a Facebook claim on evidence that cannot exist.** CONSTRAINTS.md still allowed the possessive channel phrases ("your page", "your inbox", ...) when the model could cite an `fb_*` record and had been told the signal was strong. Feature 008 deleted every FB evidence kind and retired the channel signal, so that condition is now unsatisfiable — and the code already rejects those phrases unconditionally. The instruction file was therefore weaker than the validator and described a gate that no longer exists. Now banned outright, with the removal explained so it is not reintroduced. Two related fixes: the citation example no longer offers `fb_link_1` as a sample id, and the writing guide no longer suggests opening on a Facebook page link. **Config documentation was incomplete.** `PROSPECTOR_VAULT` is read by config.py but appeared in neither the README table nor `.env.example`; the Gmail client/token paths were missing from the table; and `.env.example` predated profiles entirely, so it never mentioned `PROSPECTOR_PROFILE` or `PROSPECTOR_PROFILES`. All now documented in both places. Also: CONTRIBUTING gains an explicit "never commit prospect data" convention, the bug-report template's example command passes --profile so a new user does not land on an interactive prompt, and the PR checklist wording is consistent with v7.0.0. Co-Authored-By: Claude Opus 5 --- .env.example | 11 ++ .github/ISSUE_TEMPLATE/bug_report.md | 2 +- .gitignore | 8 ++ CONTRIBUTING.md | 5 + README.md | 3 + candidates.csv | 109 ------------------ .../profiles/duct-cleaning/CONSTRAINTS.md | 21 ++-- .../duct-cleaning/skills/write-cold-email.md | 6 +- 8 files changed, 45 insertions(+), 120 deletions(-) delete mode 100644 candidates.csv diff --git a/.env.example b/.env.example index e629026..88eff17 100644 --- a/.env.example +++ b/.env.example @@ -11,6 +11,17 @@ OPENROUTER_API_KEY= # Optional: Hunter.io email-name enrichment (skipped when absent) #HUNTER_API_KEY= +# --- Offer profiles (feature 008) --- +# Default profile, so --profile can be omitted. Without either, an interactive +# run lists the available profiles and asks; a non-interactive one fails. +#PROSPECTOR_PROFILE=duct-cleaning +# Extra profile directory, searched BEFORE ./profiles/ and before the profiles +# bundled with the package. Your own directory always wins. +#PROSPECTOR_PROFILES=/path/to/my/profiles + +# Optional: vault output folder (default: Vault/Outreach). --vault overrides it. +#PROSPECTOR_VAULT=Vault/Outreach + # --- Approved-send (features 003/004) --- # Provider: gmail (Gmail API, default) or smtp (authenticated SMTP, e.g. Zoho). #PROSPECTOR_SEND_PROVIDER=smtp diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index f04f4bf..9284d3d 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -12,7 +12,7 @@ labels: bug ## Command you ran ```bash -# e.g. prospector run companies.csv --limit 3 +# e.g. prospector run companies.csv --profile duct-cleaning --limit 3 ``` ## Expected vs actual diff --git a/.gitignore b/.gitignore index 658fa05..d072ee6 100644 --- a/.gitignore +++ b/.gitignore @@ -17,6 +17,14 @@ send_ledger.jsonl Vault/ samples/ +# Prospect data must never be committed: these files hold real businesses' +# names, addresses and websites. `candidates.csv` is the default --out of +# `prospector source`, so it appears in the working tree on a normal run. +candidates.csv +*candidates*.csv +dm_ledger.jsonl +*.local.csv + # Internal development method — not part of the public project. # These stay on the maintainer's machine and are intentionally untracked. .specify/ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0f4fa81..80fc825 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -132,6 +132,11 @@ fixes should include a test that fails before the fix and passes after. frameworks or agent/orchestration machinery. - Never hardcode secrets. Credentials come from the gitignored `.env`; never log or commit them. +- **Never commit prospect data.** Real company names, addresses, websites and + scraped emails belong to third parties and must stay local. The vault, + `candidates.csv` (the default `--out` of `prospector source`), the send ledger + and `samples/` are all gitignored for this reason. Use fictional data in tests, + fixtures, issues and PR output. ## Commit and PR conventions diff --git a/README.md b/README.md index 6318a34..094be80 100644 --- a/README.md +++ b/README.md @@ -183,6 +183,7 @@ Secrets are loaded from the gitignored `.env` file. | `OPENROUTER_MODEL` | No | Defaults to `anthropic/claude-sonnet-4.5`. | | `PROSPECTOR_PROFILE` | No | Default profile name, so `--profile` can be omitted. | | `PROSPECTOR_PROFILES` | No | Extra profile directory, searched before `./profiles/`. | +| `PROSPECTOR_VAULT` | No | Vault output folder; defaults to `Vault/Outreach`. `--vault` overrides it. | | `GOOGLE_PLACES_API_KEY` | For `source` | Required for discovery. During `run`, its absence enables the DuckDuckGo fallback. | | `HUNTER_API_KEY` | No | Enables email-name enrichment at medium confidence. | | `PROSPECTOR_SEND_PROVIDER` | No | `gmail` (default) or `smtp`. | @@ -197,6 +198,8 @@ Secrets are loaded from the gitignored `.env` file. | `PROSPECTOR_SEND_CAPS` | No | Weekly cap ramp; defaults to `15,30,60,100`. | | `PROSPECTOR_SEND_DELAY` | No | Delay range in seconds; defaults to `30,90`. | | `PROSPECTOR_LEDGER` | No | Ledger path; defaults to `send_ledger.jsonl`. | +| `PROSPECTOR_GMAIL_CLIENT` | No | Gmail OAuth client secret; defaults to `secrets/gmail_client_secret.json`. | +| `PROSPECTOR_GMAIL_TOKEN` | No | Stored Gmail token; defaults to `secrets/gmail_token.json`. | Gmail OAuth files live under `secrets/`; the send ledger remains local. Both locations are excluded from version control. diff --git a/candidates.csv b/candidates.csv deleted file mode 100644 index e6b493b..0000000 --- a/candidates.csv +++ /dev/null @@ -1,109 +0,0 @@ -company,email,website,city,ad_signal -MainDuct Inc.,hello@mainduct.com,mainduct.com,"Brooklyn, NY",pixel -OS Air-Care & Chimney Cleaning,osaircare@gmail.com,os-air-care-chimneycleaning.com,"New York, NY",pixel -VENT CLEANERS Air Duct And Vent Cleaning Los Angeles,ventcleanersla@vent-cleaners.com,vent-cleaners.com,"Los Angeles, CA",pixel -Lowe's Air Duct Cleaning,,lowesair.com,"Chicago, IL",pixel -Mr. Duct,,mrductcleaning.com,"Chicago, IL",pixel -Air Flows Chicago - Belmont,info@airflowschicago.com,airflowschicago.com,"Chicago, IL",pixel -Angel's Duct Cleaning Services Chicago,,angelsductcleaning.com,"Chicago, IL",pixel -"Four Seasons Heating, Air Conditioning, Plumbing, Sewer & Electric",,fourseasonsheatingcooling.com,"Chicago, IL",pixel -Dr. Air Duct Cleaning,leads@drairducttx.com,drairducttx.com,"Dallas, TX",pixel -SafeAir Duct & Chimney,office@safeairductchimney.com,safeairductchimney.com,"Dallas, TX",pixel -Dryer Vent Superheroes of Dallas,,dryerventheroes.com,"Dallas, TX",pixel -Clean Air Houston Pro,,cleanairhoustonpro.com,"Houston, TX",pixel -AllDay Air Duct Cleaning & Dryer Vent Cleaning of Houston,,bestairducthouston.com,"Houston, TX",pixel -Space City Air Duct Cleaning,spacecityac@yahoo.com,airductcleaninghtx.com,"Richmond, TX",pixel -Atlantic Duct Cleaning,,atlanticductcleaning.com,"Fairfax, VA",pixel -AirWiz Duct Cleaning,,airwizcleanair.com,"Germantown, MD",pixel -E Cleaning Duct & Vent Cleaning,info@ecleaning-duct-vent-cleaning.com,ecleaning-duct-vent-cleaning.com,"King of Prussia, PA",pixel -Air Duct Dynasty - Air Duct Cleaning Philadelphia,service@airductdynasty.com,airductdynasty.com,"Huntingdon Valley, PA",pixel -Ace Duct Cleaning Inc,aceductcleaningnj@gmail.com,aceductcleaning.com,"Cherry Hill Township, NJ",pixel -Air of America Air Duct & Dryer Vent Cleaning Services,,airofamericaus.com,"Alpharetta, GA",pixel -Hurricane Air Duct Cleaning Services,hurricanellc15@gmail.com,hurricanellc.com,"Dunwoody, GA",pixel -Daffy Ducts,,daffyducts.com,"Snellville, GA",pixel -Zerorez,,zerorezatlanta.com,"Norcross, GA",pixel -Integrity Air Care,,integrityaircare.com,"Sandy Springs, GA",pixel -Duct Masters Cleaning,info@ductmasterscleaning.com,ductmasterscleaning.com,"Miami Beach, FL",pixel -Air Duct Cleaning Miami,airductcleaningmiamiflorida@gmail.com,airductcleaningmiamifl.com,"Hallandale Beach, FL",pixel -Florida Clean Air Plus,contact@floridacleanairplus.com,floridacleanairplus.com,"North Miami Beach, FL",pixel -Zerorez,,zerorez.com,"Phoenix, AZ",pixel -A Z Air Duct,info@azairduct.com,azairduct.com,"Tempe, AZ",pixel -Delta Clean Air,office@deltaairductcleaning.com,deltaairductcleaning.com,"Boston, MA",pixel -Green Line Air Duct Cleaning,green.line@mail.com,greenlineairduct.com,"Quincy, MA",pixel -Anderson Air Duct Cleaning,,andersonairductcleaning.com,"Centerville, MA",pixel -RKM Heating and Air Conditioning,,rkmair.com,"Riverside, CA",pixel -Drew’s dryer vent cleaning,drewsdvc@gmail.com,drewsdryerventcleaning.com,"Riverside, CA",pixel -Direct AC,info@directac.com,directac.com,"Riverside, CA",pixel -Safety King Air Duct Cleaning,info@safetyking.com,safetyking.com,"Shelby Township, MI",pixel -Amistee Air Duct Cleaning and Insulation,,amistee.com,"Novi, MI",pixel -Zeppelin Cleaning Services,,zepservices.com,"St Clair Shores, MI",pixel -Ductz of Mid Michigan,,ductz.com,"Jackson, MI",pixel -Seattle Dryer Vent Cleaning,info@seattledryerventcleaning.com,seattledryerventcleaning.com,"Seattle, WA",pixel -Capitol Duct Cleaning,office@capitolductcleaning.com,capitolductcleaning.com,"Spanaway, WA",pixel -Alpine Specialty Services,,alpineclean.com,"Mountlake Terrace, WA",pixel -Greenwood Heating and Home Services,info@greenwoodheating.com,greenwoodheating.com,"Seattle, WA",pixel -Sonic Air Duct,info@sonicairduct.com,sonicairduct.com,"Bellevue, WA",pixel -Evergreen Home Heating and Energy,,evergreenhomeheatingandenergy.com,"Seattle, WA",pixel -AirGanic,hello@airganic.com,airganic.com,"Edmonds, WA",pixel -The Duct Cleaners,,seattleductcleaners.com,"Lynnwood, WA",pixel -Kura Home,info@kurahome.com,kurahome.com,"Golden Valley, MN",pixel -Twin Cities Finest,,twincitiesfinest.com,"St Paul, MN",pixel -Gray Duct Heating • Cooling • Air Duct Cleaning,,grayducttechnologies.com,"Savage, MN",pixel -Sky Clean Air,,skycleanair.com,"San Diego, CA",pixel -Express Air Duct Cleaning,,express-airductcleaning.com,"Tampa, FL",pixel -Clean Sweep Duct Cleaning & Air Conditioning,,cleansweepductsac.com,"Tampa, FL",pixel -Bright Air Duct Cleaning,info@brightairductcleaning.com,brightairductcleaning.com,"Tampa, FL",pixel -Clean Air Pros,info@cleanairprosfl.com,cleanairprosfl.com,"Temple Terrace, FL",pixel -Air Titans,support@airtitans.com,airtitans.com,"Tampa, FL",pixel -Monster Vac,info@monstervac.com,monstervac.com,"Englewood, CO",pixel -Apex Clean Air AC & Heating Repair,denver@apexcleanair.com,apexcleanair.com,"Denver, CO",pixel -Delintz Dryer Vent & Air Duct Cleaning,delintzco@outlook.com,delintzcolorado.com,"Brighton, CO",pixel -True Ducts,contact@trueducts.com,trueducts.com,"Baltimore, MD",pixel -"Air Duct Pros, Inc.",mwarfield@airductprosinc.com,airductprosinc.com,"Baltimore, MD",pixel -Pure Air Duct Cleaning Services,customerservice@pureairllc.com,pureairllc.com,"Owings Mills, MD",pixel -Hydro Clean,,hydro-clean.net,"Halethorpe, MD",pixel -Fresh Air Ducts,freshairducts29@gmail.com,freshairductsllc.com,"Owings Mills, MD",pixel -SafeAir Duct Care,,safeair2.com,"Imperial, MO",pixel -Classic Aire Care,,classicairecare.com,"St. Louis, MO",pixel -Hoffmann Brothers,,hoffmannbros.com,"Brentwood, MO",pixel -Cardinal Carpet & Air Duct Cleaning,mark.er.mueller@gmail.com,cardinalcarpetcleaner.com,"Wildwood, MO",pixel -Atmosphere Air Care,,atmosphereaircare.com,"University City, MO",pixel -Seliga Heating and Cooling,,seligaheatingandcooling.com,"St. Louis, MO",pixel -Deep Breath,,deepbreathflorida.com,"Orlando, FL",pixel -Air Flow Solutions,info@airflowsolutionsusa.com,airflowsolutionsusa.com,"Charlotte, NC",pixel -COIT Cleaning and Restoration,info@charlotte.coit.com,coit.com,"Fort Mill, SC",pixel -Patriot Dryer Vent Cleaning,info@cleanmydryervent.org,cleanmydryervent.org,"San Antonio, TX",pixel -America's Best Duct Cleaning and Sanitization,greggarcia349@gmail.com,americasbestairductcleaning.com,"San Antonio, TX",pixel -Southern Air duct Cleaning,,southernairductcleaning.com,"San Antonio, TX",pixel -Green Home Services - Duct Cleaning in San Antonio & Austin,support@green-home-services.com,green-home-services.com,"San Antonio, TX",pixel -Green Quality Air,,greenqualityair.com,"San Antonio, TX",pixel -Greenwood Duct Cleaning,,greenwoodairductcleaning.com,"San Antonio, TX",pixel -Willard Power Vac - Air Duct Cleaning,,willardductcleaning.com,"Portland, OR",pixel -PNW Duct Cleaning,info@pnwductcleaning.com,pnwductcleaning.com,"Portland, OR",pixel -Better Air Northwest,,betterairnorthwest.com,"Portland, OR",pixel -Power Vac LLC,,powervac.org,"Vancouver, WA",pixel -All Pro Duct Cleaning LLC,allpronw@gmail.com,allproductcleaningnw.com,"Vancouver, WA",pixel -Best Solution Services,bestsolutionsservicesllc@gmail.com,bestsolutionservices.com,"Portland, OR",pixel -Air Duct Cleaners LLC,,airductcleanersca.com,"Sacramento, CA",pixel -California Air Duct Cleaning,,calairductcleaning.com,"Roseville, CA",pixel -Superior Air Duct Cleaning,,superiorairduct.com,"New Brighton, PA",pixel -Sears Carpet & Air Duct Cleaning of Pittsburgh,,searsclean.com,"Pittsburgh, PA",pixel -Bactronix Corp.,,bactronix.com,"Moon Township, PA",pixel -Mold Medics,,moldmedics.com,"Carnegie, PA",pixel -Absolute Heating & Air,,goabsoluteair.com,"Pittsburgh, PA",pixel -Air Central,info@aircentralusa.com,aircentralusa.com,"Austin, TX",pixel -AusTex Air Duct Cleaning,austexductcleaning@gmail.com,austexairductcleaningservice.com,"Austin, TX",pixel -Duct-Pro,info@duct-pro.com,duct-pro.com,"Las Vegas, NV",pixel -Nevada Residential Services Air Conditioning & Heating,info@nrs.vegas,nrs.vegas,"Las Vegas, NV",pixel -LV Air Duct Cleaning,roseroiase333@gmail.com,lv-air-duct-cleaning.ueniweb.com,"Las Vegas, NV",pixel -Unified Air Duct,,uairduct.com,"Las Vegas, NV",pixel -J & J Air Duct Cleaning & Decontamination,jandjairductcleaning@cox.net,jjairductcleaning.com,"Las Vegas, NV",pixel -Air Supply Heating and Cooling,,airsupplyinclv.com,"Las Vegas, NV",pixel -"Super Service Cooling, Heating & Plumbing",,mysuperservice.com,"Las Vegas, NV",pixel -"Quality Comfort Home Services HVAC, Plumbing, Duct Cleaning",,myqualitycomfort.com,"Cincinnati, OH",pixel -Apollo Home,,apollohome.com,"Cincinnati, OH",pixel -One Hour Heating & Air Conditioning,retailmarketing@authoritybrands.co,onehourheatandair.com,"Cincinnati, OH",pixel -Service Experts Cincinnati,,serviceexperts.com,"Sharonville, OH",pixel -Teasdale Fenton Cleaning & Property Restoration,,teasdalefenton.com,"Cincinnati, OH",pixel -Dry Effect,,dryeffect.com,"Cincinnati, OH",pixel -Voda Cleaning & Restoration of Cincinnati,,myvoda.com,"Cincinnati, OH",pixel diff --git a/prospector/profiles/duct-cleaning/CONSTRAINTS.md b/prospector/profiles/duct-cleaning/CONSTRAINTS.md index ab7ec2a..2fd878d 100644 --- a/prospector/profiles/duct-cleaning/CONSTRAINTS.md +++ b/prospector/profiles/duct-cleaning/CONSTRAINTS.md @@ -41,8 +41,8 @@ program owns. If you write a name yourself, the draft is rejected. `cites` is a list of identifiers, and **it must never be empty**. You are given an evidence catalogue for this company. Each entry has an `id` -like `about_page_1`, `hook_source_1`, or `fb_link_1`. Those ids are what you -cite. +like `about_page_1`, `hook_source_1`, or `email_published_1`. Those ids are what +you cite. Cite only ids that appear in the catalogue you were given. - **A block that says something about the prospect** cites the evidence id(s) that support it. If you write "you have been serving Dallas for 22 @@ -85,18 +85,23 @@ The word "your" is what turns one into the other: | "when someone messages **your page** at 9pm" | "when someone messages a business at 9pm" | | "It watches **your inbox**" | "It watches the page inbox" | -Banned outright unless the evidence catalogue contains an `fb_*` record, you -cite it in that same block, **and** you were told the signal is strong: +**Banned outright — there is no evidence that makes these acceptable:** "your facebook page", "your fb page", "your page", "your inbox", "your messenger", "your dms", "your direct messages", "messages your page". +There used to be an exception here for a cited `fb_*` evidence record on a +strong channel signal. **That exception is gone.** The tool no longer researches, +scores, or records anything about a prospect's Facebook usage — there is no +`fb_*` record to cite and no signal to be told about — so a possessive channel +phrase can never be justified. A validator rejects these unconditionally. + A page appearing in search results is not proof they read it. Say what the tool does. Never say what they own. -- **Never assert they use Facebook** unless you were given `fb_*` evidence and - you cite it. Describing what the *product* does with a Facebook inbox is a - fact about the product and is always fine. Saying *they* are active on - Facebook requires evidence. +- **Never assert they use Facebook.** Not conditionally, not with a hedge. + Describing what the *product* does with a Facebook inbox is a fact about the + product and is always fine. Saying *they* are on Facebook is a claim about the + prospect, and nothing in the evidence catalogue can support it. - Never invent a problem, a metric, a compliment, or a number. - Never guarantee bookings, revenue, or replies. diff --git a/prospector/profiles/duct-cleaning/skills/write-cold-email.md b/prospector/profiles/duct-cleaning/skills/write-cold-email.md index aedc38f..06442e3 100644 --- a/prospector/profiles/duct-cleaning/skills/write-cold-email.md +++ b/prospector/profiles/duct-cleaning/skills/write-cold-email.md @@ -30,8 +30,10 @@ before you write anything. Different evidence supports different openings: and repeat customers, and a dropped message costs more. - A service area or city supports an opening about their market. - An about/team page naming the owner supports addressing what they built. -- A Facebook page link supports mentioning that channel, but only as a fact - about where messages arrive, never as a claim about how active they are. + +Nothing in the catalogue describes the prospect's own marketing channels, so no +opening can be built on one. Do not reach for Facebook, Messenger, ads, or "where +your leads come from" — you have not been told, and guessing is a fabrication. **Never open with:** - "I hope this email finds you well."