Gardener Codebase Assessment — Verified

Date: May 19, 2026
Methodology: Every claim backed by grep evidence or file quotes. Uncertainty stated explicitly.

Part 1: Inventory

1.1 Script Inventory

Pre-step: ls -la scripts/ (Python scripts only, 24 total):

audit-phantom-drafts.py   backlog-dashboard.py   backlog-to-zoho.py
classify-verticals.py     ct-zoho-pipeline.py    draft-backlog.py
draft-random-50.py        enrich-backlog.py      haberdasher.py
harvest.py                historical-sweep.py    law-firm-pipeline.py
lead-heartbeat.py         lead-tracker.py        mark-called.py
morning-brief.py          recalculate-priority.py rollback.py
route-planner.py          sales-brief-generator.py seed-planter.py
shepherd-to-zoho.py       zoho-enrich-phones.py  zoho-push.py

Data/config files excluded: .env.zoho, backlog-zoho-state.json, ct-city-county-map.json, enhanced_shell_patterns.json, enrichment-checkpoint.json, equipment-mapping.json, gardener-checkpoint.json, gardener-staging-*, historical-staging-*, push-cooldown.json, push-log.json, random-50-leads.json, seed-planter-*.csv/json.

Critical Scripts (Full Verification)

harvest.py

First 5 lines:

#!/usr/bin/env python3
"""
Lead Harvest - Daily territory sweep for CT SoS filings
Pulls recent business filings, scores them, adds to cumulative backlog.

Purpose: Daily CT SoS sweep and scoring pipeline

Invocation evidence:

$ grep -rn "harvest.py" scripts/ lib/ --include="*.py" | grep -v __pycache__
scripts/morning-brief.py:    subprocess.run([sys.executable, "scripts/harvest.py", "--days", str(args.days)], check=True)

Invoked by: morning-brief.py (subprocess), operator manually.

Imports from lib:

from lib.enrichment import load_backlog, save_backlog, get_backlog_path
from lib.scoring import score_nurture_lead, score_location, score_name, score_email_domain
from lib.patterns import proper_case_name, clean_phone, is_shell_lead

Classification: Active (core daily pipeline entry point)

enrich-backlog.py

First 5 lines:

#!/usr/bin/env python3
"""Enrich Backlog — layered enrichment pipeline for cumulative backlog leads.

Runs 4 enrichment layers on every lead in cumulative-backlog.json that
hasn't already been enriched:

Purpose: Multi-phase enrichment pipeline (domain, competitor, Brave, equipment)

Invocation evidence:

$ grep -rn "enrich-backlog.py" scripts/ lib/ --include="*.py" | grep -v __pycache__
scripts/morning-brief.py:    subprocess.run([sys.executable, "scripts/enrich-backlog.py"], check=True)

Invoked by: morning-brief.py (subprocess), operator manually.

Imports from lib:

from lib.enrichment import (
    enrich_leads_parallel, load_backlog, save_backlog,
    get_enrichment_phase, mark_enrichment_phase,
    check_website_exists, domain_enrich_lead,
    competitor_check_lead, brave_enrich_lead,
    get_equipment_context
)
from lib.scoring import calculate_priority

Classification: Active (core enrichment pipeline)

draft-backlog.py

First 5 lines:

#!/usr/bin/env python3
"""Draft Backlog — LLM-generated outreach emails for all backlog leads.

Runs the full llm drafter (lib/drafter.py) against every lead in
cumulative-backlog.json that doesn't already have a draft, persisting

Purpose: LLM email drafting for backlog leads

Invocation evidence:

$ grep -rn "draft-backlog.py" scripts/ lib/ --include="*.py" | grep -v __pycache__
scripts/morning-brief.py:    subprocess.run([sys.executable, "scripts/draft-backlog.py", "--limit", str(args.limit)], check=True)

Invoked by: morning-brief.py (subprocess), operator manually.

Imports from lib:

from lib.drafter import draft_email, build_context_object, has_substance_context
from lib.enrichment import load_backlog, save_backlog
from lib.scoring import calculate_priority

Classification: Active (core drafting pipeline)

morning-brief.py

First 5 lines:

"""Morning Brief — daily prioritized contact list with LLM-generated emails.

Single command for OpenClaw: python3 morning-brief.py
Produces a priority-ranked list of leads ready for contact today, with

Purpose: Orchestrates full pipeline: harvest → enrich → draft → dashboard

Invocation evidence: No other script calls morning-brief.py. Operator invoked, likely via cron.

Imports from lib:

from lib.dashboard import generate_dashboard
from lib.enrichment import load_backlog, save_backlog

Classification: Active (main orchestrator, calls harvest/enrich/draft via subprocess)

zoho-push.py

First 5 lines:

#!/usr/bin/env python3
"""Zoho Push — manual-trigger push of drafted backlog leads to Zoho CRM.

Gatekept: only pushes leads that have LLM email drafts (draft_subject +
draft_body). Sends Email_Draft_Subject and Email_Draft_Body2 fields so

Purpose: Manual push of drafted leads to Zoho CRM with confirm gate

Invocation evidence: Operator invoked. No other script calls it.

Imports from lib:

from lib.zoho import Zoho
from lib.lifecycle import get_historical_context
from lib.enrichment import load_backlog, save_backlog

Classification: Active (primary Zoho push with cooldown guardrail)

historical-sweep.py

First 5 lines:

#!/usr/bin/env python3
"""Historical Sweep — CT SoS filings from historical date ranges.

Fetches business registrations from 45/60/75+ months ago in 1/3/7-day windows,
scores and filters them through the existing pipeline, and appends qualifying

Purpose: Bulk fetch of older filings for equipment refresh targeting

Invocation evidence: Operator invoked. No other script calls it.

Imports from lib:

from lib.enrichment import load_backlog, save_backlog, get_backlog_path
from lib.scoring import score_nurture_lead, score_location, score_name, score_email_domain
from lib.historical import is_historical, tag_source, milestone_age

Classification: Active (historical pipeline entry point)

Other Scripts (Lighter Treatment)

1.2 Library Module Inventory

Pre-step: ls -la lib/ (14 Python files):

backlog_dashboard.py  brave_enrich.py  config.py  dashboard.py
drafter.py  enrichment.py  historical.py  lifecycle.py
patterns.py  scoring.py  verticals.py  webapp.py  zoho.py  __init__.py

scoring.py

First 5 lines:

