CampaignForge + ContentForge

Parallel orchestration works cleanly when output paths don’t collide. Four research agents dispatched from a single orchestrator turn — voc-collector, school-data-puller, bls-extender, state-aid-resolver — each writing to a distinct subdirectory tree. Zero file collisions, zero coordination overhead, zero need to consult each other’s in-flight state. Wall-clock compressed from ~4h serial estimate to ~30min (longest pole). The discipline is upfront: confirm writes land in non-overlapping paths before launching, not after. Can’t parallelize when agents need to share a stateful file or each other’s intermediate conclusions; can parallelize when each agent’s output stands alone.

Self-contained briefs beat shared-context agents. Each agent brief included: project context files to read (absolute paths), exact task scope, output schema, guardrails (compliance + anti-hallucination + firecrawl-only), success checklist, report format + word cap. Agents came back with tight, actionable reports rather than rambling transcripts. Pattern reuses: if you can write the brief as if the agent just walked into the room cold, you don’t need to babysit.

Pell-refund discovery provokes fear before delight. VoC Reddit + Trustpilot signal that first-time Pell recipients default to “I’ll get in trouble” + tax-penalty anxiety, not windfall delight. Our current EFC Calculator output flow leads with the dollar amount then context. The real sequence should be permission-slip first (“this is legitimately yours”) then specificity (“here’s $7,395”). This inverts a framing assumption baked into Phase 2 tool specs. Flagged for Phase 6 lander archetype re-work.

Peer-insider-knowledge is the primary Reddit conversion mechanism. Reddit buyers convert each other not through copy but by surfacing concrete administrative mechanisms — unusual circumstances override, 90-day SAVE recertification, §127 structural requirements, SAP appeal pathways. The tools CampaignForge builds need to package peer-insider quality natively, not just present math. That means output screens that sound like “here’s the specific administrative lever you can pull” rather than “here’s your calculated number.” Phase 3 tool blueprint implication.

Middle-income squeeze is a distinct adult-learner identity. Not a sub-segment of traditional undergrad — a named persona. The narrative: parents “made too much to qualify” for need-based aid but had no savings → student dropped out → returned 10 years later. Our 8 desire families (F1–F8) partially address this but don’t name it. Candidate F9 or cross-cutting persona in Phase 2 reality_map.json.

DEMO_KEY rate limits don’t match the docs. api.data.gov DEMO_KEY documented at 30 req/hour, actual behavior 10 req/hour. Single batched 10-school Scorecard query exhausted budget; subsequent calls returned HTTP 429 retry-after 12096s (3.3h). Operator-key path is unblocking and should be the default for any production data pull; DEMO_KEY is genuinely demo-only, not “light production.” Document upfront. 5 minutes of operator reCAPTCHA saves 3.3h of wait.

Government agency web is deteriorating; Firecrawl catches it, PDFs survive it. MT primary URL 404’d (tourism content returned); OR redesigned its entire student-aid portal; UT USHE site Wordfence-503-blocks all scraping; CT statute-database URL replaced by knowledge-base article; WY admin URL is the administering-institution’s (UW-SFA) page, not the state’s. Seven of the 14 re-pulled records required URL replacement. The authority-data-cache “source_url” discipline is load-bearing — when these URLs drift, our claims stop being traceable. For UT specifically: legislative appropriations + USHE PDF downloads survive Wordfence; HTML scraping does not. Next-pass planning needs to internalize that PDF + API survive where HTML decays.

Port verification is a one-time debt that prevents an infinite-sized future debt. Before this session, ~4,500 LOC of production JS had been reimplemented in TypeScript with only 3 trivial unit tests covering one helper function. No automated check existed that the TS produced identical outputs to the JS running on degreesources.com. Ship any design change or dep upgrade on top of that, and a silent formula drift would go undetected into production. 291 parity tests later, the drift window is closed — every tool's calculation branch has golden cases, and a regression fails the suite in milliseconds. The cost was one session. The cost of finding out about drift from a user's email about "wrong EFC number" is unbounded.

Diff line-by-line before writing tests, not after. For each tool the workflow was: (1) read source JS calculation block, (2) read port .logic.ts, (3) diff constants and formulas mentally, (4) only then write tests. Finding a match lets the tests lock in known-good behavior. Finding a mismatch would have meant fixing the port before writing the test — but none appeared, which is itself a finding: the port author stayed faithful to the source. Parity tests that pass first-run are not anti-climactic; they're the goal.

"Tools must work just like the current site" is more testable than it sounds. The operator's stated requirement reads like a vague UX promise. But tool behavior = pure functions from inputs to outputs, which is the most testable thing in software. Once restated as "for every documented input combination, TS output equals JS output," it becomes a bounded, finite verification task. Always convert fuzzy "just work like" requirements into explicit input/output golden-case assertions.

