linkedin skills

contracts/lead-artifact-contract.md

@@ -0,0 +1,53 @@
+# Lead Artifact Contract
+
+This contract defines what `linkedin-lead-filter` writes and what
+`draft-outreach` must read.
+
+## Canonical fields
+
+Required:
+- `lead_key`
+- `name`
+- `title`
+- `company`
+- `linkedin_url`
+- `qualification_status`
+- `score`
+- `signal_type`
+- `reason`
+- `last_scored_at`
+
+Optional:
+- `recent_activity`
+- `engagement_signal`
+- `source_file`
+- `owner`
+
+## File contract
+
+`linkedin-lead-filter` must write:
+- `output/leads_{date}/qualified_leads_{date}.csv`
+- category disqualification files
+- `output/leads_{date}/lead_registry_{date}.json`
+
+The registry JSON must include an array `leads[]` with canonical fields.
+
+## Key derivation
+
+`lead_key` is:
+`lowercase(trim(name) + "|" + trim(company) + "|" + trim(linkedin_url))`
+
+If `linkedin_url` is missing, use:
+`lowercase(trim(name) + "|" + trim(company) + "|missing_url")`
+
+## Conflict policy
+
+If the same `lead_key` appears multiple times in one run:
+1. Keep the highest `score`.
+2. Keep the most recent `signal_type` detail if available.
+3. Record `duplicate_count` in state.
+
+If a required field is missing:
+- Stop downstream draft generation for that lead.
+- Log it as `contract_violation`.
+- Ask for field mapping or repair.