DeCentN2Madness/aia-website
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(forms): adopt two-form consultation architecture

Browse Source
This commit is contained in:
DeCentN2Madness committed 2026-10-28 18:51:42 -07:00
1 parent ebc99c0f36
commit 6a5e54e130
10 files changed
+198 -89
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

www/reports/phase-9-jotform-integration-contract-2026-10-18.md
+38 -34
View File
@@ -1,12 +1,12 @@
# P9-03 Jotform integration contract
**Contract ID:** P9-03-JF-2026-10-18 · **Version:** 1.6 · **Decision revision:** 2026-10-28
**Contract ID:** P9-03-JF-2026-10-18 · **Version:** 1.7 · **Decision revision:** 2026-10-28
**Status: Form A owner-approved; production-gated adapter prepared locally; deployment and site release NOT authorized.**
**Status: Form A owner-approved for existing contexts; two-form consultation direction documented; deployment and new-route activation NOT authorized.**
This is the authoritative P9-03 planning contract for the owner decisions supplied on October 18 and revised through October 28. It supersedes conflicting *proposals* in the [October 17 inventory](phase-9-form-entry-point-inventory-2026-10-17.md), without rewriting that historical record. It does not supersede project policy, approve clinical/legal content beyond the Form A configuration scope recorded below, close the Phase 9 register, or authorize production changes. Future changes require an explicit owner decision, a version/change record and evidence links. Version 1.0 records the original planning instruction; version 1.1 adds the owner-supplied complete roster; version 1.2 supersedes the copy-based Form B proposal with three new blank forms; version 1.3 records limited owner-confirmed Form A configuration evidence; version 1.4 reconciles completed direct-Jotform testing and the seven-route isolated iframe adapter; version 1.5 records owner-reported embedded synthetic acceptance for sampled routes; version 1.6 adds the independent production-build gate without deploying it. No future commit SHA is invented.
This is the authoritative P9-03 planning contract for the owner decisions supplied on October 18 and revised through October 28. It supersedes conflicting *proposals* in the [October 17 inventory](phase-9-form-entry-point-inventory-2026-10-17.md), without rewriting that historical record. It does not supersede project policy, approve clinical/legal content beyond the Form A configuration scope recorded below, close the Phase 9 register, or authorize production changes. Future changes require an explicit owner decision, a version/change record and evidence links. Version 1.0 records the original planning instruction; version 1.1 adds the owner-supplied complete roster; version 1.2 supersedes the copy-based Form B proposal with three new blank forms; version 1.3 records limited owner-confirmed Form A configuration evidence; version 1.4 reconciles completed direct-Jotform testing and the seven-route isolated iframe adapter; version 1.5 records owner-reported embedded synthetic acceptance for sampled routes; version 1.6 adds the independent production-build gate without deploying it; version 1.7 retires physical Form B and specifies Form A consultation plus Form C referral planning. No future commit SHA is invented.
Companions: [source-specific implementation plan](phase-9-jotform-implementation-plan-2026-10-18.md), [verification and approval ledger](phase-9-jotform-verification-checklist-2026-10-18.csv).
Companions: [source-specific implementation plan](phase-9-jotform-implementation-plan-2026-10-18.md), [two-form integration specification](phase-9-two-form-integration-specification-2026-10-28.md), [verification and approval ledger](phase-9-jotform-verification-checklist-2026-10-18.csv).
## 1. Verified repository and evidence provenance
@@ -32,8 +32,8 @@ Evidence classes must remain distinct:
- AIA uses Jotform Gold with HIPAA enabled and a signed Jotform BAA; 27 of 100 form slots are occupied. Existing clinical/operational workflows must remain intact.
- **All public lead submissions go directly to Jotform.** No Contabo submission proxy, PHI-bearing webhook, completed form-data forwarding or clinical-document transfer to Contabo.
- Prefer iframe presentation, preserving Astro design and locale behavior; use a hosted form fallback where embedding is unsuitable.
- Use three logical forms: **A General Enquiries, B Service Consultations, C Professional Referral Initiation**. Prefer one EN/ES multilingual physical form for each where verified; separate EN/ES copies are a fallback requiring approval.
- **Create three new forms from blank forms:** A General Enquiries, B Service Consultations and C Professional Referral Initiation. Do not clone or repurpose an existing operational form. The former proposal to use a working copy of **AIA Lead Generator | plain** is superseded.
- Use two physical forms: **A General Enquiries, landing enquiries and family service consultations**, and **C Professional Referral Initiation**. Form A retains its existing `contact` and `landing` contexts; `consultation` is planned only. `service` may remain a logical visitor-intent classification, not a separate physical form.
- **Physical Form B is retired.** Do not create, clone or repurpose a separate service-consultation form. Form C alone remains a future blank-form creation task; the former proposal to use a working copy of **AIA Lead Generator | plain** remains superseded.
- The historical source ID `250727122848156` remains reference evidence only. It must not be modified, cloned, disabled, deleted, repurposed or used as an embed destination under this decision. Existing clinical, agreement, billing, event, HR, administrative and CentralReach workflows remain independent.
- No appointment booking in initial consultation forms. Staff contact the family to arrange follow-up.
- Begin with the generic Jotform notification in section 8, subject to actual settings/recipient/privacy review. Timestamps and campaign labels are deferred.
@@ -127,19 +127,19 @@ The plain form's reported update timestamp is `2026-05-07 22:27:30`, timezone un
The operational consultation form includes adult contact/service/payment, child name/age, appointment date/time, address, area, source and comments. None is adopted merely because present. The richer Lead Generator's broad children/teens and service/waitlist claims require current organizational review.
**No production embed ID is assigned for A, B or C.** All four existing IDs above are evidence references only. The former source B ID must be rejected as a clone, working-copy or live mapping. Account slot availability is not creation permission; three new forms would provisionally mean 30/100, subject to actual account-limit verification.
**Form A alone has an approved ID for its existing fixed contexts.** Form C has no ID; physical Form B is retired and has none. All legacy IDs above remain evidence references only. The former source B ID must be rejected as a clone, working-copy or live mapping. Account capacity does not establish creation or configuration permission.
### Revised blank-form decision and legacy review
The owner has selected **three purpose-built forms created from blank Jotform forms**. This avoids inheriting legacy fields, stale service/location/insurance language, conditional logic, recipients, attachments, redirects or other operational settings. The physical target is three forms, with one EN/ES multilingual configuration per form where Builder and runtime verification support it; separate language forms remain a fallback requiring approval.
The owner now selects **two physical Jotform forms**. Existing Form A is extended only after acceptance of its planned `consultation` context; Form C is the sole new blank form. This avoids a separate legacy-derived service form and preserves all existing operational workflows. One EN/ES multilingual configuration per form remains preferred where Builder and runtime verification support it; separate language forms remain a fallback requiring approval.
Each new form is to remain disabled during configuration, use minimum-necessary fields with PHI protection enabled by default, begin with built-in confirmation, and have no unapproved integrations, webhooks, answer-forwarding, PDFs or dynamic notification fields. A short English/Spanish family acknowledgment may be considered later, but it requires language, privacy and account-owner approval and must not echo submitted information.
The new Form C and any unapproved Form A consultation configuration are to use minimum-necessary fields with PHI protection, built-in confirmation, and no unapproved integrations, webhooks, answer-forwarding, PDFs or dynamic notification fields. A short English/Spanish family acknowledgment may be considered later, but it requires language, privacy and account-owner approval and must not echo submitted information.
The owner also reports remediation of the existing `AIA Lead Generator | plain` form: all fields marked PHI-protected, automatic email-template updates disabled, autoresponder content revised to exclude submitted PHI, Spanish autoresponder behavior checked, email delivery tested by the owner and the generated submission PDF attachment removed. These are owner-reported actions, not an independent audit or HIPAA certification. Historical notification recipients, access, retention, delivery, other legacy forms and actual account settings remain separate privacy/operational review items. No submissions or historical emails were accessed.
## 4. Proposed semantic field contracts
## 4. Semantic field contracts
Names below are domain semantics only, **not Jotform question IDs, uniqueName values, URL-prefill keys or actual schemas**. Operations, clinical and privacy approval remain pending.
Names below are domain semantics only, **not Jotform question IDs, uniqueName values, URL-prefill keys or actual schemas**. The v1.7 two-form contract supersedes former physical Form B planning; the historical B rows below remain only as dated decision evidence. Current future specifications are in [the two-form integration specification](phase-9-two-form-integration-specification-2026-10-28.md). Operations, clinical and privacy approval remain pending.
| Form | Semantic field | Proposed requirement |
|---|---|---|
@@ -150,15 +150,17 @@ Names below are domain semantics only, **not Jotform question IDs, uniqueName va
| A | preferred_contact | Optional; define valid choices and phone/email consistency |
| A | message | Omit by default; add only with explicit approval |
| A | source_code | Deferred; absent initially |
| B | adult_name | Required |
| B | adult_email | Required |
| B | adult_phone | Operations decision pending; no implied default requirement |
| B | service_interest | Required, approved controlled selection |
| B | payment_category | Optional, approved categories only |
| B | service_area | Optional city/area; not full address |
| B | preferred_contact | Optional; define consistency with available contact fields |
| B | message | Prefer omitted; owner review |
| B | source_code | Deferred; absent initially |
| A / consultation | service_interest | Required controlled choice after Builder/clinical/privacy approval; no ID or option value inferred |
| A / consultation | evaluation_explanation | Conditional referral-assistance explanation only; no claim of in-clinic diagnostic availability |
| B (retired) | adult_name | Historical proposal only; not a physical-form requirement |
| B (retired) | adult_email | Historical proposal only |
| B (retired) | adult_phone | Historical proposal only |
| B (retired) | service_interest | Historical proposal only |
| B (retired) | payment_category | Historical proposal only |
| B (retired) | service_area | Historical proposal only |
| B (retired) | preferred_contact | Historical proposal only |
| B (retired) | message | Historical proposal only |
| B (retired) | source_code | Historical proposal only |
| C | professional_name | Required |
| C | organization | Required |
| C | work_email | Required |
@@ -169,9 +171,9 @@ Names below are domain semantics only, **not Jotform question IDs, uniqueName va
**A:** General website/contact enquiries; Tour only if approved. Fundraising and other organizational types require explicit additions. Existing event workflow is not included. No child name/DOB, diagnosis, records, address, calendar or unnecessary free text.
**B:** Consultation for ABA, Learner Social Club, approved evaluation availability, and approved commercial/AHCCCS/private-pay branches. Proposed service semantics: `aba`, `learner_social_club`; `autism_evaluation` only after availability review; `other` only if approved. General ABA baseline: **18 months through eight years**. Learner Social Club: separate **private-pay program ages 8–17** per owner direction. Academy-specific ages/ratios are not generalized to either form. No automatic carryover of Tricare, CareCredit, Glendale, waitlist, enrollment or guaranteed-admission claims. Payment/service-area options need current operational approval.
**B (retired as a physical form):** The following was the former consultation proposal and is retained only as history. Form A `consultation` now carries the approved service choices described in the two-form specification. Proposed service semantics: `aba`, `learner_social_club`; `autism_evaluation` only after availability review; `other` only if approved. General ABA baseline: **18 months through eight years**. Learner Social Club: separate **private-pay program ages 8–17** per owner direction. Academy-specific ages/ratios are not generalized to either form. No automatic carryover of Tricare, CareCredit, Glendale, waitlist, enrollment or guaranteed-admission claims. Payment/service-area options need current operational approval.
B excludes child name, exact DOB, diagnosis, clinical history, records/uploads and appointment calendar unless separately approved within an appropriate protected workflow. Staff arrange follow-up; no promise of a booked appointment. Existing booking-oriented site headings are an editorial approval item, not permission to silently rewrite metadata or body content.
The planned Form A consultation context excludes child name, exact DOB, diagnosis, clinical history, records/uploads and appointment calendar unless separately approved within an appropriate protected workflow. Staff arrange follow-up; no promise of a booked appointment. Existing booking-oriented site headings are an editorial approval item, not permission to silently rewrite metadata or body content.
**C:** New dedicated form only after creation authorization. Initial professional contact, not patient-record transfer. No patient name/DOB, diagnosis narrative, medical document or protected case detail. Detailed referral belongs in a separately approved protected workflow. Existing clinical/CentralReach paths remain unchanged.
@@ -185,19 +187,19 @@ Cross-checked against F-001–F-009 in the local CSV, current source and eligibl
|---|---|---|---|---|
| F-001 | `/contact` | EN | `src/components/ContactForm.astro:17`, via `components/pages/ContactPage.astro:19` | A |
| F-002 | `/es/contact` | ES | Same, explicit locale | A ES |
| F-003 | `/client-consultation` | EN | `src/components/FormShell.astro:12`, `layouts/PageLayout.astro:15,82` | B |
| F-004 | `/es/client-consultation` | ES | Same, explicit locale | B ES |
| F-005 | `/schedule-consultation` | EN | Same FormShell | B |
| F-003 | `/client-consultation` | EN | `src/components/FormShell.astro:12`, `layouts/PageLayout.astro:15,82` | Form A / planned `consultation` |
| F-004 | `/es/client-consultation` | ES | Same, explicit locale | Form A / planned `consultation` |
| F-005 | `/schedule-consultation` | EN | Same FormShell | Form A / planned `consultation` |
| F-006 | `/referrals` | EN | Same FormShell; CTA `#form-title` | C |
| F-007 | `/aba-therapy` | EN | `src/components/ServiceInquiryDrawer.astro:71`, `layouts/PageLayout.astro:81` | B / approved ABA context |
| F-008 | `/autism-evaluations` | EN | Same drawer | B only after availability/copy approval |
| F-009 | `/learner-social-club` | EN | Same drawer | B / approved Social Club context |
| F-007 | `/aba-therapy` | EN | `src/components/ServiceInquiryDrawer.astro:71`, `layouts/PageLayout.astro:81` | Form A / planned `consultation`; drawer redesign pending |
| F-008 | `/autism-evaluations` | EN | Same drawer | Form A / planned `consultation` only after referral-assistance/copy approval |
| F-009 | `/learner-social-club` | EN | Same drawer | Form A / planned `consultation`; program approval pending |
Three implementations, nine instances: seven EN, two ES, zero AR. Eleven GET search instances are not lead forms and must not be disabled or routed to Jotform. No new Arabic form or translated publication is authorized. Spanish service pages currently use Spanish consultation CTAs, not drawers. Arabic visitors retain established English fallbacks and clear language notices. All three logical forms prefer EN/ES capability, but no Spanish referral page or new route is implied.
Three implementations, nine instances: seven EN, two ES, zero AR. Eleven GET search instances are not lead forms and must not be disabled or routed to Jotform. No new Arabic form or translated publication is authorized. Spanish service pages currently use Spanish consultation CTAs, not drawers. Arabic visitors retain established English fallbacks and clear language notices. The two physical forms prefer EN/ES capability, but no Spanish referral page or new route is implied.
The five imported landing-page journeys—`/lp/aba-therapy`, `/lp/aba-insurance`, `/lp/aba-ahcccs`, `/lp/aba-private-pay` and `/lp/early-intervention`—are owner-approved **Form A** isolated-test placements, each using fixed `formContext=landing&language=en`. This supersedes their earlier Form B mapping only for these five journeys. Form B remains for other service-consultation journeys requiring its additional approved fields. The five panels do not add five native form implementations, and Form A remains unavailable in normal, indexing-enabled and production-shaped artifacts.
The five imported landing-page journeys—`/lp/aba-therapy`, `/lp/aba-insurance`, `/lp/aba-ahcccs`, `/lp/aba-private-pay` and `/lp/early-intervention`—are owner-approved **Form A** isolated-test placements, each using fixed `formContext=landing&language=en`. This supersedes their earlier Form B mapping. Physical Form B is retired; other service-consultation journeys are future Form A `consultation` targets and are not yet iframe placements. The five panels do not add five native form implementations, and Form A remains unavailable in normal, indexing-enabled and production-shaped artifacts.
Tour's actual CTA currently goes to `/client-consultation` (B destination). A is the provisional proposed Tour mapping, **not a completed route change**. Fundraising awaits owner confirmation. Historical event requests remain separate; do not reinterpret the historical Eventbrite link as the account's Event Submission Form without evidence. `/client-forms` retains existing clinical, agreement, Sign and CentralReach links. The six repository-linked Jotform destinations are not automatically matched to the four named account assets.
Tour's actual CTA currently goes to `/client-consultation`, a future Form A `consultation` destination. Its service list has no tour choice, so the Tour disposition remains an intake/operations decision, **not a completed route change**. Fundraising awaits owner confirmation. Historical event requests remain separate; do not reinterpret the historical Eventbrite link as the account's Event Submission Form without evidence. `/client-forms` retains existing clinical, agreement, Sign and CentralReach links. The six repository-linked Jotform destinations are not automatically matched to the four named account assets.
`/lp/early-intervention` and the provisional local `/client-consultation` substitution remain P9-01 decisions. Campaign landing pages outside this repository are out of scope. Phone/email legacy-target issues in the inventory remain unresolved; no target is silently replaced.
@@ -228,7 +230,7 @@ Suggested semantic setting: `PUBLIC_AIA_FORMS_MODE`, exact values `off`, `mock`,
| off | No active lead form/empty POST action, live iframe, Jotform preconnect/helper/network request, or analytics. Render approved localized contact fallback; no native-submit bypass on inactive lead UI |
| mock | Synthetic local-only fixture, no external endpoint or real data; safe guarded Playwright use; no Jotform ID required |
| isolated-test | Form A only: requires `PUBLIC_AIA_FORMS_MODE=isolated-test`, `PUBLIC_AIA_FORMS_ENVIRONMENT=isolated-test`, `PUBLIC_AIA_FORMS_ISOLATED_TEST_APPROVED=true`, `PUBLIC_AIA_FORMS_LIVE_APPROVED=false`, `PUBLIC_ALLOW_INDEXING=false`, and a fixed seven-route allowlist. It is not a production mode. |
| live | Form A only: `PUBLIC_AIA_FORMS_MODE=live`, `PUBLIC_AIA_FORMS_LIVE_APPROVED=true`, `PUBLIC_AIA_FORMS_ENVIRONMENT=production`, and `PUBLIC_AIA_FORM_A_PRODUCTION_APPROVED=true` are all required. The fixed seven-route allowlist, fixed origin/URLs, locale and context still apply. Missing/invalid values fail closed. `PUBLIC_ALLOW_INDEXING` is independent: it must be `true` for an indexing-enabled release but cannot enable Form A alone. Forms B/C and all other lead surfaces remain off. |
| live | Form A only: `PUBLIC_AIA_FORMS_MODE=live`, `PUBLIC_AIA_FORMS_LIVE_APPROVED=true`, `PUBLIC_AIA_FORMS_ENVIRONMENT=production`, and `PUBLIC_AIA_FORM_A_PRODUCTION_APPROVED=true` are all required. The fixed seven-route allowlist, fixed origin/URLs, locale and context still apply. Missing/invalid values fail closed. `PUBLIC_ALLOW_INDEXING` is independent: it must be `true` for an indexing-enabled release but cannot enable Form A alone. Form C and all other lead surfaces remain off. |
Off/mock output must not contain **new lead embed IDs/URLs or the historical `250727122848156` reference ID** in HTML, scripts, preload hints or client bundles. Existing clinical/Sign links intentionally remain in the site; they already contain production destinations. Preserving them conflicts with a blanket “no production ID anywhere” assertion, so this contract's new-embed restriction is scoped to the new lead integration. Existing user-initiated clinical navigation is not permission for automatic loading or test submissions. Do not claim the whole site has zero vendor destinations.
@@ -257,7 +259,7 @@ Jotform's [HIPAA email guidance](https://www.jotform.com/help/504-how-to-use-not
## 9. Blank-form creation safety and success measurement
No form creation or original mutation is authorized now. Batch B may create exactly three disabled blank forms only after explicit Jotform mutation authorization naming the forms, account, reviewers, environment and stopping conditions. The new forms must be configured from the approved minimum field contracts, with PHI protection and generic notification defaults reviewed before any synthetic submission. Do not clone, copy, import or repurpose an existing form, and never copy submissions.
No form creation or original mutation is authorized now. A future configuration batch may add Form A `consultation` and create one disabled blank Form C only after explicit Jotform mutation authorization naming the scope, account, reviewers, environment and stopping conditions. The new forms must be configured from the approved minimum field contracts, with PHI protection and generic notification defaults reviewed before any synthetic submission. Do not clone, copy, import or repurpose an existing form, and never copy submissions.
The historical [cloning guide](https://www.jotform.com/help/27-how-to-clone-an-existing-form-from-your-account/) remains evidence for why the owner rejected inheritance: copied forms can carry email settings, recipients and workflow/thank-you behavior, with account-specific treatment of integrations and protection requiring verification. It is not an implementation path. The old source ID `250727122848156` remains reference-only and must be rejected by any future configuration validator. Account capacity does not establish creation permission.
@@ -267,7 +269,7 @@ No Google Ads/GA4/GTM, enhanced conversions, remarketing, tracking scripts, cust
## 10. Owner approval ledger
All implementation approvals below are **Pending**. Organizational selection of Jotform/three forms is already recorded; it does not resolve these gates.
All implementation approvals below are **Pending**. Organizational selection of Jotform/two physical forms is already recorded; it does not resolve these gates.
| ID | Owner role | Approval/evidence required |
|---|---|---|
@@ -305,3 +307,5 @@ Version 1.4, 2026-10-28: records owner-confirmed direct Form A EN/ES synthetic s
Version 1.5, 2026-10-28: records the owner's successful embedded synthetic submission and native-confirmation report for English contact, Spanish contact and an ABA landing placement. It marks Form A functional submission acceptance complete only for those owner-reported samples, explicitly keeps the third route name to be recorded, and retains seven-route accessibility, runtime/privacy, deployment and site-release gates. It changes the official Jotform embed-handler decision from rejected to conditionally acceptable pending a separately authorized source, origin, privilege and Firefox/error-state review; the handler is not implemented.
Version 1.6, 2026-10-28: adds the locally tested Form A production-build gate. It requires `live`, the existing live approval, `production` environment role and a new independent Form A production approval; it permits an indexing-enabled build but does not derive authorization from indexing. It leaves normal/off/mock/isolated behavior unchanged, maps no Forms B/C or service drawers, and does not deploy or change Jotform.
Version 1.7, 2026-10-28: records the owner-approved two-physical-form direction. Form B is retired as a physical Jotform form; Form A gains a planned, unconfigured `consultation` context and Form C remains a separate future referral form. The seven current Form A placements and all gates remain unchanged. No Builder, route, iframe, account or deployment change occurred.