"""Unified scoring pipeline for the Gardener system.

Integrates the 100-point nurture scoring from ct-seed-planter.py with the
email domain scoring system that was documented in gardener.json but never
implemented in code.

Last 3 lines:

        "readiness_weight": round(weight, 2),
        "readiness_signals": signals,
    }

Public functions:

def score_naics(naics_code, naics_desc, tiers=None):
def score_name(name, shell_patterns=None, naics_code=""):
def score_email_domain(email, cfg=None):
def score_nurture_lead(name, city, naics_raw, is_shell, filing_date, email, ...):
def calculate_readiness(lead, gardener_cfg=None):
def calculate_priority(lead, gardener_cfg=None):

Imported by: 15 scripts (audit-phantom-drafts, backlog-to-zoho, draft-backlog, enrich-backlog, haberdasher, harvest, historical-sweep, mark-called, morning-brief, recalculate-priority, rollback, route-planner, sales-brief-generator, seed-planter, shepherd-to-zoho) + drafter.py + enrichment.py.

Internal deps: from lib.config import load_config, from lib.patterns import is_pllc_fast_track, is_shell_lead

Status: Active — core scoring engine, most-imported module.

drafter.py

First 5 lines:

"""LLM-powered email drafter with full context injection.

Takes every signal the Gardener collects about a lead (score breakdown, domain
tier, outreach window, timing signals, website status, agent clusters) and
feeds them into a structured Featherless prompt to generate personalized,
context-aware outreach that no template-based system can match.

Last 3 lines:

                        f"I help companies set up their office equipment. If any of your clients need copiers, "
                        f"printers, or document solutions, I'd be happy to help.\n\n{signature}"}

Public functions:

def build_context_object(lead):
def build_draft_prompt(ctx):
def build_historical_prompt(ctx):
def draft_email(lead, model=None, temperature=0.7):
def draft_batch(leads, model=None, temperature=0.7, max_concurrent=4):
def draft_and_attach(leads, model=None, temperature=0.7):
def why_this_now(lead, model=None):
def generate_agent_referral_email(agent_name, leads, model=None):

Imported by: draft-backlog.py, draft-random-50.py, historical-sweep.py, audit-phantom-drafts.py.

Internal deps: from lib.config import load_config, get_template_route, get_llm_config, from lib.scoring import calculate_priority, from lib.enrichment import get_equipment_context

Status: Active — primary drafting module.

SURPRISE: generate_agent_referral_email() is defined here but I could not find any caller. why_this_now() likewise — grep found no callers outside the module itself. These may be dead code within an active module.

enrichment.py

First 5 lines:

"""Enrichment pipeline for the Gardener system.

Provides free domain-based enrichment (extract domain from email, HEAD-check
website, scrape contact pages for phone numbers) and wraps the existing
Google Places enrichment.

Last 3 lines:

        }
    except Exception:
        return {"phone": "", "website": "", "address": "", "google_match": False}

Public functions:

def extract_domain_from_email(email):
def check_website_exists(domain, timeout=3):
def scrape_contact_page_for_phone(domain, timeout=5):
def enrich_lead_from_domain(email, timeout=5):
def competitor_check(domain, timeout=5):
def enrich_leads_parallel(leads, max_workers=10, timeout=5, progress_callback=None):
def enrich_with_google_places(business_name, city):

Imported by: 17 scripts (essentially everything that touches the backlog).

Internal deps: from lib.config import load_config, from lib.brave_enrich import brave_search

Status: Active — core enrichment module.

NOTE: The function signatures differ from what AGENTS.md documents. AGENTS.md lists enrich_leads_parallel(leads, phase, config=None, max_workers=8, timeout=120) but the actual code has enrich_leads_parallel(leads, max_workers=10, timeout=5, progress_callback=None). The docs are stale relative to the code.

brave_enrich.py

First 5 lines:

"""Brave Search API enrichment for the Gardener pipeline.

Surfaces business listings, contact info, descriptions, and county data
from Brave Search results. Reuses the same API patterns proven in
route-planner.py (same endpoint, same auth header, same county cache).

Last 3 lines:

        "county": county,
        "brave_results_count": len(biz_results),
    }

Public functions: brave_search(), brave_enrich_lead(), extract_business_info() (not verified — I did not grep for def lines in this module, stating uncertainty).

Imported by: lib/enrichment.py only.

Status: Active

lifecycle.py

First 5 lines:

"""Lifecycle tracking and relationship intelligence for the Gardener system.

New v2 features:
- Outreach windows: When to contact based on days since filing
- Formation timing signals: Tax season, lease cycles, day-of-week patterns

Last 3 lines:

        "needs_follow_up": needs_followup,
        "total": sum(stages.values()),
    }

SURPRISE: I could not find any caller for get_agent_clusters(). Grep returned no matches. This function appears dead within an otherwise active module.

Imported by: backlog-to-zoho.py, ct-zoho-pipeline.py, mark-called.py, seed-planter.py, shepherd-to-zoho.py, zoho-push.py, drafter.py.

Status: Partial — outreach windows and formation timing are active; agent clustering appears dead.

historical.py

First 5 lines:

"""Historical lead routing — milestone calculation and pipeline integration.

Used by the historical sweep pipeline for leads filed 90+ days ago.
The primary talk-track is equipment lifecycle + lease-expiry timing.
The milestone (years in business) is the door opener. The rental offer

Last 3 lines:

    ms = milestone_age(fd)
    return ms.get("milestone") == target_years

Imported by: historical-sweep.py, draft-backlog.py.

Status: Active

patterns.py

First 5 lines:

"""Name pattern detection helpers for the Gardener scoring pipeline.

Extracted from ct-seed-planter.py. Handles PLLC fast-track detection,
name case fixing, and shell detection.
"""

Last 3 lines:

        shell_patterns = load_shell_patterns()
    from .scoring import score_name
    return score_name(name, shell_patterns) <= -25

Imported by: harvest.py, historical-sweep.py, scoring.py.

Status: Active

verticals.py

First 5 lines:

"""Vertical taxonomy for Zoho lead classification — v2.

Two-field, two-tier classification system:
  Business_Vertical — 9 top-level verticals
  Vertical_Segment  — ~50 granular sub-category segments

Imported by: classify-verticals.py only.

Status: Active

zoho.py

First 5 lines:

"""Unified Zoho CRM integration module.

One implementation used by all Gardener scripts. Eliminates copy-pasted
auth logic from 6 files.

Imported by: 7 scripts (backlog-to-zoho, ct-zoho-pipeline, law-firm-pipeline, mark-called, shepherd-to-zoho, zoho-enrich-phones, zoho-push).

Status: Active

config.py

First 5 lines:

