Unified Spec System — Handoff

What Was Built (2026-04-15)

The Problem Solved

Agents kept re-discovering context from scratch every session. Specs, tests, and acceptance docs lived in 4+ places with no single index. This system gives any agent ONE place to look.

The Architecture

knowledge/tests/specs/<id>.yaml        ← SOURCE OF TRUTH (you write here)
         ↓  GitHub Action on push to master
test_specs (Supabase table)            ← QUERYABLE by agents at runtime
         ↓  generate-spec-pages.ts at docs-portal prebuild
docs.churchwiseai.com/tests/specs      ← HUMAN-READABLE portal

One YAML file per test spec. Playwright .spec.ts files are implementations. Acceptance .md files are detailed expected-output docs, linked FROM YAML.

Files Created

File	Purpose
knowledge/tests/specs/*.yaml	25 canonical spec files
knowledge/tests/specs/_schema.md	Field reference for writing specs
knowledge/tests/specs/_schema.json	JSON Schema for CI validation
knowledge/tests/specs/README.md	How to add specs
knowledge/.github/workflows/sync-specs-to-db.yml	Auto-syncs YAML → DB on push
docs-portal/scripts/generate-spec-pages.ts	YAML → MDX portal pages at build

Supabase

• Table: test_specs — 25 rows, RLS enabled (service_role write, anon/auth read)
• FK: manual_test_reports.spec_id → test_specs.id (nullable, for legacy rows)
• Migration: pewsearch/migrations/20260415_unified_test_specs.sql (applied)

Portal

• URL: https://docs-portal-chi.vercel.app/tests/specs
• Navbar: "Test Specs" link added
• Auto-build: Every push to knowledge master triggers Vercel rebuild

---

Current Coverage: 25 / ~110 Specs

Written ✅

ID	What it covers
stripe-live-checkout	CRITICAL PATH — Stripe checkout → webhook → provisioning
acceptance-starter-chat	Starter Chat tier entitlements
acceptance-starter-voice	Starter Voice tier entitlements
acceptance-starter-both	Starter Both bundle
acceptance-pro-suite-chat	Pro Suite Chat tier
acceptance-pro-both	Pro Both bundle
acceptance-trial-expired	Trial expiry graceful downgrade
visitor-uses-chatbot	Visitor chatbot experience
production-smoke	All sites up smoke test
cwa-01-discovery through cwa-08-upgrade	Full pastor lifecycle (8 specs)
pastor-discovers-and-signs-up	End-to-end acquisition journey
persona-pastor-ai-skeptic	AI skeptic persona
persona-pastor-tiny-church	Tiny church persona
theology-vocabulary	Denomination vocabulary accuracy
consistency-price-matching	Prices match pricing.yaml
pewsearch-claim-flow	PewSearch church claim
security-edge-cases	Auth/RBAC/XSS/injection
sermonwise-signup-and-generate	SermonWise first sermon

Still Needed (~85 more)

Pick up from this list of existing Playwright specs — one YAML per file:

Tier acceptance (e2e/delivers/acceptance/):

• itw-premium, pewsearch-premium, pewsearch-pro-website, pro-suite-chat, suite-both, sermonwise-pro, cancelled

Customer lifecycle (e2e/delivers/churchwiseai/): All 8 done ✅

Personas (e2e/delivers/personas/):

• board-leader-mark-evaluator, committee-buyer-board-meeting, deacon-bob-board-evaluation
• karen-privacy-paranoid, mark-mega-church-it, pastor-maria-catholic-journey
• pastor-steve-burned, youth-pastor-jake-mobile

Theological (e2e/delivers/theological/):

• landing-pages, safety-crisis, vocabulary-all-lenses, vocabulary-baptist
• vocabulary-catholic, vocabulary-orthodox, vocabulary-pentecostal, vocabulary-reformed

Consistency (e2e/delivers/consistency/):

• feature-claims, product-knowledge-alignment, stale-copy-detection

Cross-property (e2e/delivers/cross-property/):

• itw-to-sermonwise, pewsearch-to-cwa-upsell

Known bugs (e2e/delivers/known-bugs/):

• cwa-demo-phone-labels, cwa-no-post-signup-explanation, cwa-pricing-paralysis
• itw-irrelevant-on-this-day, pewsearch-search-returns-all

SermonWise (e2e/delivers/sermonwise/):

• 01-discovery, 02-understanding, 04-daily-use, sermonwise-homily-missing

Journeys (e2e/journeys/):

• admin-daily-dashboard, cancelled, denomination-experience
• pro-both, pro-suite-chat, sermonwise-pro, starter-both, suite-both, trial-expired

CRUD (e2e/crud-*.spec.ts):

• crud-admin-care, crud-admin-settings, crud-admin-training, crud-chatbot
• crud-contact, crud-social-campaigns, crud-social-platforms, crud-social-posts, crud-social-settings

Edge cases (e2e/edge-*.spec.ts):

• edge-chatbot, edge-cross-site, edge-input-validation, edge-rate-limiting

Other:

• admin-dashboard, api, api-new-routes, care, email-link-audit
• env-integration, journey-all-products, journey-chatbot-config, journey-chatbot-signup
• journey-external-products, journey-sermon-checkout, journey-suite-signup
• legal-pages, onboard, p2-security, p4-seo-metadata, p5-content-accuracy
• p7-branding, payment-flow, production-journeys, sermon-generation
• sermonwise-full, smoke, social-advanced, social-api, social-smoke
• stripe-synthetic-validator, visual, visual-mobile

---

How to Add a New Spec

1. Create knowledge/tests/specs/<id>.yaml using _schema.md as reference
2. Push to master
3. GitHub Action syncs to test_specs DB automatically
4. Vercel rebuilds portal with new page automatically

Agent query pattern:

-- Find all specs for a feature area
SELECT id, title, critical_path, playwright_ref
FROM test_specs
WHERE property = 'churchwiseai-web'
  AND category = 'onboarding'
ORDER BY critical_path DESC, title;

-- Find critical path specs
SELECT id, title, spec_file_path
FROM test_specs
WHERE critical_path = TRUE;

---

Drift Prevention

When you change a code file, check if it's in any spec's linked_code_files:

SELECT id, title, spec_file_path
FROM test_specs
WHERE steps::text ILIKE '%webhook%'  -- or search by code file pattern

The GitHub Action in knowledge/.github/workflows/sync-specs-to-db.yml keeps the DB in sync. The portal auto-rebuilds on every push. The only manual step is writing the YAML — everything else is automatic.