Session-end script: git add -u silently drops new files; -A is the fix. Session #20 commit missed Deliverable B artifacts because -u only stages modified tracked files. Switched to -A; safety is preserved because the per-repo confirm step shows git status --short (including ?? entries) before staging. Also caught ContentForge branch drift (main not master) in the config. Tooling bugs compound across sessions; fix them when you notice them, not later.

A 2026-current biosphere study is the compliance-angle-map's external-environment twin. Deliverable A mapped the compliance-restriction list to psychological-desire translations; Deliverable C maps the 12 major 2026 market forces (enrollment cliff, AI displacement, layoff waves, SAVE end, FAFSA recovery, Gen-Z skepticism, OBBBA, Workforce Pell, §127 permanence, Meta Ad Library, platform benchmarks) to what’s converting RIGHT NOW. Five forces structurally favor our tool-backed-proof thesis (not coincidentally — the pipeline was designed for this environment). The enrollment cliff isn’t a problem to solve; it’s the rationale for the vertical-shifting strategy. The wage-premium plateau is the single most important datapoint because it empirically validates Gen-Z’s skepticism — so ROI Calculator's honest-verdict framing becomes a trust-building asset, not a conversion liability. Competitors still selling “guaranteed ROI” are fighting 2020 research with 2020 claims in a 2026 market.

One Firecrawl batch keeps paying dividends if the cache layer is schema-disciplined. Session #20 emitted 88 Firecrawl scrape files into .firecrawl/gate3-b/. Session #21 emitted 37 additional state-aid records, 8 BLS SOCs, 5 IPEDS pilots, and source-cited all 12 biosphere-study sections — zero new Firecrawl spend, because Session #20’s scrapes already contained the authoritative content. Every emitted record carries schema_version + authority_tier + cache_refresh_date; 14 [VERIFY] flags are queued where specific 2026-27 dollar amounts need re-pull. The cache doesn’t need to be perfect at seed; it needs to be correctly structured and honestly flagged.

“Full 50-state coverage” and “full 10-school pilot” are orthogonal scope questions. Operator C6 lock requires 50-state coverage at Phase 2 seed (agent-driven Copy Factory per ADR 0009 has no phased-copywriter constraint). That’s binary — 50 states covered or not. IPEDS pilot is different: 10 schools is a partner-negotiation scope that can stretch across sessions without blocking Phase 3. Solution: ship 50-state primary-program coverage this session (achieved); ship 5 of 10 IPEDS pilots with [PENDING_API_PULL] markers for Scorecard metrics; queue remaining 5 + Scorecard API pull for next session. Distinguish “coverage mandate” from “depth target” up front or the scope swims.

Research sprints compound when batched in parallel with high-yield searches. 88 authoritative pages scraped across 6 parallel Firecrawl batches (federal, state × 7 sub-batches, military+tax+employer, niche-private, ranking-data APIs, verify-pass). Each firecrawl search --scrape returns multiple full authoritative pages in one call; batching them in background frees main context for structured-data emission. The real throughput multiplier isn't "scrape more" — it's "scrape once, emit structured records that feed every downstream deliverable." B.1 (75 records), B.2 (10 floor/multiplier stacks), B.3 (10 methodologies), B.4 (53 cache records) all sourced from the same 88 scrapes.

Truth is the moat, but only if every claim is resolvable to its source. Every record in B.1 + B.4 carries source_url + retrieval_date + recency_confidence + authority_tier. Any claim that couldn't be confirmed from Firecrawl content shipped with a [VERIFY] tag and operator-verification-pass queue — never a speculative value. Operator verify pass resolved all 6 flagged items via targeted Firecrawl scrapes (loan rates 6.39%/7.94%/8.94%, HHS 2026 poverty guidelines, Ch 30 MGIB-AD $2,518, §127 student-loan-payment made PERMANENT by OBBBA). Zero [VERIFY] markers remain in final shipped state.

Aggregator sources excluded by construction, not by review. authority_tier enum hard-codes {primary_gov, secondary_gov, accredited_private} — third_party_aggregator isn't a value that ships. This isn't a taste preference; it's regulator-defense architecture. When a challenge comes (Meta account review, FTC inquiry, competitor legal), every claim in copy traces to a cache record that traces to a primary-gov URL with release date. 54 primary_gov + 19 accredited_private + 2 secondary_gov (reciprocity compacts), 0 aggregators across 75 records.

