cocottetech/@platform/codebase/@features/prospecting/docs/warm-intros.contract.md

specialist-warm-intro.contract

Subfeature: warm-intros Tenancy: Per-Person specialist instance, runs symmetrically on sender and recipient. API plane: platform.api (black). New routes prefixed /warm-intro/*. Federation: Cross-tenant calls happen via MCP tool mcp__platform-prospecting__warm_intro_*; the recipient's tenant authenticates the sender's copilot.

Scope

Both propose a warm intro (sender side) and evaluate incoming warm-intro proposals (recipient side). The same specialist; behaviour switches on role.

Reads (sender role)

Source	Purpose
Local prospects + prospect_touchpoints	Identify candidate recipients the sender's human has signaled interest in.
prospect_subject_aggregates (graph)	Recipient's network-known preferences, capacity hints.
provider_directory (existing in peer-directory.screen.md)	Recipient addressability + public profile claims.
Local copilot context (sender's stated goals)	Why this intro.

Reads (recipient role)

Source	Purpose
Local intro_preferences (new table)	Policy-coded gating: categories, capacity, deposit policy, time windows.
Local calendar_pressure (from calendar-drawer.screen.md aggregates)	Current load.
prospect_subject_aggregates (graph)	Sender's network reputation.
coop_peer_attestations (N-provider-coop)	Hard-block flags on sender.
Local intros_received (new)	Sender rate-limit state.

Writes

Target	Side	Purpose
intros_sent (new)	sender	Append-only log of proposed intros + outcomes.
intros_received (new)	recipient	Append-only log of evaluated proposals (including silent declines).
intro_threads (new)	both	Created on accept; pins the warm-intro packet to the resulting message thread.
audit_log (existing)	both	Symmetric audit row per negotiation step.

Never list

• Never auto-accept an intro on the recipient human's behalf. The accept-tap is always human; the copilot only decides whether to surface.
• Never include recipient calendar specifics, prior message content, or capacity numerics in a silent-decline response — only a reason class enum.
• Never quote the recipient's content in the warm-intro packet (the packet is sender→recipient, composed entirely from sender-side material).
• Never bypass coop_peer_attestations flags — a flagged sender is hard-declined regardless of evaluator output.
• Never allow the sender's copilot to retry a declined intro within the rate-limit window; the silent decline is sticky.
• Never expose the negotiation transcript to either human until both have surfaced their side (audit replay is allowed; live peeking is not).

Correction lens

• Recipient corrects "I would have wanted to see this": specialist lowers the threshold for that sender / category and records the correction in the recipient's policy.
• Recipient corrects "stop showing me these": specialist raises threshold sender-class-wide; if repeated, the sender (or sender class) is added to a soft-block list.
• Sender corrects "the intro misrepresented me": sender-side packet composer is corrected via mcp__quinn-prospector__* correction-pattern store.

Inputs (MCP tools / endpoints)

• mcp__platform-prospecting__warm_intro_propose(recipient_person_id, packet) — sender → recipient tenant.
• mcp__platform-prospecting__warm_intro_evaluate(proposal_id) — recipient-internal; called by recipient's copilot in response to a proposal event.
• mcp__platform-prospecting__warm_intro_decision(proposal_id, decision) — recipient → sender; carries decision + reason class.
• mcp__platform-prospecting__warm_intro_accept(proposal_id) — recipient-human-only endpoint (gated by a human-presence assertion from the recipient's surface).

Outputs (to peers)

• To sender's specialist-ai-copilot: decision event (surfaced / declined-not-now / declined-out-of-scope / declined-flagged).
• To recipient's specialist-ai-copilot: surface-card request when threshold is met.
• To specialist-strategist: anonymised intro-funnel metrics.

Failure modes

Mode	Behaviour
Recipient tenant unreachable	Sender's copilot is told "delivery deferred"; retries with backoff; never falls back to a cold pitch without the human's go-ahead.
Recipient has no copilot	Proposal returns no-copilot reason class; sender falls back per its own policy.
Rate-limit exceeded	Proposal is hard-declined with rate-limited reason; sender's copilot must wait.
Disagreeing evaluations across copilot replicas	Defer to the recipient's most recent evaluation; log the disagreement to audit.

Related docs

• warm-intros.brief.md, warm-intros.screen.md
• cross-provider-graph.contract.md (reputation source)
• @features/ai-copilot/docs/specialist-ai-copilot.contract.md
• @features/ai-copilot/docs/N-provider-coop.brief.md
• @features/ai-copilot/docs/I-audit-trust-replay.brief.md