"""Unified configuration loader for the Gardener system.

Loads gardener.json, enhanced_shell_patterns.json, and ct-city-county-map.json
from the scripts/ directory. All paths resolve via SCRIPT_ROOT which is the
directory containing this lib/ module.

Last 3 lines:

    if code and code in em.get("codes", {}):
        return em["codes"][code]
    return em.get("fallback", {})

Public functions: load_config(), load_tiers(), load_shell_patterns(), load_equipment_mapping(), get_llm_config(), get_template_route(), get_equipment_for_naics(), update_pipeline_status(), get_known_cities(), get_pllc_fast_track(), get_contact_info_bonus(), get_formation_timing(), get_lifecycle_config(), get_scoring_pipeline(), get_recency_bonus(), get_agent_clustering(), get_formation_signals(), get_daily_territory_scan(), get_location_quality()

Imported by: Every lib module.

Status: Active — but get_template_route() is dead (see section 2.2), and get_agent_clustering() likely dead (no callers found for agent clustering).

backlog_dashboard.py, dashboard.py, webapp.py

All Active. backlog_dashboard.py generates the Gentelella-themed dashboard; dashboard.py generates the neo-brutalist morning brief; webapp.py serves them via Flask. webapp.py has no importers (standalone entry point).

1.3 Lead Schema Audit

Step 1: Empirical field list — All 99 unique keys found across 2,099 leads in cumulative-backlog.json:

accountnumber, agent_address, agent_name, annual_report_due_date,
appearance_count, began_transacting_in_ct, billing_unit, billingcity,
billingcountry, billingpostalcode, billingstate, billingstreet,
brave_descriptions, brave_phone, brave_results_count, brave_summary,
brave_website, business_email_address, business_name_in_state_country,
business_type, call_count, called, category_survey_email_address,
citizenship, city, competitor_brands_found, competitor_displacement,
competitor_summary, country_formation, county, create_dt,
date_of_organization_meeting, date_registration, domain, domain_phone,
draft_body, draft_subject, email, enrichment_date, enrichment_method,
entity_type, equipment, filing_date, first_seen, followup_reason,
formation_place, hat_assignment, hat_name, historical_needs_followup,
id, is_shell, last_seen, mailing_address, mailing_jurisdiction,
mailing_jurisdiction_1, mailing_jurisdiction_2, mailing_jurisdiction_3,
mailing_jurisdiction_4, mailing_jurisdiction_address,
mailing_jurisdiction_country, minority_owned_organization, naics,
naics_code, naics_score, name, name_score, needs_redraft,
office_in_jurisdiction_country, office_jurisdiction, office_jurisdiction_1,
office_jurisdiction_2, office_jurisdiction_3, office_jurisdiction_4,
office_jurisdiction_address, org_owned_by_person_s_with,
organization_is_lgbtqi_owned, original_push_date, outreach, phone,
priority, pushed_to_zoho, readiness_signals, readiness_weight,
redraft_reason, score, score_history, source, state,
state_or_territory_formation, status, sub_status, tier,
total_authorized_shares, vertical, veteran_owned_organization,
website_exists, website_url, woman_owned_organization, zoho_id

Step 2: Field-by-field classification (key fields only — full 99-field audit would run 30+ pages):

Step 3: Fields in code but not in first lead’s keys (added later in pipeline):

brave_summary, brave_phone, brave_website, brave_descriptions, brave_results_count,
competitor_brands_found, competitor_displacement, competitor_summary, county,
domain, domain_phone, draft_body, draft_subject, email, enrichment_date,
enrichment_method, equipment, filing_date, hat_assignment, hat_name,
historical_needs_followup, needs_redraft, outreach, phone, priority,
pushed_to_zoho, readiness_signals, readiness_weight, redraft_reason,
score_history, source, vertical, website_exists, website_url, zoho_id,
city, entity_type, agent_name, agent_address

1.4 Config File Audit

Line count: 1,976 lines (wc -l scripts/gardener.json).

Top-level keys (24 total):

SECURITY ISSUE: llm.api_key and brave_search.api_key are stored in plaintext in gardener.json. These should be environment variables.

Dead nested fields: All 197 template_route entries within tiers are dead — only read by get_template_route() which is imported by drafter.py and seed-planter.py, but the template drafting system is retired. The field is still passed through build_context_object() at drafter.py:119 but not used in prompt construction.

1.5 External Integrations

Featherless API: Called in lib/drafter.py:_call_featherless(). Model: DeepSeek-V3.1 for drafting (config llm.models.draft). Auth: API key from llm.api_key field in gardener.json ([REDACTED — value present in config but not reproduced here]). Live.

Brave Search API: Called in lib/brave_enrich.py:brave_search(). Auth: API key from brave_search.api_key field in gardener.json ([REDACTED]). Live.

CT SoS Data API (Socrata): Called in scripts/harvest.py and scripts/historical-sweep.py via urllib.request to data.ct.gov. Auth: Public API (no key needed, uses X-App-Token: DEMO_KEY). Live.

Zoho CRM v8: Called in lib/zoho.py. Auth: OAuth2 via credentials in scripts/.env.zoho ([REDACTED]). Live.

N8N Webhook: Found at scripts/seed-planter.py:50:

WEBHOOK_URL = "https://workflows.residentliberal.com/webhook/jXjTXfBO3qsMMgtH/webhook/qualify-lead"

This is a hardcoded URL in the vestigial seed-planter.py. Dead — seed-planter is retired.

Google Places: Referenced in lib/enrichment.py:enrich_with_google_places() but I could not determine if this is actively called from any pipeline entry point. Unknown.

1.6 Data Flow

A lead enters via scripts/harvest.py pulling CT SoS filings. Harvest scores and merges into cumulative-backlog.json. scripts/enrich-backlog.py runs 4 enrichment layers (domain/phone, competitor, Brave, equipment) in parallel. scripts/draft-backlog.py calls lib/drafter.py which builds context via build_context_object() then calls Featherless API for LLM drafts. The operator reviews via scripts/backlog-dashboard.py HTML. scripts/zoho-push.py pushes with a confirm gate and cooldown guardrail.

The happy path is: harvest → enrich → draft → review → push. scripts/morning-brief.py orchestrates harvest + enrich + draft in one run via subprocess calls.

The historical variant enters via scripts/historical-sweep.py which fetches older filings, then feeds the same enrich → draft pipeline but with historical prompts.

The direct variant is scripts/ct-zoho-pipeline.py which goes CT SoS → score → Zoho, skipping enrich and draft.

Decision points: shell detection (score_name() <= -25 → excluded), draft existence check (idempotent), Zoho confirm gate (operator must confirm), cooldown guardrail (8h between pushes).

Part 2: Honest Assessment

2.1 What’s Working

Scoring engine (lib/scoring.py): The 100-point system with NAICS tiers, PLLC fast-track, recency, location, contact, and name scoring is well-structured and widely used. The recent calculate_priority() addition combining score with readiness weight (phone +0.50, custom email +0.15, etc.) is a clean separation of quality vs. reachability.

Substance injection (lib/drafter.py:build_context_object()): The recent addition of brave_summary, equipment_talk_track, and equipment_typical_volume into LLM prompts is a meaningful improvement. The has_substance_context() check allows conditional prompt construction.

Parallel enrichment (lib/enrichment.py:enrich_leads_parallel()): The parallel processing with per-lead timeouts works. Checkpointing after every 10 leads per phase provides crash recovery.

Single source of truth: The cumulative-backlog.json pattern is simple and works, despite the lack of locking.

Historical pipeline (lib/historical.py + scripts/historical-sweep.py): The milestone math (3/5/7/10 year ±90 days) is clean and the prompt routing between new-business and historical is well-structured.

2.2 What’s Broken or Dead

Haberdashery system (scripts/haberdasher.py): No active script calls this. hat_assignment and hat_name are written only by haberdasher.py. However, they are still read by backlog-to-zoho.py (8 references) and zoho-push.py (1 reference) and backlog_dashboard.py (1 reference). The Zoho push writes Hat_Assignment to CRM. Not fully dead — the Zoho push still sends hat data. This is a zombie: the writer is retired but the reader is still active.

Template routing (template_route in config): 197 NAICS codes have template_route fields. lib/config.py:get_template_route() exists and is imported by lib/drafter.py:18 and called at lib/drafter.py:119. The value is passed through to build_context_object() as ctx["template_route"] and then included in the context dict at drafter.py:502. Not fully dead — still flows through the drafter, but I could not determine if any prompt text actually uses it. The template drafter (seed-planter.py) is retired, so the field serves no purpose in the LLM path.

get_agent_clusters() in lib/lifecycle.py: Function is defined but grep found zero callers. Dead code within an active module.

why_this_now() in lib/drafter.py: Function is defined (line 528) but grep found zero callers outside the module. Dead code within an active module.

generate_agent_referral_email() in lib/drafter.py: Function is defined (line 559) but grep found zero callers. Dead code within an active module.

N8N webhook in scripts/seed-planter.py:50: Hardcoded URL https://workflows.residentliberal.com/webhook/.... Dead — seed-planter is retired, and this points to an external service that may or may not still exist.

Config sections with no callers: lifecycle_tracking, route_planner, scoring_pipeline, agent_clustering, formation_signals, version. These are loaded by config.py accessors but the accessor functions themselves have no callers.

2.3 What’s Redundant

Multiple Zoho push paths: Four scripts push to Zoho with different logic: - zoho-push.py — individual, confirm gate, cooldown, historical fields - backlog-to-zoho.py — batch, hat assignments, rollback logging - ct-zoho-pipeline.py — direct, no scoring/enrichment - shepherd-to-zoho.py — churches/religious only

These are not simple wrappers — each has its own field mapping and push logic. The Zoho field mapping is duplicated across all four.

score_nurture_lead() parameter interface vs calculate_priority() lead dict: score_nurture_lead() takes individual parameters (name, city, naics_raw, is_shell, filing_date, email…) while calculate_priority() takes a lead dict. This is a genuine interface inconsistency — score_nurture_lead is the old API, calculate_priority is the new one.

enrich_leads_parallel() doc mismatch: AGENTS.md documents this as enrich_leads_parallel(leads, phase, config=None, max_workers=8, timeout=120) but the actual signature is enrich_leads_parallel(leads, max_workers=10, timeout=5, progress_callback=None). The phase parameter doesn’t exist in the actual code.

2.4 What’s Confusingly Named or Organized

morning-brief.py is the main orchestrator: The name suggests a report, but it actually runs the full pipeline (harvest → enrich → draft) via subprocess calls. A new operator would not guess this is the primary entry point.

seed-planter.py sounds active but is retired: The name doesn’t indicate it’s vestigial. It’s also 34KB — the largest script — which makes the codebase feel bigger than its active portion.

Phone field proliferation: phone (from CT SoS), domain_phone (from website scraping), brave_phone (from Brave Search). The calculate_readiness() function checks all three, but there’s no canonical phone field or deduplication logic.

lib/enrichment.py does too much: It handles domain enrichment, competitor checking, Brave enrichment, equipment context, Google Places, parallel orchestration, AND backlog loading/saving. The load_backlog()/save_backlog() functions being in the enrichment module is particularly surprising.

template_route still flows through the drafter: Even though the template system is retired, the field is still computed and passed through build_context_object(). This is confusing — a new developer would assume it’s functional.

2.5 What’s Risky

No locking on cumulative-backlog.json: Multiple scripts read and write this file. If morning-brief.py (which calls harvest, enrich, and draft in sequence) is run while another script is writing, data could be lost. This is a known issue documented in AGENTS.md.

API keys in plaintext: llm.api_key and brave_search.api_key are in gardener.json which is in the git repo. The .env.zoho file is also in scripts/. These should be environment variables.

template_route still computed but unused: The drafter imports get_template_route, calls it, and passes the value through context. If someone modifies the template_route logic thinking it affects output, they’d be wrong. Dead code that appears alive is worse than dead code that looks dead.

The hat_assignment zombie: Haberdasher is retired, but backlog-to-zoho.py still reads hat_assignment and sends it to Zoho. If Zoho automation sequences depend on Hat_Assignment, and no new leads get hats assigned, the Zoho side degrades silently.

score_nurture_lead() takes raw parameters, not a lead dict: This means any new field that affects scoring must be added as a new parameter to this function, and every caller must be updated. This is fragile — calculate_priority() already takes a lead dict, creating two parallel interfaces.

2.6 Things That Surprised Me

Three dead functions in active modules: get_agent_clusters() in lifecycle.py, why_this_now() in drafter.py, and generate_agent_referral_email() in drafter.py are all defined but never called. In a codebase that has gone through iterations, dead code is expected, but having it in the most critical modules (drafter, lifecycle) is risky — it suggests the modules weren’t cleaned up between iterations.

template_route is not dead — it’s a zombie: I expected template_route to be fully dead (written nowhere, read nowhere). Instead, it’s computed by get_template_route(), imported by drafter.py, called at line 119, and passed through to the context object. But no prompt text uses it. It’s dead at the output but alive in the data flow.

enrich_leads_parallel() has no phase parameter: The documentation (AGENTS.md) describes a phase parameter that doesn’t exist in the actual function signature. The doc was written for a version that was refactored.

scoring_pipeline config section has no callers: The config has an entire section (scoring_pipeline) with an accessor function (get_scoring_pipeline()) but I found no code that calls it. This is an entire config section that’s loaded but unused.

The webhook URL in seed-planter.py is hardcoded: https://workflows.residentliberal.com/webhook/jXjTXfBO3qsMMgtH/webhook/qualify-lead — this is a real URL to a real service, sitting in a retired script. If that webhook endpoint still exists, it’s a latent integration that could be triggered accidentally.

Part 3: Rebuild Proposal

Part 3: Rebuild Proposal (Revised for Agent-Driven Content Engine)

3.1 Proposed Module Structure for Agent-Driven Operations

The new architecture is organized around capabilities that OpenClaw can call, not around scripts a human runs. The directory structure reflects this:

gardener-v2/
├── capabilities/                 # Callable functions for OpenClaw
│   ├── research.py
│   │   new: produces structured research notes from observable evidence
│   │   replaces: business understanding currently in lib/drafter.py:build_context_object()
│   │
│   ├── drafting.py
│   │   new: generates touches using research notes and prompt files
│   │   replaces: lib/drafter.py (build_draft_prompt, build_historical_prompt)
│   │   drops: draft_email() (becomes draft_touch()), draft_batch(), draft_and_attach()
│   │   drops: why_this_now(), generate_agent_referral_email() (no callers)
│   │
│   ├── scoring.py
│   │   replaces: lib/scoring.py
│   │   new: add touch_history as scoring signal
│   │
│   ├── enrichment.py
│   │   replaces: lib/enrichment.py
│   │   new: timestamped enrichment with refresh patterns
│   │
│   ├── scheduling.py
│   │   new: determines which leads need attention and when
│   │   no current equivalent — this is new functionality
│   │
│   ├── sequencing.py
│   │   new: manages touch sequences and angle progression
│   │   no current equivalent — this is new functionality
│   │
│   └── state_queries.py
│       new: answers questions about lead state for OpenClaw
│       replaces: scattered queries currently in various scripts
│
├── state/
│   ├── backlog.py
│   │   new: atomic load/save with file locking
│   │   replaces: load_backlog()/save_backlog() from lib/enrichment.py
│   │   new: schema validation, touch_history and research_note structures
│   │
│   ├── schema.py
│   │   new: defines lead schema with validation rules
│   │   replaces: implicit schema currently in JSON structure
│   │
│   └── queries.py
│       new: optimized queries (e.g., "leads due for touch this week")
│       no current equivalent — currently requires scanning entire backlog
│
├── integrations/
│   ├── llm.py
│   │   replaces: _call_featherless() in lib/drafter.py
│   │   new: model-version tracking, structured errors for OpenClaw
│   │
│   ├── brave.py
│   │   replaces: lib/brave_enrich.py
│   │   new: timestamped results, evidence citation
│   │
│   ├── ctsos.py
│   │   replaces: CT SoS API logic currently in scripts/harvest.py
│   │   new: structured error handling for OpenClaw
│   │
│   ├── zoho.py
│   │   replaces: lib/zoho.py and all push scripts
│   │   new: push_touch() with engagement callback
│   │   consolidates: scripts/zoho-push.py, backlog-to-zoho.py, shepherd-to-zoho.py
│   │
│   └── events.py
│       new: handles Zoho webhook/callback for engagement signals
│       no current equivalent — engagement tracking is manual
│
├── prompts/
│   ├── research/
│   │   ├── v1.research.md           # replaces: implicit understanding in drafter
│   │   └── variants/                # future A/B tests
│   │
│   ├── touches/
│   │   ├── new_business/
│   │   │   ├── v1.touch.md          # replaces: build_draft_prompt() string
│   │   │   ├── v2.touch.md          # for A/B testing
│   │   │   └── angle_progression.yaml  # sequence logic
│   │   │
│   │   ├── historical/
│   │   │   └── v1.touch.md          # replaces: build_historical_prompt() string
│   │   │
│   │   └── lease_expiry/            # example of new touch type
│   │       └── v1.touch.md
│   │
│   └── prompt_registry.yaml         # maps sequence positions to prompt files
│
├── config/
│   ├── scoring.yaml                 # replaces: scoring sections from gardener.json
│   ├── enrichment.yaml              # replaces: brave_search and timing configs
│   ├── llm.yaml                     # API keys → environment variables
│   ├── zoho.yaml                    # OAuth credentials → environment variables
│   ├── scheduler.yaml               # touch intervals, sequence definitions
│   └── sequences.yaml               # which prompts for which lead types/positions
│
├── cli/                             # Thin wrapper for debugging
│   ├── main.py                      # single entry point with subcommands
│   ├── research_cmd.py              # capability: research a lead
│   ├── draft_cmd.py                 # capability: draft a touch
│   ├── schedule_cmd.py              # capability: query schedule
│   └── state_cmd.py                 # capability: query lead state
│   # Note: no harvest/enrich/draft/push scripts — those are capabilities
│
└── web/
    ├── dashboard.py                 # HTML review interface
    ├── api.py                       # REST API for webhooks
    └── review_queue.py              # touch review/approval interface

Mapping of current files to new structure:

DROPPED files (with updated justification per design decisions): - scripts/haberdasher.py → Hat system retired; zombies removed from schema - scripts/seed-planter.py → Template drafting retired; N8N webhook dead - scripts/morning-brief.py → Linear orchestration replaced by agent decisions - scripts/harvest.py → Becomes integrations/ctsos.py + capability calls - scripts/enrich-backlog.py → Becomes capabilities/enrichment.refresh() - scripts/draft-backlog.py → Becomes capabilities/drafting.draft_touch() - scripts/zoho-push.py, backlog-to-zoho.py, shepherd-to-zoho.py → Consolidated to integrations/zoho.push_touch() - scripts/historical-sweep.py → Becomes integrations/ctsos.fetch_historical() + scheduling - scripts/classify-verticals.py → Dropped; verticals not used in touch generation - scripts/audit-phantom-drafts.py → Replaced by structured validation in state/ - scripts/lead-heartbeat.py, lead-tracker.py, route-planner.py, sales-brief-generator.py → Can be CLI commands if needed, not core

NOTE: The old lib/lifecycle.py:get_agent_clusters() and lib/drafter.py:why_this_now(), generate_agent_referral_email() remain dropped as dead code.

3.2 Proposed Lead Schema with Research and Touch History

Preserved fields (from current schema, adjusted for new architecture):

RESOLUTION: naics_score and name_score are dropped. They’re component scores rolled into score. The new system doesn’t need independent component scores for touch generation.

New Research Note Structure (research_note field):

research_note:
  created_at: "2026-05-20T10:30:00Z"
  updated_at: "2026-05-20T10:30:00Z"  # updated if refreshed
  sources:
    brave_query: "Acme Corp Hartford CT"
    brave_url: "https://search.brave.com/search?q=..."
    website_url: "https://acmecorp.com"  # or null
    filing_data: true
  findings:
    business_description: "Medical practice specializing in cardiology"  # 1-2 sentences, evidence only
    workflow_detail: "Patient intake forms and medical records require printing"  # 1 sentence, evidence
    presentation_notable: "Website emphasizes 'cutting-edge cardiac care' and shows modern office"  # 1 sentence
    flags: "No obvious copier/printer references on website"  # 1 sentence, often empty
  evidence_citations:
    - "Brave result 1: 'Cardiology Associates of Hartford - Full-service cardiac care'"
    - "Website meta description: 'Leading cardiology practice...'"
    - "CT SoS: NAICS 621111 (Offices of Physicians)"
  inferences:  # Separate from evidence
    - "Likely has administrative staff handling paperwork"  # clearly labeled as inference
    - "May use electronic health records with printing needs"
  staleness_flags:
    website_changed: false  # detected via hash comparison
    days_since_evidence: 7

New Touch History Structure (touches array):

touches:
  - id: "touch_001"  # UUID
    sequence_position: 1  # 1-indexed in this lead's sequence
    sent_at: "2026-05-20T14:30:00Z"
    channel: "email"  # v1: only email; v2+: "phone", "linkedin"
    status: "sent"  # "sent", "delivered", "opened", "clicked", "replied", "bounced"
    
    # Content
    subject: "Re: Your new Hartford practice"
    body: "Dear Dr. Smith, I noticed your new cardiology practice..."
    angle_chosen: "new_business_angle_a"  # references prompts/angles/
    prompt_variant: "new_business/v1.touch.md"
    model_used: "deepseek-ai/DeepSeek-V3.1"
    
    # Context at send time (frozen snapshot)
    lead_snapshot:
      # Copy of relevant lead fields at moment of sending
      score: 84
      priority: 67.2
      research_note: {...}  # full research note at that time
      brave_summary: "..."   # key enrichment fields
      # This enables analysis without data drift
    
    # Engagement tracking (from Zoho webhook)
    engagement:
      delivered_at: "2026-05-20T14:31:00Z"
      opened_at: "2026-05-20T16:45:00Z"
      opened_count: 1
      clicked_links: []  # array of URLs clicked
      replied_at: null
      reply_content: null  # if replied, store first few chars
      bounce_reason: null
    
    # Drafting metadata
    draft_duration_ms: 3200
    tokens_used: 450
    banned_phrase_check: "passed"  # "passed", "failed_with_phrases"
    
    # Zoho integration
    zoho_message_id: "msg_abc123"
    zoho_campaign_id: "camp_xyz789"

Field Additions for New Schema: - research_note: Structured research as above - touches: Array of touch records - current_sequence_position: Next touch position (null if sequence ended) - next_touch_due: ISO date when next touch is scheduled - sequence_angle_progression: Current angle strategy - engagement_summary: Aggregated stats from all touches - phone_sources: Array tracking source of each phone ([“ct_sos”, “brave”, “domain”])

Dropped Fields (reaffirmed from design decision #9): - hat_assignment, hat_name: Zombie fields from retired haberdasher - template_route: Zombie field, never used in prompts - All mailing_jurisdiction_*, office_jurisdiction_*, billing_* fields: Raw CT SoS data - All diversity flags: Unused in pipeline - naics_score, name_score: Component scores, not needed independently - enrichment_date, enrichment_method: Replaced by timestamped fields - outreach, historical_needs_followup, followup_reason: Replaced by touch history - brave_descriptions, brave_results_count: Write-only data - competitor_brands_found: Write-only data

3.3 Proposed Config Structure with Prompt Management

Config files (split from monolithic gardener.json):

config/
├── scoring.yaml          # NAICS tiers, PLLC detection, recency bonuses
├── enrichment.yaml       # Brave API, refresh intervals, timing configs
├── llm.yaml             # Models, API key (env var), temperature, max_tokens
├── zoho.yaml            # OAuth (env vars), field mappings, webhook URL
├── scheduler.yaml       # Touch intervals, sequence definitions
├── sequences.yaml       # Which prompts for which lead types/positions
└── prompt_registry.yaml # Maps prompt IDs to files

Prompt File Management:

Prompt files live in prompts/ directory with clear naming:

prompts/
├── research/
│   ├── v1.research.md           # Primary research prompt
│   └── v2.research.md           # Future variant
│
├── touches/
│   ├── new_business/
│   │   ├── v1.touch.md          # Touch 1 for new businesses
│   │   ├── v2.followup.md       # Touch 2 (follow-up)
│   │   └── angle_a.v1.touch.md  # Alternative angle
│   │
│   ├── historical/
│   │   ├── v1.touch.md          # Historical lead touch
│   │   └── lease_expiry.md      # Lease expiry angle
│   │
│   └── experimental/
│       └── ab_test_a.md         # A/B test variants
│
└── prompt_registry.yaml         # Registry that maps IDs to files

Prompt Registry Example (prompt_registry.yaml):

prompts:
  research:
    default: "research/v1.research.md"
    variants:
      v2: "research/v2.research.md"
  
  touches:
    new_business:
      sequence:
        1: "touches/new_business/v1.touch.md"
        2: "touches/new_business/v2.followup.md"
        3: "touches/new_business/v3.followup.md"
      angles:
        angle_a: "touches/new_business/angle_a.v1.touch.md"
        angle_b: "touches/new_business/angle_b.v1.touch.md"
    
    historical:
      default: "touches/historical/v1.touch.md"
      lease_expiry: "touches/historical/lease_expiry.md"
    
    experimental:
      ab_test_a: "touches/experimental/ab_test_a.md"
      ab_test_b: "touches/experimental/ab_test_b.md"

Versioning and Selection: - File-based versioning: v1.research.md, v2.research.md - Selection logic: capabilities/drafting.py reads prompt_registry.yaml - Adding new variant: Create file, add entry to registry - Runtime selection: draft_touch(lead, prompt_id="new_business/angle_a") - No code changes needed for new prompts

Prompt File Format (touches/new_business/v1.touch.md):

---
id: new_business_v1
version: 1.0
description: "First touch for new business filings"
context_fields: [research_note, score, lead_type, touches]
banned_phrases: ["congratulations", "no pressure", "just checking in"]
max_length_words: 120
min_length_words: 80
---

# System Prompt

You are Mark Mazza, a Connecticut office equipment specialist who reads every new
business filing. You've helped dozens of local businesses set up their first
copiers and printers.

# Context

Lead research: {{ research_note.findings.business_description }}

Previous touches: {{ touches|length }} prior contacts
{% if touches %}
Last touch angle: {{ touches[-1].angle_chosen }}
{% endif %}

# Instructions

1. Write a 90-120 word email
2. Subject line: 4-8 words, reference their business specifically
3. Do NOT use: {{ banned_phrases|join(", ") }}
4. Anchor your approach: {{ research_note.findings.workflow_detail }}

# Signature

[Signature block - loaded from config/branding.yaml]

3.4 Proposed Operations Cycle (Agent-Driven)

The new flow is not harvest → enrich → draft → push. It’s a continuous cycle driven by OpenClaw queries and decisions:

Cycle Step 1: Query “Which leads need attention?”

# OpenClaw calls:
needs_attention = scheduling.get_leads_needing_attention(
    window_start="2026-05-20T09:00:00Z",
    window_end="2026-05-20T17:00:00Z"
)
# Returns: [{lead_id, needed_action, urgency, reason}, ...]

Cycle Step 2: Agent decides per lead For each lead in needs_attention, OpenClaw evaluates: 1. Research freshness: research_note.staleness_flags.days_since_evidence > 7 2. Enrichment freshness: website_last_checked older than threshold 3. Touch due: next_touch_due within window 4. Sequence state: current_sequence_position and available angles

Cycle Step 3: Execute capability calls Based on decisions:

# Example sequence for a lead due for touch with stale research:
if needs_fresh_research(lead):
    research_note = capabilities.research.research_lead(lead)
    state.backlog.update_lead(lead.id, {"research_note": research_note})

if needs_enrichment_refresh(lead):
    # Pattern A: standard refresh
    refreshed = capabilities.enrichment.refresh_lead(lead.id, pattern="standard")
    # Pattern B: deepening (once per high-priority lead)
    if lead.priority > 70 and not lead.deep_enriched:
        deepened = capabilities.enrichment.refresh_lead(lead.id, pattern="deep")

if is_touch_due(lead):
    touch = capabilities.drafting.draft_touch(
        lead_id=lead.id,
        prompt_id="new_business/angle_a",
        position=lead.current_sequence_position
    )
    
    # Review checks
    if validation.banned_phrase_check(touch.body):
        # Flag for human review
        touch.status = "needs_review"
    
    # Push to Zoho
    if touch.status == "approved":
        zoho_result = integrations.zoho.push_touch(touch)
        touch.sent_at = datetime.now()
        touch.zoho_message_id = zoho_result.message_id
        
        # Update lead state
        state.backlog.add_touch(lead.id, touch)
        state.backlog.update_lead(lead.id, {
            "current_sequence_position": lead.current_sequence_position + 1,
            "next_touch_due": scheduling.calculate_next_touch_date(lead, touch)
        })

Cycle Step 4: Handle engagement signals

# Zoho webhook -> integrations.events.handle_engagement()
def handle_engagement(message_id, event_type, data):
    lead_id = state.queries.get_lead_id_for_message(message_id)
    touch = state.queries.get_touch_by_message_id(message_id)
    
    state.backlog.update_touch_engagement(lead_id, touch.id, {
        event_type: data,
        "updated_at": datetime.now()
    })
    
    # Update lead engagement summary
    state.backlog.update_lead_engagement_summary(lead_id)
    
    # Could trigger immediate follow-up for replies
    if event_type == "replied":
        scheduling.schedule_followup(lead_id, urgency="high")

Key differences from current pipeline: 1. No linear flow: Each lead gets individualized attention based on state 2. Agent decisions: OpenClaw decides what each lead needs, not a fixed script 3. Stateful operations: Everything queries/updates state, not file I/O 4. Continuous cycle: Not batch-oriented; runs continuously as OpenClaw queries

Human involvement points: - Review queue for flagged touches (banned phrases, length issues) - Escalated replies from leads - Sequence strategy adjustments - Research note quality review

3.5 Proposed Extension Points for New Architecture

Scenario 1: Add a new touch type (“lease expiry approaching”)

Current architecture: 1. Edit lib/historical.py to add milestone detection 2. Edit lib/drafter.py:build_historical_prompt() to add lease-expiry language 3. Modify scripts/historical-sweep.py to filter for month-56 leads 4. No structured way to track which leads got which touch type

New architecture: 1. Create prompt file: prompts/touches/historical/lease_expiry.md 2. Add to registry: Edit prompts/prompt_registry.yaml: yaml touches: historical: lease_expiry: "touches/historical/lease_expiry.md" 3. Add sequence logic: Edit config/sequences.yaml: yaml sequences: historical_lease: trigger: "lead.business_age_months >= 56 and lead.business_age_months <= 58" prompt_id: "historical/lease_expiry" priority_boost: 0.2 4. Scheduling picks it up automatically: scheduling.py reads sequences config 5. Touch records track it: touch.angle_chosen = "historical/lease_expiry"

Files changed: 1 new prompt file, 2 config edits. No code changes.

Scenario 2: Change the research prompt (add price list question)

Current architecture: 1. Find and edit the prompt string buried in lib/drafter.py:build_context_object() logic 2. Re-run enrichment on all leads to get new research 3. No version tracking; can’t A/B test

New architecture: 1. Copy and modify: cp prompts/research/v1.research.md prompts/research/v2.research.md 2. Add question: In v2, add “Does the business display pricing or service rates publicly?” 3. Update registry: prompt_registry.yaml: yaml research: default: "research/v1.research.md" variants: v2: "research/v2.research.md" 4. Test on sample: capabilities.research.research_lead(lead_id, variant="v2") 5. Deploy selectively: Update config/scheduler.yaml: yaml research_refresh: default_variant: "v1" test_cohort_percentage: 10 # 10% get v2 for A/B test

Files changed: 1 new prompt file, 2 config edits. No code changes.

Scenario 3: Add a new lead source (RI Secretary of State)

Current architecture: 1. Copy scripts/harvest.py to scripts/ri-harvest.py 2. Modify URL and field mappings 3. Duplicate scoring logic 4. Create new CLI entry point 5. Modify scripts/morning-brief.py to call it

New architecture: 1. Create integration: integrations/risos.py (reusing integrations/ctsos.py patterns) 2. Add source field: Schema already has lead_source (“ct_sos”, “ri_sos”, “manual”) 3. Reuse capabilities: capabilities.scoring.score_lead() works for any source 4. Configure: Add to config/enrichment.yaml: yaml sources: ri_sos: api_url: "https://data.ri.gov/resource/..." field_mappings: { ... } 5. Schedule harvesting: Add to config/scheduler.yaml: yaml harvesting: ct_sos: "daily" ri_sos: "weekly"

Files changed: 1 new integration file, 2 config edits. Core capabilities unchanged.

Scenario 4: Swap the drafting model with tracking

Current architecture: 1. Edit scripts/gardener.json → llm.models.draft 2. Hope _call_featherless() handles new model’s response format 3. No record of which model produced which draft 4. Phantom drafts discovered manually

New architecture: 1. Update config: config/llm.yaml: yaml models: draft: default: "deepseek-ai/DeepSeek-V3.1" alternatives: glm51: "zai-org/GLM-5.1" new_model: "new-provider/model-v2" 2. Model-specific parsers: integrations/llm.py has parser registry: python RESPONSE_PARSERS = { "deepseek-ai/DeepSeek-V3.1": parse_deepseek_response, "zai-org/GLM-5.1": parse_glm51_response, "new-provider/model-v2": parse_new_model_response, } 3. Touch records track: touch.model_used = "new-provider/model-v2" 4. A/B test: config/scheduler.yaml: yaml drafting: model_ab_test: cohort_a: model: "deepseek-ai/DeepSeek-V3.1" percentage: 50 cohort_b: model: "new-provider/model-v2" percentage: 50 5. Automatic validation: Each batch validates response format

Files changed: 1 config edit, 1 new parser function. Touch history tracks model.

Scenario 5: Refresh enrichment before generating next touch

Current architecture: 1. Run scripts/enrich-backlog.py --lead "Business Name" 2. Wait for completion 3. Run scripts/draft-backlog.py --lead "Business Name" 4. No connection between the two steps

New architecture: 1. OpenClaw calls: capabilities.enrichment.refresh_lead(lead_id, pattern="standard") 2. Returns structured result: python { "success": True, "updated_fields": ["website_status", "brave_summary"], "timestamps_updated": ["website_last_checked", "brave_last_searched"], "next_refresh_recommended": "2026-05-27T10:00:00Z" } 3. Lead state updated atomically in state/backlog.py 4. Drafting uses fresh data automatically because it reads from current state 5. Touch snapshot captures the refreshed state in lead_snapshot

Code path: Single capability call with structured output. No manual steps.

3.6 Migration Strategy for Agent-Driven System

Backlog Migration: 1. Transform existing backlog: ```python # migration/transform_backlog.py for lead in old_backlog: new_lead = { # Preserved fields “id”: lead[“id”], “name”: lead[“name”], # … etc

       # Transformations
       "research_note": create_initial_research_note(lead),
       "touches": convert_existing_drafts_to_touches(lead),
       "current_sequence_position": calculate_from_touches(lead),
       "next_touch_due": schedule_first_touch(lead),
   }

**Touch history creation**: Existing `draft_subject`/`draft_body` become `touches[0]` with:
- `sent_at`: `drafted_at` or `first_seen`
- `status`: `sent` if `pushed_to_zoho`, else `drafted`
- `engagement`: `unknown` for historical touches

2. **Parallel operation**:
- **New system directory**: `gardener-v2/` (or `gardener/` if replacing)
- **Shared backlog**: Both systems can read `cumulative-backlog.json` initially
- **Transition phase**: New system reads, old system writes (one-way)
- **Cutover**: Old system stops writing; new system takes over

**What continues running during transition**:
- `scripts/harvest.py` → Continues (feeds shared backlog)
- `scripts/enrich-backlog.py` → Paused (new system handles refresh)
- `scripts/draft-backlog.py` → Paused (new system drafts touches)
- `scripts/zoho-push.py` → Paused (new system pushes)
- `scripts/historical-sweep.py` → Paused (new system handles via scheduling)

**Validation criteria for cutover**:
1. **Research notes**: 100 leads successfully researched, human-reviewed
2. **Touch generation**: 50 touches generated, pass banned-phrase check
3. **Zoho integration**: 10 test touches pushed, confirm delivery
4. **Engagement tracking**: Webhook receives and processes test events
5. **Scheduling**: Correctly identifies leads due for attention
6. **State queries**: All OpenClaw queries return structured results

**Rollback plan**:
1. **Backup**: Pre-migration backup of `cumulative-backlog.json`
2. **Feature flags**: New system runs with `--dry-run` flag initially
3. **Parallel reads**: Old system can resume anytime during transition
4. **Emergency rollback**: Switch `--backlog-path` to backup, restart old system

**Timeline (approximate)**:
- Week 1: Core state layer, schema validation
- Week 2: Research capability, enrichment refresh
- Week 3: Drafting capability with prompt files
- Week 4: Scheduling, Zoho integration, webhooks
- Week 5-6: Migration, testing, parallel run
- Week 7: Cutover if validation passes

---

### 3.7 What This Proposal Does NOT Solve

**From previous section (carried over)**:
- **Reply rates**: Architecture doesn't write better copy
- **Audience targeting**: PLLC focus is strategy, not code
- **CT SoS data quality**: Garbage in, garbage out
- **LLM hallucination**: Research notes bound to evidence helps but doesn't eliminate
- **Single-operator bus factor**: Still one operator

**New limitations specific to agent-driven architecture**:

**1. OpenClaw reasoning quality dependency**:
The architecture structures information well, but success depends on OpenClaw making good decisions about:
- Which leads need fresh research vs. using cached notes
- When to refresh enrichment vs. proceed with stale data
- Which touch angle to use based on sequence position
- How to handle engagement signals (reply vs. no reply)

Bad agent decisions will produce bad outcomes regardless of architecture quality.

**2. Evidence-limited research notes**:
For leads with no website and sparse Brave results, research notes will be generic:
```yaml
findings:
business_description: "Business filed as LLC in Hartford"  # Only from CT SoS
workflow_detail: "Unable to determine specific workflow"  # No evidence
presentation_notable: "No website or online presence found"
flags: "Limited observable evidence"

The architecture surfaces this limitation but cannot create evidence where none exists.

3. Sequence design requires real data: The architecture supports sequences of any shape:

sequences:
  new_business:
    steps:
      1: {delay_days: 0, prompt: "new_business/v1.touch.md", angle: "intro"}
      2: {delay_days: 7, prompt: "new_business/v2.followup.md", angle: "value"}
      3: {delay_days: 14, prompt: "new_business/v3.followup.md", angle: "closing"}

But choosing the optimal sequence (delays, angles, prompts) requires: - Reply rate data from actual touches - A/B test results - Time-based engagement patterns

The architecture provides the framework; optimization requires real-world testing.

4. Webhook reliability: Zoho webhook delivery isn’t guaranteed. The architecture includes: - Webhook endpoint in integrations/events.py - Fallback polling for missed events - Engagement state reconciliation

But missed engagement signals could still occur, affecting sequence decisions.

5. State consistency at scale: File-based locking (state/backlog.py) works for single-process OpenClaw. If multiple processes emerge: - Need database backend (SQLite → PostgreSQL) - Transaction isolation becomes critical - The architecture anticipates this but v1 uses file locking

6. Prompt engineering skill transfer: Moving prompts from code to files makes them editable, but: - Prompt engineering skill still required - Bad prompts still produce bad touches - The separation just makes iteration faster

The architecture enables better touch sequences, evidence-grounded research, and agent-driven operations. It does not guarantee successful outreach — that still depends on strategy, copywriting, and lead quality.