Institution-first rankings compound; program-level is Phase 8 expansion. Ship 10 institution-level proprietary rankings immediately from Scorecard + IPEDS data (operator-locked). Program-level (4-digit CIP × institution joins) is genuinely higher-moat but requires more data engineering — Phase 8 scope. Three methodologies (Best Veteran-Friendly, Best GI Bill Value Max, Best Employer Partner Schools) are institution-level by nature and stay that way permanently. The other seven carry phase_8_expansion_target: "institution_and_program" so the Phase 5 agent knows what's coming.

Floor-to-multiplier ratios quantify the moat numerically. 10 tools × per-tool floor anchor vs. tool-proven multiplier: ratios range 2x (Financial Aid Quiz "FAFSA" → 3–5 aid categories) to 40x+ (Scholarship Finder "unclaimed billions" → $60K specific). The big numbers aren't marketing — they're what the math produces when you stack compliant resources for a qualifying profile. Ad copy uses typical case; tool output shows the user's specific number. Competitors can't follow because they don't have the tool to produce the math.

OBBBA changed §127 from temporary to permanent. The One Big Beautiful Bill Act made the student-loan-repayment inclusion in Section 127 educational assistance permanent (previously scheduled to expire 12/31/2025). This is load-bearing for the employer-benefit angle — no more sunset-clock framing on the $5,250 employer loan-repayment benefit. Every Employer Tuition Checker output can now cite permanence. Find the legislative changes that quietly enable new angles; they're the research edge.

Sync discipline: ClickUp is primary, not just STATUS/SESSION-LOG. Operator reminded at session #20 close — tracker sync at session end must include ClickUp (per ADR 0006) when tracker-relevant work happened. Saved as feedback_clickup_sync.md in memory. If STATUS.md moves forward and ClickUp doesn't, the operator-facing view diverges from the working view.

Research-sprint deliverables are agent inputs, not copywriter briefs. The breakthrough reframe this session: Stage 3 Copy Factory is a skill-based Claude agent, not a human-copywriter production line. Every schema field, every authority-data-cache record, every compliance rule, every tool-multiplier story becomes a parameter the agent reads at generation time. This inverts the constraint model — bandwidth is no longer the bottleneck, research-input rigor is. Moat is two-layered: research quality competitors can't match AND agent throughput competitors can't match at human-copywriter pace. ADR 0009 locks this thesis in.

Full 50-state coverage is sustainable because production is agent-driven. Initially scoped state coverage as phased copywriter depth (top-15 deep at launch, remaining 35 in Phase 5). Operator flagged the agent-driven nature of Copy Factory — all phased gating dissolved. authority-data-cache/state-aid/ covers all 50 states at Phase 2 seed; agent generates state × angle × platform × format matrix at every campaign run. Constraint shifts from hours to authority-data-cache completeness.

Channel the persona deliberately for judgment calls. When operator asked "answer from your 15-year perspective" on Gate 2 decisions, re-reading the v2 persona and deliberately channeling it produced substantively different answers than the default — categorical rather than hedge-y, strict rather than permissive (e.g., "universal skip YouTube Bumper when disclaimer won't fit", "strict 30-conv PMax bar, no lean seed", "PLUS-heavy red flag is factual"). The re-load triggers in CLAUDE.md aren't just cost-savings, they're judgment-quality gates.

Typical-case in ad copy, upper-bound as tool output. Distilled media-buyer discipline on multiplier framing: ad copy references the typical case ("most adults see $12–20K combined aid"); upper-bound numbers ($30K+, $65K/yr) only appear as tool output for users whose inputs produce them. Mixing the two in ad copy is the aggressive-affiliate pattern that burns accounts AND creates downstream lead-quality disasters (users expecting $30K, receiving $12K, churning through enrollment funnel, damaging school-partner relationships).

Compliance-and-CTR simultaneity is tool-discovery framing's signature. TikTok's restricted-industry scrutiny is aggressive for aid-claim copy. But tool-discovery framing ("take this 2-minute quiz to see what you qualify for") is BOTH the safer compliance posture AND the higher-CTR framing. Ad carries no standalone claim; tool on the lander carries substantiation. The moat pattern — tools-that-prove-claims — isn't just a moat, it's also the copywriting pattern that converts across every platform.

Plugin hooks can accumulate hidden tax. claude-mem's PreToolUse:Read hook was truncating file reads to line 1 when prior observations existed — a token-saving optimization that inverted into a capability regression for deep synthesis work (persona re-loads, spec reviews, multi-file research). Removed only that one hook (via jq 'del(.hooks.PreToolUse)'); kept every other claude-mem feature. Idempotent re-apply script because plugin updates will overwrite the patch. Lesson: "capability regression" can live inside what looks like a working plugin.

