מסמך מקור מתקדם. דפי ההתקנה, פרוטוקול ההפעלה וששת הסקילים זמינים לקריאה בעברית; קובץ המקור נשמר כפי שהוא.

--- name: lead-status description: Use when handling tenant-bound synthetic lead intake, Google Sheets status/quality observations, and uncertain write reconciliation. ---

Preserve the lead identity and the meaning of its outcome

Version and authority boundary

Read the selected profile and the exact contract from the package root. Unconverted V1 uses contracts/pipeline.contract.json, mode simulation, demo IDs, supplied synthetic records, geometric placeholders and the existing offline validator only. V1 restrictions remain intact. For V2 explicitly select contracts/pipeline.v2.contract.json; reject unconverted V1 with an explanation. Conversion creates a separate simulation artifact, preserves its source, enriches missing fields, rebuilds all digests, and never promotes approve_demo to human authorization. Neither mode names nor schema validation enable a connector. This build uses no network, accounts, secrets, installs or customer records; integration-test and customer-pilot are separate future gates, not claims of readiness.

Use approved API/MCP/connectors first when integration is separately enabled; browser fallback is only for a capability unavailable in the authorized programmatic path, at the same authority boundary. Never launch external scripts, installers, model CLIs or services from this Skill. Source rule IDs below resolve to docs/knowledge-register-v1.md (checked 2026-10-24). Untested real behavior remains unverified.

Before requesting new OAuth or a project, inspect the client's existing authorized CRM/Sheets connector and verify access to the exact destination and read/write operations. For supervised MVP, hand off a bounded lead/write plan with tenant, route, stable source ID and write ID to that connector, observe its actual response, read back the row and journal the outcome. A prepared plan or recommendation is not delivery. Connector-mediated testing does not prove webhook ingestion or operation after chat closes; use an existing client-owned integration for continuous receipt where suitable, or describe the precise missing setup and seek approval.

Client connection decision: (1) If the existing agent connector can perform the requested supervised action, use it and report the receipt/readback. (2) For continuous receipt outside chat, prefer a suitable native form-to-CRM integration the client already operates. (3) Offer client-owned n8n only when routing, field mapping, multiple destinations, retry or status feedback needs a custom workflow. Explain the proposed source trigger and authentication, exact field/tenant mapping, stable lead key and replay behavior, target write plus readback, uncertain-write reconciliation, bounded retry and error alert, and how a CRM status change returns to the report. Identify the owner, minimum permissions, data retention and approvals before setup. An agent supplies judgment and supervised actions; a configured workflow engine handles ongoing events. Neither a recommendation nor an n8n diagram proves a deployed connection.

For native Meta leads, distinguish app capability, token scope, Page Leads Access and form ownership. During client onboarding, verify the eligible app and credential type plus exact Page/form access. Select only permissions needed for the chosen route, including leads_retrieval for native retrieval. Read back granted scopes and assets, then verify a synthetic test-lead fetch under an approved boundary. A scope checkbox alone never grants Page or Leads Access. Website-only campaign creation does not universally need leads_retrieval. Do not issue or replace a token from this instruction.

Tenant and destination [A2, S1, N2]

Read explicit profile, source/owner mappings, pipeline and intake authorization before accepting an event. Check tenant/account/page/form/destination on events and source reads; unknown or mismatched identity is refused with no default. Unique lead identity is (tenant_id, source_lead_id); same ID in different tenants is distinct. Identical replay is idempotent; changed replay is conflict, never overwrite or status reset. Destination is first Google Sheets, separate/private/synthetic only in pilot; no agency Airtable requirement, Monday records or provider expansion. No real names/phones/emails or public sheet sharing in this build.

Allowlist spreadsheetId AND sheetId and reviewed schema. Row number is never identity: re-resolve stable external key and source/write IDs before a write. Block moved/deleted/duplicate keys or schema changes for reconciliation. Write untrusted values as RAW. Executor owns source/intake/write_id columns; status, qualified, reason, notes and owner belong to the human and are read-only in normal processing. Only approved initialization on a new row and separately authorized synthetic status test are exceptions; replay never reinitializes human fields. Controlled structure and pause-before-maintenance are required; local checks are not atomic against concurrent row movement or a sheet owner bypass.

Writes and recovery [S1, H1]

Persist authenticated intake before ack; worker/queue/outbox are explicit services, not this skill. Save write_id and prepared / in-flight / confirmed / failed-safe / uncertain / confirmed_then_missing. Preserve entity IDs after partial completion. Timeout, elapsed time, local fencing or two empty searches cannot prove a remote append was canceled. No blind retry or new source ID. Resolve uncertain only with sufficient target evidence or bounded documented human disposition; deletion after confirmation is reported and never auto-recreated. Single writer/durable journal reduces races but does not promise exactly-once. Respect bounded scan windows/quota; Sheets offers no assumed conditional upsert or change feed. Report queued as queued, not delivered; prove independent process operation separately.

Quality and measurement [N2, R1, M1]

Keep handling status separate from qualified yes/no/not-reviewed, customer-defined criterion/version, reason, reviewer and assessment time. Missing review is unknown, never no. A recorded successful-sales label is not independently verified sale or revenue; require separate business evidence. Missing ad ID stays null/unknown. Preserve source creation time, observed time and is_test for cohorting. Refresh source snapshots in the authorized window; exclude test records from business reports. Report only last observed Sheets state, not a full edit history or a verified human identity inferred from a cell. Trace intake gap and status to source snapshots. Remote delivery, security, background service, sale and revenue remain unverified until separately tested.