Operator's compounding-moat framing re-centers the work. The directive to "accumulate factual, true data across all possibilities that truly can benefit others, then condense that into useful, easy-to-use tools that output truthful quality results with a path for every consumer" is the project thesis in one sentence. Every research gap becomes a ceiling on output quality; every layer of rigor becomes throughput at output. Keep this framing front of mind for every future agent — research is not overhead, it is the moat made tangible.

Cloudflare Access cannot pre-gate a Pages custom domain during initial SSL provisioning. The ACME HTTP-01 challenge to /.well-known/acme-challenge/* is intercepted by the Access gate, blocking Google CA cert issuance. Workaround: delete the Access app → let cert issue (~15s once unblocked) → recreate the Access app. Brief public window is acceptable when the URL isn't advertised yet. Order-of-operations trap — gate pre-seeding doesn't work end-to-end for brand-new hostnames.

Pages.dev hostnames can't have direct Access apps. They belong to Cloudflare's shared zone owned by Cloudflare itself, not your account. Error 12130 "domain does not belong to zone". Always bind a custom subdomain from a zone in the same account as the Pages project, then gate the custom subdomain. The raw .pages.dev URL stays public and needs a separate noindex mechanism.

GitHub repo is locked to one CF account at a time. Disconnecting the CF Pages GitHub App from a repo does NOT clear CF's internal account-repo binding — only deleting the Pages project in the other account fully frees the repo. Error 8000093 means: "delete the conflicting project." Don't try to disconnect the GitHub App as a shortcut; check which account currently owns the binding and do cleanup there first.

CF doesn't support account merging. Manual migration: zones move cleanly via "Move Domain" (preserves all DNS records, no nameserver change); Pages/Workers/R2/KV/D1 must be recreated in target (destructive, lose history). Pick master by which account holds the most infrastructure, not the most domains. Moving a zone that has a bound Pages custom domain BREAKS that binding until the Pages project is re-homed to match — coordinate those two migrations together.

Canonical tag is advisory, not authoritative. Google may still crawl and index .pages.dev URLs despite <link rel="canonical"> pointing to production. Host-scoped X-Robots-Tag: noindex via Pages public/_headers is the authoritative signal. Don't rely on canonical alone for indexing control.

DNS on a prod zone is safe for new subdomains — but verify no wildcards first. Adding a new subdomain CNAME is isolated from root/www/MX records. But if the zone has a wildcard CNAME (*.example.com), an explicit new record overrides the wildcard for that host — could surprise downstream systems. Always grep DNS list for wildcards before committing new records to a prod zone.

After session compaction, restate the intended next action before producing substantive artifacts. Session #18 opened with the system-start context pointing at a Phase 2 Session 2 bootstrap prompt; agent assumed that meant "execute now" and produced a 260-line canonical tool spec. Operator was mid-Cloudflare-work from the prior session and confused by the pivot. Better pattern: after compact, briefly surface the ambiguous thread ("X was queued before compact, Y was just referenced — which one?") and await explicit confirmation before producing substantive artifacts. The work wasn't wasted (the EFC spec becomes the template for remaining 9), but the redirect cost a full round-trip of context.

Compliance is an angle-generation input, not a guardrail. The restricted-claims list is literally the cheat sheet for what converts — each restriction exists because the underlying psychological desire converts hard. Map every restriction to its desire family, the Layer-1 triggers that deliver that desire, and the tool-backed compliant framing that lands harder than the non-compliant original.

Disclaimers are conditional on ad-claim content, not platform/format. Tool-discovery framing ("See what you could qualify for") makes no standalone claim — the tool + 2–3K-word article lander carries all required disclosures with cited sources and freshness dates. In-ad disclaimers only trigger when the ad itself makes a specific claim (dollar amount, named government program, income claim). Tool-discovery framing is simultaneously the best-CTR AND most-compliant framing — not a coincidence.

Proprietary rankings from public gov data beats third-party whitelist. College Scorecard + IPEDS + BLS + VA data let us build our own defensible ranking system with full methodology transparency. No usage-rights gating, no publication bias, no expiration. Essentially "US News for online education" built from public gov data — an angle space competitors can't replicate.

Pattern-detect meta-specs. Three distinct questions (IPEDS cache, proprietary rankings, BLS wage refresh) had the same structural answer: authority-tier data cache with freshness tracking, cron-refreshed, read by Phase 5 with automated staleness halts. Consolidating into one authority-data-cache infrastructure spec beats three separate specs that repeat the same logic.

Persona re-load has empirical basis. Not superstition — output quality degrades every 4–5 turns as attention weight on the persona decays relative to accumulated context. Re-reading restores signal strength via token recency + repetition. CLAUDE.md now codifies: reload on strategic triggers + every ~5 turns in long sessions + every natural phase boundary. NOT every turn (wasteful, dilutes attention on actual work).

Tool-discovery framing is the workflow cheat-code. The same pattern that solves compliance (route substantiation to lander) also solves CTR (no in-ad disclaimer drag) and lead quality (friction-as-feature qualifies users). Three optimization goals aligned in one architectural choice.

Diagnose before adding. Session surfaced that Firecrawl skill wasn't firing, continuous-learning-v2 looked dormant, session-end was manual. Diagnosis revealed: Firecrawl was CLI-skill-vs-MCP-mismatch (fixable by rewiring deep-research); continuous-learning-v2 had 7.7MB of observations accumulated but observer.enabled: false was blocking the analysis phase (one config flag fix); session-end was genuinely manual (built scripts/session-end.sh safe multi-repo helper). Don't install — diagnose first. Most "missing" capabilities are broken capabilities.

Agents process early rules more heavily: Adding HARD RULES blocks at the top of each skill file ensures non-negotiable constraints are in the "hot zone" of agent attention. Rules buried mid-document get diluted by accumulated context.

Decision trees > prose guidance: Converting "consider X when Y" into "IF X THEN Y, OTHERWISE Z" produces more reliable agent behavior. Agents follow explicit branches; they interpret flexible guidance flexibly (which means inconsistently).

Anti-patterns are as powerful as patterns: Showing agents what NOT to produce (with concrete BAD examples and WHY explanations) creates hard boundaries. Without anti-patterns, agents gravitate toward "safe" generic output that passes no rules but also creates no value.

Subagent permissions are session-scoped, not inherited: Adding permissions to settings.local.json or project settings doesn't reliably propagate to subagents in don't-ask mode. Python/Bash fallback for file writes is the workaround. Some agents succeed, some don't — the behavior is inconsistent and needs investigation.

Sweet spot is 3-4 parallel agents: Beyond 4, prompt quality drops and merge review gets sloppy. The real constraint is file isolation, not compute. With 3 repos, the ceiling is ~5 agents if file boundaries are clean.

Feature branches prevent same-repo conflicts: Agents C and D in campaignforge-app worked on separate branches (feat/cost-session-manager, feat/pipeline-orchestrator), then merged sequentially. Zero conflicts.

Independent agents can converge on identical fixes: Both the a11y and Lighthouse agents independently identified and fixed the same CSS cascade issue (@layer base wrapping, :where() scoping) with byte-identical diffs. Merge was clean because Git detected identical changes.

CAPI Worker type errors are IDE-only: Cloudflare Workers have their own tsconfig with @cloudflare/workers-types. The IDE picks up the root tsconfig which doesn't know about Request/Response/fetch globals. Not real errors.

MDX body_html requires JSX-safe formatting: Raw HTML from JSON has nested block elements on same lines, bare <br> tags, and ~ chars parsed as strikethrough. Conversion script needed multi-pass formatting: self-close void tags, escape tildes to ~, and split every block element onto its own line.

Astro dynamic components need static imports: client:visible hydration fails with dynamic component references (NoMatchingImport). Must use conditional static rendering: {tc === 'EFCCalculator' && <EFCCalculator client:visible />}.

Parallel agents for tool implementations: 4 agents dispatched simultaneously, each handling 2-3 tools. All completed in ~17 minutes. Logic/data separation (*.logic.ts, *.data.ts) enabled clean parallelization with zero merge conflicts.

Astro 5 Content Layer API: entry.render() is gone. Use import { render } from 'astro:content' then render(entry). Content collections need glob() loader from astro/loaders.

shadcn-svelte + Tailwind v4: @apply border-border fails — Tailwind v4 doesn't know custom vars via @apply. Use @theme inline to declare all HSL color vars, then use raw CSS instead of @apply for base styles.

shadcn-svelte components need WithElementRef: The cn utility must also export WithElementRef and WithoutChildrenOrChild types for sidebar/rail components.

MDX in Content Collections: HTML (tables, callouts, step-lists) works inline in MDX. No need to convert to custom components yet — the prose CSS styles handle it.

Astro 5 Content Collections: Uses src/content.config.ts (not src/content/config.ts). The z import from astro:content shows deprecation warnings.

Tailwind v4: No tailwind.config.ts needed. Uses @tailwindcss/vite plugin. The @astrojs/tailwind integration conflicts — use the Vite plugin directly.

Remote agents failed: Overnight scaffold agents couldn't auth with GitHub. Local execution worked first try.