{ "version": "1.8.0", "slug": "ca-adde-allergen-menu-completeness-pack-engine", "title": "AllergenPack — CA ADDE Act (SB 68) Menu Allergen Completeness Pack Engine", "vertical": "Regulatory compliance", "seed": { "s": "ca-adde-allergen-menu-completeness-pack-engine", "t": "AllergenPack — CA ADDE Act (SB 68) Menu Allergen Completeness Pack Engine", "v": "Regulatory compliance", "r": "Medium-high", "m": "M" }, "product": { "slug": "ca-adde-allergen-menu-completeness-pack-engine", "project_name": "AllergenPack", "project_type": "AI-native done-for-you compliance documentation service", "vertical": "Regulatory compliance / foodservice", "audience": "Culinary, QA, and operations leaders at 20-120 unit US restaurant brands with at least one California location", "geography": "United States (California-triggered, national brand footprint)", "scale_expectation": "Boutique service business: 8 founding packs in first 90 days, 12-20 cumulative packs plus 5+ retainers by day 90, 50%+ blended gross margin by month 12", "core_workflows": [ "Gap Scan: free public-menu diagnostic that seeds the sales pipeline", "Completeness Pack production: intake -> extraction -> Big-9 mapping -> drafting -> Exception Queue -> Specialist Release -> QA -> delivery", "Quarterly Refresh Retainer: re-run the pipeline against supplier/menu changes to keep the Change Log current" ], "discovery": { "one_line_purpose": "On AllergenPack, culinary and ops leaders stop guessing at menu allergen gaps and start shipping released, evidence-backed Big-9 Matrices. Recipes and supplier specs are extracted at intake, Big-9 mapping runs against deterministic rules, and every Completeness Pack releases with a source-traced disclosure pack a specialist has signed.", "primary_users": [ "VP Operations, Director of Culinary, and QA/food-safety managers at 20-120 unit restaurant brands with a California door", "Culinary/allergen-ops specialist (release authority)", "Franchisee print/ops coordinator (read-only Channel Checklist consumer)" ], "jobs_to_be_done": [ "Produce the §114093.5 written Big-9 disclosure for every covered menu item without hiring an allergen-ops FTE", "Catch Unknown/HOLD items and hidden-ingredient patterns (sesame oil, soy glazes) before they become inspection gaps", "Hand an inspector, franchisee, or new hire a released, channel-mapped disclosure pack on demand" ], "value_prop": "AllergenPack turns a scattered, multi-channel menu allergen picture into a release-ready, human-released SB 68 Completeness Pack -- reconstructable on demand, defensible at inspection, with the client always the brand/PIC of record.", "competitors": [ "Menu-audit SaaS the culinary team never fully operates (MenuRegistry, MenuIQ, Foodini)", "Nutrition labs and consultants selling slow, expensive project work", "The shared drive folder where recipe cards and supplier specs currently go to die" ], "differentiation": "Done-for-you packs, not a dashboard: deterministic Big-9 rules (never a guessed call), specialist release on every pack, Written Alternative built in by default, and explicit HOLD registers instead of invented allergen data.", "positioning_statement": "For culinary and ops leaders at 20-120 unit restaurant brands who inherited a written Big-9 disclosure duty on July 1, 2026, AllergenPack is the done-for-you documentation service that turns every recipe and supplier spec into a release-ready, inspection-ready SB 68 Completeness Pack -- unlike menu-audit SaaS tools that expect the culinary team to operate software, or enterprise menu suites built for 100+ unit brands." }, "assumptions": [ { "id": "A1", "statement": "Buyers will pay $2,500-$12,000 per brand for a done-for-you pack rather than operate SaaS themselves", "confidence": "Medium", "impact_if_wrong": "Pricing must drop toward SaaS-comparable levels or bundle more retainer value", "revisit_trigger": "Founding-cohort close rate below 20% of qualified consults" }, { "id": "A2", "statement": "20-120 unit brands lack in-house allergen-ops headcount and enterprise menu platforms", "confidence": "Medium-High", "impact_if_wrong": "ICP should narrow to brands with confirmed platform gaps only", "revisit_trigger": "Two consecutive Gap Scan targets already running a full menu-management suite" }, { "id": "A3", "statement": "Recipe/supplier evidence is collectible within 5 business days of kickoff for a typical client", "confidence": "Medium", "impact_if_wrong": "SLA needs a buffer tier or an evidence-remediation fee", "revisit_trigger": "More than 25% of pilot packs miss the 10-business-day SLA on evidence grounds" }, { "id": "A4", "statement": "Quarterly Refresh Retainer attach rate reaches ~40% of delivered packs", "confidence": "Medium", "impact_if_wrong": "Recurring revenue plan slips; founder-led sales must carry more of year-1 revenue", "revisit_trigger": "Retainer attach below 20% after first 10 packs" } ], "unknowns": [ { "id": "U1", "question": "Exact count of 20+ unit brands with >=1 California door", "blocks": "TAM precision", "resolution_path": "Build a store-locator-derived list during outbound; treat published estimate as a range, not a fact" }, { "id": "U2", "question": "Whether other states' copycat allergen bills (MD, NJ, IL, OH, MO, NY, MI) pass and on what timeline", "blocks": "Multi-state expansion sequencing", "resolution_path": "Track state legislative sessions quarterly; the rule engine is modular per state" }, { "id": "U3", "question": "Actual E&O insurance cost/availability for a menu-allergen documentation service", "blocks": "Compliance-checklist finalization, first paid engagement", "resolution_path": "Shop specialty policies before accepting client #1" } ], "expert_panel": [ { "role": "Culinary/allergen-ops specialist", "key_concern": "Evidence completeness before any release; hidden-ingredient patterns (sesame oil, soy glazes) are the real risk, not the headline items", "recommendation": "Keep the Exception Queue mandatory and never let a confidence score substitute for a source span", "dissent": "None -- structural control, not a judgment call" }, { "role": "Franchise operations counsel", "key_concern": "Franchisee non-deployment after a released pack still leaves the franchisor exposed", "recommendation": "Bundle the Franchisee Print Kit add-on into any franchisor-level engagement, and track 30-day deployment confirmation as a KPI", "dissent": "None" }, { "role": "Food-safety QA director", "key_concern": "A completeness pack that certifies nothing but reads like a certification will be misused by sales/marketing", "recommendation": "Enforce the forbidden-claim scrub on every pack and disclosure surface, including the landing page", "dissent": "None" } ], "strategy": { "business_model": "Outcome-priced DFY documentation service; one-time Completeness Pack plus recurring Quarterly Refresh Retainer and channel/franchisee add-ons", "revenue_streams": [ "Brand Completeness Pack", "Quarterly Refresh Retainer", "Delivery-Channel Sync add-on", "Franchisee Print Kit add-on", "Free Gap Scan (lead magnet, non-revenue)" ], "moat": [ "[PLACEHOLDER] owner to complete" ], "gtm": [ "[PLACEHOLDER] owner to complete" ], "pricing_hypothesis": "Founding pack $1,990-$4,900 anchors below a rushed reprint or a failed-inspection cycle; standard pack $2,500-$12,000 stays economically comparable to a few months of SaaS spend while removing operator burden", "kill_criteria": [ "[PLACEHOLDER] owner to complete" ] }, "security": { "stride": [ { "threat": "Spoofing", "scenario": "Attacker attempts to impersonate a reviewer to sign off on a fabricated artifact.", "mitigation": "SSO with MFA; reviewer signatures bound to a cryptographic session claim, not a form field." }, { "threat": "Tampering", "scenario": "Historical evidence entries edited after the fact to hide a bad claim.", "mitigation": "Append-only audit log; hash-chained artifact snapshots; diff view on every reviewer surface." }, { "threat": "Repudiation", "scenario": "Reviewer denies signing off on a delivered artifact.", "mitigation": "Signed attestations with server-side timestamp + reviewer identity; export bundle includes signature manifest." }, { "threat": "Information Disclosure", "scenario": "Cross-tenant leak of Regulated-record, PII, Internal-audit data through shared indices, logs, or prompts.", "mitigation": "Tenant-scoped row-level auth; PII scrubbing in logs; retrieval indices partitioned per tenant." }, { "threat": "Denial of Service", "scenario": "Runaway AI job or export exhausts shared workers.", "mitigation": "Per-tenant concurrency + budget caps; circuit breaker on model calls; degrade-gracefully queue." }, { "threat": "Elevation of Privilege", "scenario": "Standard user acquires reviewer or admin capability via a workflow shortcut.", "mitigation": "Roles stored in a separate table; capability checks server-side; no client-only role checks." } ], "privacy_posture": "Data-minimization by default; per-tenant isolation; DPA + BAA templates on file; DSAR runbook published.", "compliance_targets": [ "SB 68 / HSC §114093.5 disclosure duty", "HSC §113820.5 Big-9 definition", "CRFC recordkeeping norms" ], "data_classifications": [ "Client recipes (confidential)", "Supplier specs (confidential)", "Released packs (client-owned, retained per compliance-checklist.md)" ] }, "devops": { "ci_cd": "PR → typecheck + unit + snapshot tests → preview deploy → main auto-deploys to a single production region; migrations gated on review.", "environments": [ "local", "preview (per-PR)", "staging (shared)", "production (single region + multi-AZ)" ], "observability": [ "Structured logs with tenant + request IDs", "RED metrics per workflow", "Error tracking with source maps", "Model-call spans with cost + latency", "Weekly SLO review" ], "testing_pyramid": [ "Unit tests on derivation + validation modules", "Component tests on reviewer surfaces", "Contract tests on integrations", "End-to-end smoke test on the intake→specialist release→delivery path" ], "accessibility_tests": [ "axe-core in CI on reviewer surfaces", "Keyboard-only walkthrough per workflow", "Prefers-reduced-motion honored" ], "performance_budget": "p95 workflow latency published per module; artifact-generation cold-path under 30s or shown as background job." }, "accessibility_i18n_ethics": { "wcag_target": "AA", "locales": [ "en-US" ], "rtl_support": false, "ethical_risks": [ "Pack released without human review", "Cross-regime rule leakage (§608 ODS vs §114093.5 HFC)", "Regulator-facing errors attributed to AI" ], "ethical_guardrails": [ "Human reviewer required before regulator submission", "Per-regime prompt + template isolation (§608 ODS vs §114093.5 HFC)", "AI-usage disclosure in pack metadata where required" ] }, "governance": { "ownership": [ { "area": "Product + roadmap", "owner": "Executive Sponsor" }, { "area": "Architecture + platform", "owner": "Engineering Lead" }, { "area": "Evidence + reviewer workflow", "owner": "Named licensed reviewer" }, { "area": "Compliance + privacy", "owner": "Compliance Lead" }, { "area": "Design system", "owner": "Design Lead" }, { "area": "SEO + content", "owner": "Content Lead" } ], "docs_required": [ "ADR log (checked in)", "Owner-action ledger", "Evidence register", "STRIDE threat model", "Runbook: incident, restore, breach notification", "Reviewer playbook + signature policy" ], "naming_conventions": [ "kebab-case slugs for blueprints and routes", "camelCase for TypeScript identifiers", "SCREAMING_SNAKE_CASE for environment variables", "Verb-first action names (e.g., generate-blueprint-docs)" ], "change_control": "ADR-per-major-decision; migrations require review; production deploys gated on green CI + owner-action ledger check." }, "risk_register": [ { "id": "R1", "risk": "Allergen miss reaches a guest, tied to a released pack", "likelihood": "Medium", "impact": "High", "mitigation": "Evidence-only mapping, mandatory HOLD on Unknown, no allergen-free claims, E&O insurance, client verification step", "contingency": "Immediate specialist escalation + incident-response referral per compliance-checklist.md", "owner": "Culinary/allergen-ops specialist" }, { "id": "R2", "risk": "Client withholds supplier specs, blocking release", "likelihood": "High", "impact": "Medium", "mitigation": "Intake completeness gate; partial pack ships with explicit HOLD list rather than a guess", "contingency": "Two-touch chase over 5 business days, then HOLD ships with buyer-action note", "owner": "Intake operator" }, { "id": "R3", "risk": "SaaS competitors undercut on price", "likelihood": "Medium", "impact": "Medium", "mitigation": "Sell labor removal and full pack assembly, not audit access alone", "contingency": "Emphasize DFY differentiation and Written Alternative default in sales copy", "owner": "Founder" }, { "id": "R4", "risk": "Franchisee non-deployment after pack delivery", "likelihood": "Medium", "impact": "Medium", "mitigation": "Deployment checklist, 30-day confirmation check, Franchisee Print Kit add-on", "contingency": "Escalate to release approver with Channel Checklist as the deployment guide", "owner": "Delivery lead" } ], "roadmap": [ { "phase": "Weeks 1-8: Pilot cohort", "weeks": "1-8", "outcomes": [ "Offer page + Gap Scan live", "3 paid founding packs released", "Gold-standard pack library seeded" ], "exit_criteria": [ "[PLACEHOLDER] owner to complete" ], "kill_criteria": [ "[PLACEHOLDER] owner to complete" ] }, { "phase": "Weeks 9-13: Harden ops", "weeks": "9-13", "outcomes": [ "Intake evidence requirements hardened after 5 pilots", "SOPs/exception-queue checklist hardened after 10 pilots", "12-20 cumulative packs, 5+ retainers" ], "exit_criteria": "90-day gate met per launch-plan.md", "kill_criteria": "Rework rate above 15% sustained past pilot 10" }, { "phase": "Month 4-12: Scale within CA", "weeks": "14-52", "outcomes": [ "50%+ blended gross margin by month 12", "Referral-partner channel contributing consults", "Automation share of specialist minutes at 75%" ], "exit_criteria": "Financial-model.csv targets met within 20%", "kill_criteria": "Automation share stalls below 50% by month 9" } ], "metrics": { "north_star": "Released Completeness Packs deployment-confirmed within 30 days", "leading": [ "Gap Scans/week", "scan-to-consult conversion", "consult-to-paid conversion", "Exception Queue / Unknown rate" ], "lagging": [ "Cumulative packs delivered", "retainer attach rate", "gross margin", "rework rate" ], "guardrails": [ "No pack releases with a blank Big-9 cell", "No release without a named specialist signature", "No digital-channel pack ships without a Written Alternative" ] }, "executive_review": { "consensus": "Go. SB 68 is live, the buyer cohort is well-defined, and the DFY gap versus SaaS competitors is real and evidence-backed.", "dissent": "None recorded; the franchise-operations concern about non-deployment was resolved by adding the Franchisee Print Kit and 30-day deployment KPI.", "go_no_go": "Go", "top_3_risks": [ "Allergen miss on a released pack", "Client evidence incompleteness blocking SLA", "SaaS price competition on the audit layer alone" ], "first_10_steps": [ "Publish offer page and Gap Scan form", "Send 25 outbound diagnoses", "Run 3 Gap Scans", "Kick off pack #1 intake", "Release pack #1", "Confirm pack #1 deployment", "Sign 1 referral partner", "Publish first 3 educational posts", "Schedule the Gap Scan Clinic webinar", "Log pilot-1 findings toward the 5-pilot checkpoint" ] } }, "project_site": { "slug": "ca-adde-allergen-menu-completeness-pack-engine", "app_name": "AllergenPack Release Desk", "archetype": "filing-dossier", "archetype_label": "completeness-pack release desk", "reader_role": "Director of Culinary Operations", "one_sentence_app": "AllergenPack Release Desk is a completeness-pack release desk for culinary/ops leaders who need every menu item tied to a §114093.5-complete Big-9 disclosure before a health inspector, franchisee, or delivery-app audit asks for it.", "homepage_sequence": [ "scene", "workflow", "instrument", "offer", "proof", "qualification", "objections" ], "hero": { "frame_label": "Foodservice compliance · completeness-pack release desk", "eyebrow": "Director of Culinary Operations / recipe change or SB 68 enforcement trigger", "interface_title": "AllergenPack release desk", "primary_panel_title": "House Teriyaki Glaze · sesame + soy flagged · Unknown on 1 sub-ingredient", "primary_panel_body": "Open pack run: extract the recipe and supplier-spec fields, verify the Big-9 evidence, run the deterministic mapping rules, then stage the Completeness Pack for specialist release.", "side_panel_title": "Before this ships", "side_panel_items": [ "Source span on every Yes/No call", "Written Alternative artifact attached", "Channel Checklist staged" ], "status_metric": "REVIEW", "status_label": "release gate active" }, "language": { "problem_heading": "The Director of Culinary Operations moment", "mechanism_heading": "Inside the AllergenPack Release Desk", "proof_heading": "Why this survives an inspection", "offer_heading": "What leaves the room", "objection_heading": "The hard questions", "qualification_heading": "Who should not use this", "cta_close": "Open a pack run from your current recipes and supplier specs -- released by a real culinary/allergen-ops specialist, never auto-released on an Unknown." }, "modules": [ { "name": "Recipe & spec intake", "job": "Turns forwarded recipes, supplier specs, and menus into a named pack run with an item match, extracted ingredients, and a missing-evidence list.", "artifact": "intake triage record" }, { "name": "Big-9 Matrix registry", "job": "Holds every menu item's Yes/No/Unknown call across all nine allergens, with the source span behind each.", "artifact": "Big-9 Matrix" }, { "name": "Completeness Pack", "job": "Packages the Matrix, disclosure copy, Written Alternative, Channel Checklist, and Source-Trace Appendix into the record an inspector can walk without a meeting.", "artifact": "release package" } ], "checkpoints": [ { "label": "Big-9 required field", "pass": "extracted with source span", "fail": "chased or shipped as explicit HOLD" }, { "label": "Big-9 mapping call", "pass": "deterministic rule, evidence-backed", "fail": "blocked before release" }, { "label": "Completeness Pack", "pass": "specialist releases", "fail": "stays draft" } ], "signature_scene": "You're a Director of Culinary Operations. A supplier just changed the house teriyaki glaze recipe. Someone needs to know -- today -- whether that introduces sesame or soy that isn't on the current disclosure, and the only evidence is a spec sheet nobody has read line by line. This page is built like the release desk that person needed before the next reprint." }, "ddd": { "slug": "ca-adde-allergen-menu-completeness-pack-engine", "project_name": "AllergenPack", "business_understanding": { "summary": "AllergenPack is a done-for-you production service that turns a restaurant brand's recipes, supplier specs, and menus into a released, inspection-ready Menu Allergen Completeness Pack under California's ADDE Act (SB 68 / HSC §114093.5).", "customer_profile": "Culinary, QA, and operations leaders at 20-120 unit US restaurant brands with at least one California location and no enterprise menu-management platform live for allergens.", "customer_pain": "Written per-item Big-9 disclosure across every channel (menu, kiosk, app, web, delivery listings) is now a statutory duty, but evidence lives in scattered recipe cards and supplier specs, and hidden ingredients (sesame oil, soy glazes) routinely slip through informal review.", "paid_outcome": "A released Menu Allergen Completeness Pack -- Big-9 Matrix, disclosure copy, Written Alternative, Channel Checklist, Source-Trace Appendix, Change Log -- the client deploys themselves.", "value_creation": "AI collapses recipe/spec extraction from days to minutes; deterministic Big-9 rules stop guessed calls; a named specialist owns release accountability; the hidden-ingredient pattern library compounds with every corrected pack.", "why_ai_native": "Cross-document synthesis (recipes, specs, menus, channel inventories) at the scale of dozens of SKUs per brand is exactly where frontier-model extraction plus deterministic rule-checking outperforms manual spreadsheet work, while judgment stays concentrated at the specialist-release chokepoint.", "operational_risks": [ "Allergen miss reaching a guest", "Client evidence incompleteness", "Franchisee non-deployment after release", "Delivery-app channel drift" ], "assumptions": [ "Buyers will pay a DFY premium over SaaS audit tools", "Recipe/supplier evidence is collectible within the SLA window for most clients" ], "validation_questions": [ "Does the founding cohort convert at the assumed 35% consult-to-paid rate?", "Does the 40% pack-to-retainer attach rate hold past pilot 10?" ] }, "domain_discovery": { "actors": [ { "actor": "Culinary/Ops leader", "role": "Economic buyer and release approver", "goals": [ "Ship a compliant, deployable disclosure pack", "Avoid inspection and guest-safety gaps" ], "decisions": [ "Approve intake evidence completeness", "Approve final pack for deployment" ], "pain_points": [ "No allergen-ops headcount", "Channel sprawl across boards/app/web/delivery" ] }, { "actor": "Culinary/allergen-ops specialist", "role": "Release authority", "goals": [ "Resolve every Exception Queue item with evidence or a clear HOLD" ], "decisions": [ "Release, resolve, or HOLD each flagged item" ], "pain_points": [ "Weak or conflicting supplier evidence" ] }, { "actor": "Franchisee ops coordinator", "role": "Deployment consumer", "goals": [ "Print and post correct, current disclosure materials" ], "decisions": [ "Which Channel Checklist items apply at their door" ], "pain_points": [ "Master Matrix drift across print runs" ] }, { "actor": "AI extraction/mapping agent", "role": "Draft producer", "goals": [ "Extract ingredients with source spans", "Draft Big-9 calls only where evidence supports them" ], "decisions": [ "Route to Exception Queue vs. auto-populate" ], "pain_points": [ "Ambiguous or missing supplier documentation" ] } ], "glossary": [ { "term": "Completeness Pack", "definition": "The released bundle of six artifacts delivered to a client for one brand menu family.", "used_by": "All contexts", "context": "QA & Delivery", "example": "The Q3 Completeness Pack for a 60-unit fast-casual brand.", "notes": "Never called a 'report' or 'bundle' -- one term everywhere." }, { "term": "Gap Scan", "definition": "The free diagnostic run against a public menu before any paid engagement.", "used_by": "Sales, Intake", "context": "Marketing/Intake", "example": "A prospect submits a menu URL and receives an itemized Gap Scan PDF.", "notes": "Not a Completeness Pack -- diagnosis only." }, { "term": "Big-9 Matrix", "definition": "The item-level Yes/No/Unknown table across all nine major allergens.", "used_by": "Mapping & Rules, QA", "context": "Core deliverable", "example": "Matrix row for 'House Teriyaki Glaze' shows Soy: Yes, Sesame: Yes, Wheat: Unknown.", "notes": "Sesame always its own column." }, { "term": "Written Alternative", "definition": "The non-digital chart/booklet required whenever any channel is digital.", "used_by": "Drafting, QA", "context": "Statutory requirement", "example": "A laminated allergen booklet kept at the host stand.", "notes": "Required, not optional, on any digital channel." }, { "term": "Exception Queue", "definition": "The routing state for any item with an Unknown call, low-confidence evidence, or a hidden-ingredient pattern alert.", "used_by": "Mapping & Rules, Release", "context": "Human chokepoint", "example": "A sauce with no supplier spec on file sits in the Exception Queue.", "notes": "Cannot self-clear; only a specialist can release it." }, { "term": "HOLD", "definition": "The status for an item that ships without a resolved Big-9 call, with the specific buyer action needed to clear it.", "used_by": "Release, Delivery", "context": "No-Holes Quality Engine", "example": "Item ships HOLD pending the supplier's ingredient spec for a new sauce.", "notes": "Never a silently guessed 'No'." }, { "term": "Specialist Release", "definition": "The signed act of a named culinary/allergen-ops specialist clearing a pack to ship.", "used_by": "Release", "context": "Accountability chokepoint", "example": "The specialist signs the release record for pack #4.", "notes": "Cannot be automated away." }, { "term": "Refresh Retainer", "definition": "The recurring quarterly engagement that re-runs the pipeline against supplier/menu changes.", "used_by": "Portfolio & Refresh", "context": "Recurring revenue", "example": "A brand's Refresh Retainer catches a new LTO sauce with undisclosed tree nuts.", "notes": "Same pipeline as the initial pack, scoped to deltas." } ], "decisions": [ { "decision": "Route item to Exception Queue vs. auto-populate Matrix", "who": "Mapping & Rules deterministic rule", "inputs": [ "Ingredient source span", "Confidence band", "Pattern-library alert" ], "rule": "Any Unknown, low-confidence, or unresolved pattern alert routes to Exception Queue; nothing auto-releases", "output": "Draft Matrix cell or Exception Queue entry", "risk": "False confidence from a plausible-sounding but unsupported extraction" }, { "decision": "Release vs. HOLD an Exception Queue item", "who": "Culinary/allergen-ops specialist", "inputs": [ "Available evidence", "Buyer follow-up status" ], "rule": "Release only with a source-backed call; otherwise HOLD with a named buyer action", "output": "PackReleased or ItemMarkedHold", "risk": "Premature release under sales pressure" }, { "decision": "Whether a channel requires a Written Alternative", "who": "Deterministic rule", "inputs": [ "Channel Checklist digital flag" ], "rule": "Any digital=true channel requires a completed Written Alternative before release", "output": "Release blocked or unblocked", "risk": "Missed channel in the client-supplied inventory" }, { "decision": "Whether to escalate to counsel or a dietitian", "who": "Any operator", "inputs": [ "Client request type" ], "rule": "Legal-conclusion or clinical-claim requests are referred out, never answered internally", "output": "Referral memo", "risk": "Unauthorized practice if internalized" } ], "events": [ { "event": "IntakeCompletenessGatePassed", "meaning": "Evidence Checklist is sufficient to start the SLA clock", "trigger": "All standard items have a source and all channels have a current artifact", "downstream": [ "[PLACEHOLDER] owner to complete" ] }, { "event": "MatrixDraftReady", "meaning": "AI has produced a full draft Big-9 Matrix", "trigger": "Extraction and mapping complete for all items", "downstream": "Exception Queue population" }, { "event": "ItemMarkedHold", "meaning": "An item ships without a resolved call", "trigger": "Specialist cannot resolve within SLA", "downstream": "HOLD list included in delivered pack" }, { "event": "PackReleased", "meaning": "Specialist has signed the release record", "trigger": "All Exception Queue items resolved or HOLD-marked", "downstream": "QA sample and forbidden-claim scrub" }, { "event": "PackDelivered", "meaning": "Client has received the full pack bundle", "trigger": "QA passes", "downstream": "30-day deployment check scheduled" }, { "event": "DeploymentConfirmed", "meaning": "Client confirms the pack is live across its channels", "trigger": "30-day check response", "downstream": "Retainer pitch eligibility" } ] }, "subdomains": [ { "name": "Evidence Intake", "type": "supporting", "description": "Collects and gates recipes, supplier specs, menus, and channel inventories.", "reason": "Every downstream call depends on evidence quality captured here.", "business_value": "Prevents guessed disclosure calls at the source.", "recommendation": "Keep the completeness gate strict even under sales pressure.", "ai_involvement": "AI checklists flag likely-missing evidence types.", "human_involvement": "Operator confirms completeness and logs gaps.", "risks": [ "Client stalls on evidence delivery" ], "validation_questions": [ "Is 5 business days a realistic evidence-collection window across most clients?" ] }, { "name": "Menu Allergen Completeness Pack Production", "type": "core", "description": "Extracts, maps, drafts, and releases the Big-9 Matrix and companion artifacts.", "reason": "This is the paid outcome and the primary moat.", "business_value": "Direct revenue driver; every other subdomain supports this one.", "recommendation": "Protect the specialist-release chokepoint from automation pressure.", "ai_involvement": "Extraction, mapping drafts, disclosure copy drafting.", "human_involvement": "Specialist release, QA sample review.", "risks": [ "Allergen miss on a released pack" ], "validation_questions": [ "Does the Exception Queue rate fall as the pattern library matures?" ] }, { "name": "Channel Deployment Tracking", "type": "supporting", "description": "Tracks which of a brand's channels (boards, kiosk, app, web, delivery listings) reflect the released Matrix.", "reason": "A correct Matrix that never reaches a channel is a compliance gap in practice.", "business_value": "Drives Delivery-Channel Sync add-on revenue and deployment-confirmation KPI.", "recommendation": "Make deployment confirmation, not pack delivery, the completion metric.", "ai_involvement": "Drift detection between released Matrix and live channel content (roadmap).", "human_involvement": "30-day deployment check call.", "risks": [ "Franchisee non-deployment" ], "validation_questions": [ "What fraction of packs reach full deployment within 30 days?" ] }, { "name": "Refresh & Retainer Management", "type": "supporting", "description": "Re-runs the pipeline on a quarterly cadence against supplier and menu changes.", "reason": "Converts a one-time pack into a recurring relationship.", "business_value": "Primary recurring-revenue line.", "recommendation": "Pitch retainers at the 30-day deployment check, not at kickoff.", "ai_involvement": "Change-detection against the prior Matrix.", "human_involvement": "Specialist re-release on material changes.", "risks": [ "Retainer churn if refresh doesn't surface real value" ], "validation_questions": [ "Does churn stay under the modeled 5%/month?" ] }, { "name": "Compliance & Licensing Boundary", "type": "generic", "description": "Maintains the disclaimer language, engagement-letter outline, and referral rules that keep AllergenPack inside its documentation-assembly scope.", "reason": "Regulatory and licensing risk is the top operational risk category.", "business_value": "Protects the business from unauthorized-practice and liability exposure.", "recommendation": "Have counsel review before the first paid engagement, not after.", "ai_involvement": "Forbidden-claim scrub on every disclosure surface.", "human_involvement": "Specialist and, on escalation, external counsel/dietitian.", "risks": [ "Treated as legal or medical advice" ], "validation_questions": [ "Is the referral trigger clear enough that operators use it consistently?" ] }, { "name": "Sales & Diagnostic Funnel", "type": "generic", "description": "Runs the free Gap Scan and converts it to consults and paid packs.", "reason": "Top-of-funnel motion that de-risks the sales cycle with a free diagnostic.", "business_value": "Drives pipeline at a controlled CAC.", "recommendation": "Keep the Gap Scan honest -- it should sometimes show a brand is not covered.", "ai_involvement": "Automated gap detection from a public menu.", "human_involvement": "Founder-led consult calls at launch.", "risks": [ "Gap Scan inflates gaps to force urgency" ], "validation_questions": [ "Does the Gap Scan's gap count match what the paid pack actually finds?" ] }, { "name": "Portfolio Reporting", "type": "generic", "description": "Read-side views of a multi-brand or multi-quarter client's pack history.", "reason": "Supports franchisors managing several concepts.", "business_value": "Upsell surface for multi-brand accounts.", "recommendation": "Defer building a real dashboard until volume justifies it (build-before-scale gate).", "ai_involvement": "None at launch.", "human_involvement": "Manual spreadsheet reporting at launch.", "risks": [ "Building this too early diverts specialist time from production" ], "validation_questions": [ "Do any founding clients actually operate 2+ brands through AllergenPack?" ] }, { "name": "Payments & Invoicing", "type": "generic", "description": "Stripe-based invoicing for packs, retainers, and add-ons.", "reason": "Necessary commercial plumbing, not a differentiator.", "business_value": "Enables outcome-based billing without hourly tracking.", "recommendation": "Off-the-shelf Stripe; no custom billing engine at this scale.", "ai_involvement": "None.", "human_involvement": "Founder issues and reconciles invoices at launch.", "risks": [ "Low -- standard tooling" ], "validation_questions": [] } ], "core_domain_analysis": { "primary_core": "Menu Allergen Completeness Pack Production", "secondary_cores": [ "Evidence Intake", "Channel Deployment Tracking" ], "supporting_may_become_core": [ "Refresh & Retainer Management -- if recurring revenue outgrows one-time packs" ], "generic_do_not_distract": [ "Payments & Invoicing", "Portfolio Reporting" ], "rationale": "The paid outcome is a released, evidence-backed Big-9 disclosure pack; every dollar of differentiation lives in evidence discipline and the specialist-release chokepoint, not in software features generic to any DFY service business." }, "bounded_contexts": [ { "name": "Intake", "purpose": "Collect and gate recipes, supplier specs, menus, and channel inventory before the SLA clock starts.", "subdomain": "Evidence Intake", "type": "supporting", "owned_language": [ "Evidence Checklist", "EvidenceItem", "completeness gate" ], "owns": [ "Evidence Checklist lifecycle", "intake completeness scoring" ], "does_not_own": [ "Big-9 mapping calls", "release authority" ], "primary_actors": [ "Culinary/ops leader", "Intake operator" ], "entities": [ "EvidenceChecklist", "EvidenceItem" ], "value_objects": [ "ItemId", "ChannelInventoryEntry" ], "aggregates": [ "EvidenceChecklistAggregate" ], "domain_services": [ "CompletenessGateEvaluator" ], "application_services": [ "StartIntake", "LogEvidenceGap", "ConfirmChannelInventory" ], "commands": [ "StartIntake", "ReceiveEvidenceItem", "LogGap" ], "domain_events": [ "IntakeStarted", "EvidenceItemReceived", "IntakeCompletenessGatePassed", "IntakeGapLogged" ], "policies": [ "SLA clock starts only after the completeness gate passes" ], "specifications": [ "Every standard item has >=1 recipe/spec source", "Every declared channel has a current menu artifact" ], "invariants": [ "No item enters Extraction without at least a logged-gap or a source" ], "ai_agents": [ "Intake completeness assistant" ], "human_roles": [ "Intake operator" ], "data_owned": [ "Evidence Checklist records" ], "inputs": [ "Client-supplied documents" ], "outputs": [ "Gated Evidence Checklist" ], "external_integrations": [ "Client Drive/Dropbox folder" ], "risks": [ "Client stalls on evidence" ], "interfaces": [ "Kickoff email", "Evidence Checklist form" ] }, { "name": "Extraction", "purpose": "Normalize recipes, specs, and menus into a structured ingredient list with source spans.", "subdomain": "Menu Allergen Completeness Pack Production", "type": "core", "owned_language": [ "NormalizedMenu", "MenuItem", "Ingredient", "source_span" ], "owns": [ "Ingredient extraction", "synonym normalization" ], "does_not_own": [ "Big-9 calls", "release" ], "primary_actors": [ "AI extraction agent" ], "entities": [ "MenuItem", "Ingredient" ], "value_objects": [ "IngredientName", "ItemId" ], "aggregates": [ "NormalizedMenuAggregate" ], "domain_services": [ "IngredientExtractor" ], "application_services": [ "ExtractDocument" ], "commands": [ "ExtractIngredients" ], "domain_events": [ "IngredientsExtracted", "SourceSpanMissing" ], "policies": [ "Never infer an ingredient without a source_span" ], "specifications": [ "Every ingredient has a source_span or a needs_spec flag" ], "invariants": [ "No ingredient with world-knowledge-only provenance enters the Matrix" ], "ai_agents": [ "Extraction agent (Layer 2)" ], "human_roles": [], "data_owned": [ "Normalized ingredient lists" ], "inputs": [ "Recipe/spec/menu documents" ], "outputs": [ "Structured ingredient list" ], "external_integrations": [], "risks": [ "Hallucinated ingredient content" ], "interfaces": [ "Extraction prompt contract" ] }, { "name": "Mapping & Rules", "purpose": "Map extracted ingredients to Big-9 Yes/No/Unknown calls via deterministic rules.", "subdomain": "Menu Allergen Completeness Pack Production", "type": "core", "owned_language": [ "Big-9 Matrix", "confidence band", "hidden-ingredient pattern" ], "owns": [ "Matrix draft state", "pattern-library retrieval" ], "does_not_own": [ "Release signature" ], "primary_actors": [ "AI mapping agent" ], "entities": [ "MatrixCell" ], "value_objects": [ "ConfidenceBand" ], "aggregates": [ "BigNineMatrixAggregate" ], "domain_services": [ "MapIngredientsToBigNine", "PatternLibraryLookup" ], "application_services": [ "DraftMatrix" ], "commands": [ "MapItemToBigNine" ], "domain_events": [ "MatrixDraftReady", "PatternAlertRaised" ], "policies": [ "No blank cells", "Sesame always its own column", "Absence of evidence is Unknown, never No" ], "specifications": [ "Every item has 9 populated calls" ], "invariants": [ "A Yes/No call always cites >=1 source_span" ], "ai_agents": [ "Mapping agent (Layer 4)" ], "human_roles": [], "data_owned": [ "Big-9 Matrix drafts", "hidden-ingredient pattern library" ], "inputs": [ "Structured ingredient list" ], "outputs": [ "Draft Matrix" ], "external_integrations": [], "risks": [ "Pattern-library false negative on a novel sauce" ], "interfaces": [ "Mapping prompt contract" ] }, { "name": "Release", "purpose": "Route Exception Queue items to specialist judgment and record the signed release.", "subdomain": "Menu Allergen Completeness Pack Production", "type": "core", "owned_language": [ "Exception Queue", "HOLD", "Specialist Release", "release record" ], "owns": [ "Exception Queue routing", "release signature" ], "does_not_own": [ "Extraction", "QA sampling" ], "primary_actors": [ "Culinary/allergen-ops specialist" ], "entities": [ "ExceptionQueueItem", "PackRelease" ], "value_objects": [ "ReleaseDecision" ], "aggregates": [ "PackReleaseAggregate" ], "domain_services": [ "ExceptionRouter" ], "application_services": [ "ResolveExceptionItem", "MarkHold", "SignRelease" ], "commands": [ "ResolveExceptionItem", "MarkHold", "SignRelease" ], "domain_events": [ "ExceptionResolved", "ItemMarkedHold", "PackReleased" ], "policies": [ "PackReleased cannot fire while any Exception item is unresolved and not HOLD-marked" ], "specifications": [ "Every release has a named signer" ], "invariants": [ "No auto-release under any confidence threshold" ], "ai_agents": [], "human_roles": [ "Culinary/allergen-ops specialist" ], "data_owned": [ "Release records" ], "inputs": [ "Draft Matrix", "Exception Queue" ], "outputs": [ "Released pack" ], "external_integrations": [ "E-signature (release acknowledgment)" ], "risks": [ "Premature release under deadline pressure" ], "interfaces": [ "Release signature form" ] }, { "name": "QA & Delivery", "purpose": "Sample-check released packs, scrub forbidden claims, and deliver the bundle.", "subdomain": "Menu Allergen Completeness Pack Production", "type": "core", "owned_language": [ "QA sample", "forbidden-claim scrub", "deployment walkthrough" ], "owns": [ "QA sampling", "delivery bundling" ], "does_not_own": [ "Release signature" ], "primary_actors": [ "QA operator" ], "entities": [ "QASample" ], "value_objects": [ "ClaimScrubResult" ], "aggregates": [ "DeliveryAggregate" ], "domain_services": [ "ForbiddenClaimScrub" ], "application_services": [ "RunQASample", "DeliverPack" ], "commands": [ "RunQASample", "DeliverPack" ], "domain_events": [ "QASamplePassed", "PackDelivered", "DeploymentCheckDue" ], "policies": [ "5-item minimum QA sample per pack" ], "specifications": [ "No forbidden phrase ships unscrubbed" ], "invariants": [ "PackDelivered only after QASamplePassed" ], "ai_agents": [ "Claim-scrub agent" ], "human_roles": [ "QA operator" ], "data_owned": [ "Delivered pack bundles" ], "inputs": [ "Released pack" ], "outputs": [ "Delivered pack + walkthrough" ], "external_integrations": [ "Client email/calendar for walkthrough" ], "risks": [ "Sample misses a systematic extraction error" ], "interfaces": [ "Delivery email template" ] }, { "name": "Portfolio & Refresh", "purpose": "Track deployment confirmation and run Quarterly Refresh Retainers against menu/supplier changes.", "subdomain": "Refresh & Retainer Management", "type": "supporting", "owned_language": [ "Refresh Retainer", "Change Log", "deployment confirmation" ], "owns": [ "Change Log", "retainer scheduling" ], "does_not_own": [ "Initial pack production" ], "primary_actors": [ "Culinary/ops leader" ], "entities": [ "ChangeLogEntry" ], "value_objects": [ "RefreshCycleWindow" ], "aggregates": [ "RefreshRetainerAggregate" ], "domain_services": [ "ChangeDetector" ], "application_services": [ "ScheduleRefresh", "ConfirmDeployment" ], "commands": [ "ConfirmDeployment", "ScheduleRefresh" ], "domain_events": [ "DeploymentConfirmed", "RefreshScheduled" ], "policies": [ "30-day deployment check on every delivered pack" ], "specifications": [], "invariants": [], "ai_agents": [], "human_roles": [ "Founder / account lead" ], "data_owned": [ "Change Log", "retainer schedule" ], "inputs": [ "Delivered pack", "supplier change notices" ], "outputs": [ "Refresh pack" ], "external_integrations": [ "CRM" ], "risks": [ "Retainer churn" ], "interfaces": [ "30-day check email" ] } ], "context_map": [ { "upstream": "Intake", "downstream": "Extraction", "pattern": "Customer/Supplier", "business_reason": "Extraction cannot start without a completeness-gated Evidence Checklist", "data_exchanged": [ "[PLACEHOLDER] owner to complete" ], "events_exchanged": [ "[PLACEHOLDER] owner to complete" ], "contract_type": "Internal event", "failure_risks": [ "[PLACEHOLDER] owner to complete" ], "acl_notes": "None needed -- same team", "ownership_boundary": "Intake owns the gate; Extraction trusts it" }, { "upstream": "Extraction", "downstream": "Mapping & Rules", "pattern": "Customer/Supplier", "business_reason": "Mapping needs normalized ingredients with source spans", "data_exchanged": "Structured ingredient list", "events_exchanged": "IngredientsExtracted", "contract_type": "Internal event", "failure_risks": "Missing source_span silently defaults to a guess", "acl_notes": "Mapping rejects any ingredient without source_span or needs_spec flag", "ownership_boundary": "Extraction owns ingredient data; Mapping owns Big-9 calls" }, { "upstream": "Mapping & Rules", "downstream": "Release", "pattern": "Customer/Supplier", "business_reason": "Release needs a complete Draft Matrix and populated Exception Queue", "data_exchanged": "Draft Matrix, Exception Queue", "events_exchanged": "MatrixDraftReady", "contract_type": "Internal event", "failure_risks": "Exception Queue under-populated, allowing a silent bad call through", "acl_notes": "Release re-validates no-blank-cell invariant independently", "ownership_boundary": "Mapping owns the Matrix draft; Release owns the signed outcome" }, { "upstream": "Release", "downstream": "QA & Delivery", "pattern": "Customer/Supplier", "business_reason": "QA cannot sample or deliver an unreleased pack", "data_exchanged": "Released pack", "events_exchanged": "PackReleased", "contract_type": "Internal event", "failure_risks": "QA runs on a pre-release draft by mistake", "acl_notes": "QA checks for a valid release signature before sampling", "ownership_boundary": "Release owns the signature; QA owns delivery readiness" }, { "upstream": "QA & Delivery", "downstream": "Portfolio & Refresh", "pattern": "Customer/Supplier", "business_reason": "Refresh scheduling and deployment tracking start only after delivery", "data_exchanged": "Delivered pack, delivery date", "events_exchanged": "PackDelivered", "contract_type": "Internal event", "failure_risks": "Deployment check scheduled against the wrong delivery date", "acl_notes": "None needed", "ownership_boundary": "QA & Delivery owns the bundle; Portfolio & Refresh owns the ongoing relationship" } ], "external_integrations": [ { "system": "Client Drive/Dropbox folder", "risk": "Client revokes or misconfigures access mid-pack", "internal_model": "EvidenceChecklist", "acl_strategy": "Read-only access requested at kickoff; local mirror kept in AllergenPack's own storage", "owner_context": "Intake", "data_in": [ "[PLACEHOLDER] owner to complete" ], "data_out": [ "[PLACEHOLDER] owner to complete" ], "trigger": "Kickoff", "failure_strategy": "Escalate to client contact within 1 business day of access failure", "audit_need": "Log every file received with a hash and timestamp" }, { "system": "E-signature (release acknowledgment)", "risk": "Signature service outage delays release", "internal_model": "PackRelease", "acl_strategy": "Fallback to a manually countersigned PDF if the service is down", "owner_context": "Release", "data_in": "Release record", "data_out": "Signed release document", "trigger": "SignRelease command", "failure_strategy": "Manual signature fallback", "audit_need": "Signed document retained per compliance-checklist.md" }, { "system": "Stripe", "risk": "Payment failure blocks pack kickoff", "internal_model": "Invoice", "acl_strategy": "Simple invoice API usage; no custom billing engine", "owner_context": "Payments (generic subdomain)", "data_in": "Client billing details", "data_out": "Invoice, receipt", "trigger": "Pack or retainer sale", "failure_strategy": "Manual invoice follow-up", "audit_need": "Standard Stripe transaction log" }, { "system": "CRM (Attio/HubSpot)", "risk": "Lead/consult data drifts from actual pipeline state", "internal_model": "Consult, Lead", "acl_strategy": "Founder-maintained at launch; single source of truth for funnel stage", "owner_context": "Sales & Diagnostic Funnel", "data_in": "Gap Scan submissions", "data_out": "Pipeline stage updates", "trigger": "Gap Scan form submit", "failure_strategy": "Weekly manual reconciliation", "audit_need": "None beyond standard CRM history" } ], "event_storm": [ { "seq": 1, "command": "StartIntake", "event": "IntakeStarted", "actor": "Culinary/ops leader", "context": "Intake", "aggregate": "EvidenceChecklistAggregate", "policy": "None", "downstream": "Evidence collection begins", "risk": "Low" }, { "seq": 2, "command": "ReceiveEvidenceItem", "event": "EvidenceItemReceived", "actor": "Client", "context": "Intake", "aggregate": "EvidenceChecklistAggregate", "policy": "None", "downstream": "Completeness scoring updates", "risk": "Low" }, { "seq": 3, "command": "EvaluateCompleteness", "event": "IntakeCompletenessGatePassed", "actor": "System (deterministic rule)", "context": "Intake", "aggregate": "EvidenceChecklistAggregate", "policy": "Gate passes only when every standard item has a source and every channel has an artifact", "downstream": "Extraction starts, SLA clock starts", "risk": "Medium -- false pass on shallow evidence" }, { "seq": 4, "command": "ExtractIngredients", "event": "IngredientsExtracted", "actor": "AI extraction agent", "context": "Extraction", "aggregate": "NormalizedMenuAggregate", "policy": "Never infer without a source_span", "downstream": "Mapping begins", "risk": "Medium -- hallucinated ingredient" }, { "seq": 5, "command": "MapItemToBigNine", "event": "MatrixDraftReady", "actor": "AI mapping agent", "context": "Mapping & Rules", "aggregate": "BigNineMatrixAggregate", "policy": "No blank cells; sesame always its own column", "downstream": "Exception Queue populated", "risk": "Medium -- pattern-library miss on a novel sauce" }, { "seq": 6, "command": "RouteException", "event": "ItemRoutedToExceptionQueue", "actor": "System (deterministic rule)", "context": "Mapping & Rules", "aggregate": "BigNineMatrixAggregate", "policy": "Any Unknown or low-confidence call routes", "downstream": "Specialist review queue grows", "risk": "Low" }, { "seq": 7, "command": "ResolveExceptionItem", "event": "ExceptionResolved", "actor": "Culinary/allergen-ops specialist", "context": "Release", "aggregate": "PackReleaseAggregate", "policy": "Resolve only with evidence", "downstream": "Item clears for release", "risk": "Medium -- specialist judgment on weak evidence" }, { "seq": 8, "command": "MarkHold", "event": "ItemMarkedHold", "actor": "Culinary/allergen-ops specialist", "context": "Release", "aggregate": "PackReleaseAggregate", "policy": "HOLD requires a named buyer action", "downstream": "HOLD list included in pack", "risk": "Low" }, { "seq": 9, "command": "SignRelease", "event": "PackReleased", "actor": "Culinary/allergen-ops specialist", "context": "Release", "aggregate": "PackReleaseAggregate", "policy": "Cannot fire while any item unresolved and not HOLD-marked", "downstream": "QA sampling begins", "risk": "High -- premature release under deadline pressure" }, { "seq": 10, "command": "RunQASample", "event": "QASamplePassed", "actor": "QA operator", "context": "QA & Delivery", "aggregate": "DeliveryAggregate", "policy": "5-item minimum sample, forbidden-claim scrub", "downstream": "Delivery proceeds", "risk": "Medium -- sample misses a systematic error" }, { "seq": 11, "command": "DeliverPack", "event": "PackDelivered", "actor": "System", "context": "QA & Delivery", "aggregate": "DeliveryAggregate", "policy": "Only after QASamplePassed", "downstream": "30-day deployment check scheduled", "risk": "Low" }, { "seq": 12, "command": "ConfirmDeployment", "event": "DeploymentConfirmed", "actor": "Culinary/ops leader", "context": "Portfolio & Refresh", "aggregate": "RefreshRetainerAggregate", "policy": "None", "downstream": "Retainer pitch eligible", "risk": "Low" }, { "seq": 13, "command": "ScheduleRefresh", "event": "RefreshScheduled", "actor": "Founder / account lead", "context": "Portfolio & Refresh", "aggregate": "RefreshRetainerAggregate", "policy": "Quarterly cadence", "downstream": "Next pipeline run scoped to deltas", "risk": "Low" } ], "critical_path": [ "IntakeCompletenessGatePassed -> IngredientsExtracted -> MatrixDraftReady -> ExceptionResolved (or ItemMarkedHold) -> PackReleased -> QASamplePassed -> PackDelivered" ], "exception_flows": [ "Missing supplier spec -> item routed to Exception Queue -> chased twice over 5 business days -> ships HOLD if unresolved", "Conflicting evidence across recipe and spec -> Exception Queue -> specialist adjudicates with both sources cited", "Digital channel declared without a Written Alternative on file -> release blocked until artifact attached" ], "escalation_flows": [ "Client requests a legal opinion -> referred to outside counsel, not answered internally", "Client requests a clinical/allergen-free claim -> referred to a registered dietitian", "Suspected reaction incident tied to a released pack -> immediate specialist escalation + insurance carrier notification", "Franchisee non-deployment at 30-day check -> escalate to release approver with Channel Checklist" ], "retry_flows": [ "Evidence chase: 2 touches over 5 business days before HOLD", "E-signature service outage: manual countersigned PDF fallback", "Delivery-app listing check failure: retried on the following business day" ], "manual_override_flows": [ "Specialist can force a HOLD on any item regardless of AI confidence score", "Specialist can override an auto-suggested Yes/No call with a documented reason", "Founder can pause new-logo intake at any Build-Before-Scale checkpoint regardless of pipeline pressure" ], "commands": [ { "name": "StartIntake", "issued_by": "Culinary/ops leader", "preconditions": [ "Kickoff scheduled" ], "aggregate": "EvidenceChecklistAggregate", "success_event": "IntakeStarted", "failure_event": "IntakeStartFailed", "authorization": "Any client contact", "validation": "Client identity confirmed", "audit": "Logged with timestamp" }, { "name": "ExtractIngredients", "issued_by": "AI extraction agent", "preconditions": [ "IntakeCompletenessGatePassed" ], "aggregate": "NormalizedMenuAggregate", "success_event": "IngredientsExtracted", "failure_event": "ExtractionFailed", "authorization": "System", "validation": "Document type recognized", "audit": "Source document hash logged" }, { "name": "MapItemToBigNine", "issued_by": "AI mapping agent", "preconditions": [ "IngredientsExtracted" ], "aggregate": "BigNineMatrixAggregate", "success_event": "MatrixDraftReady", "failure_event": "MappingBlocked", "authorization": "System", "validation": "Every item has 9 populated calls or Exception routing", "audit": "Rule version logged per call" }, { "name": "ResolveExceptionItem", "issued_by": "Culinary/allergen-ops specialist", "preconditions": [ "Item in Exception Queue" ], "aggregate": "PackReleaseAggregate", "success_event": "ExceptionResolved", "failure_event": "ResolutionRejected", "authorization": "Named specialist role only", "validation": "Evidence cited", "audit": "Specialist ID + evidence logged" }, { "name": "MarkHold", "issued_by": "Culinary/allergen-ops specialist", "preconditions": [ "Item in Exception Queue" ], "aggregate": "PackReleaseAggregate", "success_event": "ItemMarkedHold", "failure_event": "None", "authorization": "Named specialist role only", "validation": "Buyer action specified", "audit": "Specialist ID logged" }, { "name": "SignRelease", "issued_by": "Culinary/allergen-ops specialist", "preconditions": [ "No unresolved, non-HOLD Exception items" ], "aggregate": "PackReleaseAggregate", "success_event": "PackReleased", "failure_event": "ReleaseBlocked", "authorization": "Named specialist role only", "validation": "Invariant check on Exception Queue state", "audit": "Signature record retained" }, { "name": "DeliverPack", "issued_by": "System", "preconditions": [ "QASamplePassed" ], "aggregate": "DeliveryAggregate", "success_event": "PackDelivered", "failure_event": "DeliveryBlocked", "authorization": "System", "validation": "Forbidden-claim scrub clean", "audit": "Delivery timestamp + recipient logged" } ], "policies": [ { "name": "No blank Big-9 cells", "trigger": "MatrixDraftReady", "condition": "Any item missing a Yes/No/Unknown call for any allergen", "action": "Block release until populated", "context": "Mapping & Rules / Release", "ai_involvement": "AI drafts the call; rule enforces completeness", "human_approval": "Not required for this check itself, only for the underlying Unknown resolution" }, { "name": "Sesame explicit tracking", "trigger": "MatrixDraftReady", "condition": "Sesame merged into an 'other' category", "action": "Reject draft; require standalone sesame column", "context": "Mapping & Rules", "ai_involvement": "Enforced in extraction/mapping schema", "human_approval": "No" }, { "name": "Written Alternative required on digital channels", "trigger": "Channel Checklist finalized", "condition": "Any channel flagged digital=true without a completed Written Alternative", "action": "Block PackReleased", "context": "Release", "ai_involvement": "Drafts the artifact", "human_approval": "Specialist confirms completeness at release" }, { "name": "Auto-request specialist review on Exception Queue population", "trigger": "ItemRoutedToExceptionQueue", "condition": "Queue item age > 0", "action": "Notify specialist", "context": "Release", "ai_involvement": "None", "human_approval": "N/A (notification only)" }, { "name": "Forbidden-claim scrub before delivery", "trigger": "PackReleased", "condition": "Any banned phrase detected", "action": "Block PackDelivered until corrected", "context": "QA & Delivery", "ai_involvement": "AI + regex scrub pass", "human_approval": "QA operator confirms clean" } ], "aggregates": [ { "name": "EvidenceChecklistAggregate", "root": "EvidenceChecklist", "context": "Intake", "purpose": "Own the completeness gate for a single pack's intake evidence", "entities": [ "EvidenceItem" ], "value_objects": [ "ItemId", "ChannelInventoryEntry" ], "invariants": [ "Gate cannot pass with an unlogged gap" ], "commands": [ "StartIntake", "ReceiveEvidenceItem", "LogGap" ], "events": [ "IntakeStarted", "EvidenceItemReceived", "IntakeCompletenessGatePassed", "IntakeGapLogged" ], "repository": "EvidenceChecklistRepository", "transaction_boundary": "One Evidence Checklist per pack request" }, { "name": "NormalizedMenuAggregate", "root": "NormalizedMenu", "context": "Extraction", "purpose": "Own the structured, source-spanned ingredient list for a pack", "entities": [ "MenuItem", "Ingredient" ], "value_objects": [ "IngredientName" ], "invariants": [ "No ingredient without source_span or needs_spec flag" ], "commands": [ "ExtractIngredients" ], "events": [ "IngredientsExtracted", "SourceSpanMissing" ], "repository": "NormalizedMenuRepository", "transaction_boundary": "One normalized menu per pack request" }, { "name": "BigNineMatrixAggregate", "root": "BigNineMatrix", "context": "Mapping & Rules", "purpose": "Own the draft and final Big-9 calls for every item in a pack", "entities": [ "MatrixCell" ], "value_objects": [ "ConfidenceBand" ], "invariants": [ "No blank cells", "Sesame always its own column" ], "commands": [ "MapItemToBigNine", "RouteException" ], "events": [ "MatrixDraftReady", "PatternAlertRaised", "ItemRoutedToExceptionQueue" ], "repository": "BigNineMatrixRepository", "transaction_boundary": "One Matrix per pack request" }, { "name": "PackReleaseAggregate", "root": "PackRelease", "context": "Release", "purpose": "Own the Exception Queue and the signed release decision", "entities": [ "ExceptionQueueItem" ], "value_objects": [ "ReleaseDecision" ], "invariants": [ "PackReleased cannot fire with unresolved, non-HOLD items" ], "commands": [ "ResolveExceptionItem", "MarkHold", "SignRelease" ], "events": [ "ExceptionResolved", "ItemMarkedHold", "PackReleased" ], "repository": "PackReleaseRepository", "transaction_boundary": "One release record per pack request" }, { "name": "DeliveryAggregate", "root": "Delivery", "context": "QA & Delivery", "purpose": "Own QA sampling, claim scrub, and delivery state", "entities": [ "QASample" ], "value_objects": [ "ClaimScrubResult" ], "invariants": [ "PackDelivered only after QASamplePassed" ], "commands": [ "RunQASample", "DeliverPack" ], "events": [ "QASamplePassed", "PackDelivered", "DeploymentCheckDue" ], "repository": "DeliveryRepository", "transaction_boundary": "One delivery record per pack request" }, { "name": "RefreshRetainerAggregate", "root": "RefreshRetainer", "context": "Portfolio & Refresh", "purpose": "Own the Change Log and refresh scheduling for a retainer client", "entities": [ "ChangeLogEntry" ], "value_objects": [ "RefreshCycleWindow" ], "invariants": [ "Refresh cannot start before the prior pack's PackDelivered" ], "commands": [ "ConfirmDeployment", "ScheduleRefresh" ], "events": [ "DeploymentConfirmed", "RefreshScheduled" ], "repository": "RefreshRetainerRepository", "transaction_boundary": "One retainer record per client relationship" } ], "invariants": [ { "invariant": "No Big-9 Matrix cell ships blank", "context": "Mapping & Rules", "aggregate": "BigNineMatrixAggregate", "why": "A blank cell is indistinguishable from an unreviewed item to an inspector", "enforcement": "Deterministic rule blocks PackReleased" }, { "invariant": "Every Yes/No call cites a source_span", "context": "Mapping & Rules", "aggregate": "BigNineMatrixAggregate", "why": "Guessed calls are the core liability risk", "enforcement": "Schema-level requirement on the mapping output" }, { "invariant": "PackReleased requires a named specialist signature", "context": "Release", "aggregate": "PackReleaseAggregate", "why": "Accountability chokepoint cannot be automated away", "enforcement": "SignRelease command requires an authenticated specialist role" }, { "invariant": "No digital channel ships without a Written Alternative", "context": "Release", "aggregate": "PackReleaseAggregate", "why": "Statutory requirement under SB 68", "enforcement": "Release-blocking deterministic rule" }, { "invariant": "PackDelivered only follows QASamplePassed", "context": "QA & Delivery", "aggregate": "DeliveryAggregate", "why": "Prevents an unreviewed release from reaching the client", "enforcement": "Sequencing enforced in DeliveryAggregate" } ], "ai_agents": [ { "name": "Extraction agent", "context": "Extraction", "responsibility": "Parse recipes/specs/menus into structured ingredients with source spans", "inputs": [ "Raw document text", "item_id" ], "outputs": [ "Ingredient list with source spans and confidence" ], "tools": [ "Document parser", "LLM API" ], "forbidden_actions": [ "Inferring an ingredient without a source span" ], "memory_scope": "Single pack request", "retrieval_sources": [ "None -- extraction is source-document-only" ], "validations": [ "Source span required or explicit needs_spec flag" ], "confidence_scoring": "High/Medium/Low per ingredient", "escalation_triggers": [ "needs_spec flag raised" ], "human_approval": "Not required for extraction itself; required downstream at release", "failure_modes": [ "Missed componentized ingredient in a sauce name" ], "audit_logs": [ "Every extraction call logged with document hash" ], "metrics": [ "Extraction accuracy vs. specialist correction rate" ], "versioning": "Prompt version pinned per pack run" }, { "name": "Mapping agent", "context": "Mapping & Rules", "responsibility": "Map extracted ingredients to Big-9 Yes/No/Unknown calls using only provided evidence plus pattern-library alerts", "inputs": [ "Ingredient list with source spans", "pattern-library alerts" ], "outputs": [ "Draft Big-9 Matrix" ], "tools": [ "Big-9 dictionary", "hidden-ingredient pattern library", "LLM API" ], "forbidden_actions": [ "Returning No on absence of information alone" ], "memory_scope": "Single pack request, with pattern-library lookups scoped globally (anonymized)", "retrieval_sources": [ "Big-9 dictionary", "hidden-ingredient pattern library", "gold-standard pack library" ], "validations": [ "Every allergen call populated", "Sesame always separate" ], "confidence_scoring": "High/Medium/Low per call", "escalation_triggers": [ "Any Unknown or Medium/Low confidence call" ], "human_approval": "Required via Exception Queue for any non-High-confidence call", "failure_modes": [ "Pattern-library miss on a novel supplier product" ], "audit_logs": [ "Rule version + evidence cited per call" ], "metrics": [ "Exception Queue rate over time" ], "versioning": "Rule and prompt versions pinned per pack run" }, { "name": "Claim-scrub agent", "context": "QA & Delivery", "responsibility": "Detect forbidden phrases (allergen-free claims, guarantees) before delivery", "inputs": [ "Draft disclosure copy", "landing/marketing copy" ], "outputs": [ "Pass/fail with flagged spans" ], "tools": [ "Banned-phrase list", "LLM API" ], "forbidden_actions": [ "Approving unreviewed client-counsel override text without a logged approval" ], "memory_scope": "Single pack or content asset", "retrieval_sources": [ "Banned-phrase list" ], "validations": [ "No banned phrase present unless counsel-approved override logged" ], "confidence_scoring": "Binary pass/fail with flagged spans", "escalation_triggers": [ "Any flagged phrase" ], "human_approval": "QA operator confirms every flag", "failure_modes": [ "Novel phrasing not on the banned list" ], "audit_logs": [ "Scrub result logged per asset" ], "metrics": [ "Flags raised per pack" ], "versioning": "Banned-phrase list versioned and updated from real misses" } ], "prompt_chain_map": [ "Extraction prompt (Layer 2) -> Mapping prompt (Layer 4), chained on the structured ingredient list", "Mapping prompt (Layer 4) -> Drafting prompt (disclosure copy + Written Alternative), chained on the released Matrix" ], "rag_map": [ "Big-9 dictionary + hidden-ingredient pattern library retrieved at Mapping time", "Gold-standard prior pack library retrieved for pattern-matching on recurring ingredient names, never to infer new client's content" ], "ai_evaluation": [ "Fixed eval set of prior gold-standard packs re-run whenever the underlying model changes (Layer 10 model portability)", "Specialist correction rate tracked per pack as the primary extraction/mapping quality signal", "Exception Queue rate tracked as a leading indicator of pattern-library maturity" ], "hallucination_controls": [ "Every ingredient requires a source_span or explicit needs_spec flag", "Every Big-9 call requires cited evidence; absence of evidence yields Unknown, never No", "Deterministic rules (not the LLM) own the no-blank-cell and sesame-column invariants", "Specialist release is mandatory on every pack regardless of AI confidence" ], "human_in_the_loop_plan": [ "Exception Queue routes every Unknown/low-confidence/pattern-alert item to the specialist", "5-item QA sample reviewed by a human on every pack", "30-day deployment check is a human-conducted call, not an automated survey", "Legal/clinical questions always referred to a human outside AllergenPack (counsel/dietitian)" ], "ai_audit_plan": [ "Every extraction and mapping call logs its prompt version, evidence cited, and confidence band", "Specialist corrections logged and periodically reviewed to update the pattern library (Layer 9 learning loop)", "Quarterly review of Exception Queue rate and rework rate against financial-model.csv targets" ], "prompt_versioning": "Extraction and mapping prompts are versioned artifacts owned by AllergenPack (not embedded in a vendor platform); a model swap requires re-validation against the fixed eval set before the new version is promoted (ai-engine-spec.md Layer 10).", "human_roles": [ { "role": "Culinary/allergen-ops specialist", "responsibilities": [ "Resolve Exception Queue items", "Sign pack releases", "Mark HOLD with buyer action" ], "contexts": [ "Release" ], "decisions_owned": [ "Release vs. HOLD" ], "ai_support": [ "[PLACEHOLDER] owner to complete" ], "approval_authority": "Sole release signer", "escalation_authority": "Refers legal/clinical questions out", "quality_metrics": [ "Rework rate", "Exception Queue resolution time" ], "workload_risks": [ "Bottleneck if pilot volume outpaces one specialist" ] }, { "role": "Intake operator", "responsibilities": [ "Run completeness gate", "Log evidence gaps", "Chase missing evidence" ], "contexts": [ "Intake" ], "decisions_owned": [ "Gap logging" ], "ai_support": "Completeness checklist assistant", "approval_authority": "None -- cannot release", "escalation_authority": "Escalates chronic evidence gaps to specialist", "quality_metrics": [ "SLA adherence" ], "workload_risks": [ "Founder-doubling at launch" ] }, { "role": "QA operator", "responsibilities": [ "Run 5-item QA sample", "Confirm claim-scrub results" ], "contexts": [ "QA & Delivery" ], "decisions_owned": [ "QA pass/fail" ], "ai_support": "Claim-scrub agent", "approval_authority": "QA sign-off (distinct from release signature)", "escalation_authority": "Escalates systematic errors to specialist", "quality_metrics": [ "Post-delivery correction rate" ], "workload_risks": [ "Low at launch volume" ] }, { "role": "Founder / account lead", "responsibilities": [ "Sales, kickoff scheduling, 30-day deployment checks, retainer pitches" ], "contexts": [ "Sales & Diagnostic Funnel", "Portfolio & Refresh" ], "decisions_owned": [ "Pricing exceptions within published bands" ], "ai_support": "CRM pipeline view", "approval_authority": "Commercial terms within policy", "escalation_authority": "N/A", "quality_metrics": [ "Consult-to-paid conversion", "retainer attach rate" ], "workload_risks": [ "Founder is also the specialist at launch -- explicit dual-role risk" ] }, { "role": "External counsel (referral only)", "responsibilities": [ "Legal-conclusion questions on SB 68 applicability or franchise-agreement implications" ], "contexts": [ "Compliance & Licensing Boundary" ], "decisions_owned": [ "Legal opinions" ], "ai_support": "None", "approval_authority": "N/A -- not AllergenPack staff", "escalation_authority": "N/A", "quality_metrics": [ "N/A" ], "workload_risks": [ "N/A" ] }, { "role": "Registered dietitian (referral only)", "responsibilities": [ "Clinical/dietary claim questions" ], "contexts": [ "Compliance & Licensing Boundary" ], "decisions_owned": [ "Clinical guidance" ], "ai_support": "None", "approval_authority": "N/A -- not AllergenPack staff", "escalation_authority": "N/A", "quality_metrics": [ "N/A" ], "workload_risks": [ "N/A" ] } ], "human_review_checkpoints": [ "Exception Queue resolution (every Unknown/low-confidence item)", "Pack release signature (every pack)", "QA 5-item sample (every pack)", "30-day deployment check (every delivered pack)" ], "escalation_matrix": [ "Evidence gap unresolved after 2 chases -> HOLD + written notice to release approver", "Legal or clinical question -> external referral, never answered internally" ], "manual_override_rules": [ "Specialist may override any AI-suggested call with a documented reason", "Founder may pause new-logo intake at any build-before-scale checkpoint" ], "separation_of_duties": [ "The operator who logs intake evidence gaps is never the same person who signs the release, once the team grows past the founder-only stage" ], "quality_control_workflow": [ "Draft -> Exception Queue -> Specialist Release -> QA sample -> Delivery, with no stage skippable and every transition event-logged" ], "data_objects": [ { "name": "EvidenceChecklist", "meaning": "The gated record of intake evidence for one pack request", "owner_context": "Intake", "writers": [ "Intake operator", "Client" ], "readers": [ "Extraction", "Release" ], "source_of_truth": "Intake context", "retention": "Per compliance-checklist.md retention rules", "privacy": "Client-confidential", "audit": "Every received item logged with hash and timestamp" }, { "name": "NormalizedMenu", "meaning": "Structured, source-spanned ingredient list", "owner_context": "Extraction", "writers": [ "Extraction agent" ], "readers": [ "Mapping & Rules" ], "source_of_truth": "Extraction context", "retention": "Per compliance-checklist.md", "privacy": "Client-confidential", "audit": "Document hash logged at extraction" }, { "name": "BigNineMatrix", "meaning": "Item-level Yes/No/Unknown calls across all nine allergens", "owner_context": "Mapping & Rules", "writers": [ "Mapping agent", "Specialist (on resolution)" ], "readers": [ "Release", "QA & Delivery", "Client" ], "source_of_truth": "Mapping & Rules context", "retention": "Retained for the life of the client relationship plus buffer", "privacy": "Client-confidential until released, then client-owned" }, { "name": "ExceptionQueueItem", "meaning": "A flagged item awaiting specialist resolution", "owner_context": "Release", "writers": [ "Mapping & Rules (routing)", "Specialist (resolution)" ], "readers": [ "Specialist" ], "source_of_truth": "Release context", "retention": "Retained with the pack record", "privacy": "Client-confidential" }, { "name": "PackRelease", "meaning": "The signed record of a released pack", "owner_context": "Release", "writers": [ "Specialist" ], "readers": [ "QA & Delivery", "Client", "Audit" ], "source_of_truth": "Release context", "retention": "Per compliance-checklist.md", "privacy": "Client-confidential, shared with client on delivery" }, { "name": "HiddenIngredientPatternLibrary", "meaning": "Generalized patterns (never client-specific verbatim) used to alert Mapping on likely hidden allergens", "owner_context": "Mapping & Rules", "writers": [ "Learning loop (from specialist corrections)" ], "readers": [ "Mapping agent" ], "source_of_truth": "Mapping & Rules context", "retention": "Indefinite, generalized only", "privacy": "Anonymized -- never a specific client's proprietary recipe" } ], "read_models": [ "Weekly Monday digest: open Exception Queue items, packs in flight, upcoming 30-day deployment checks", "CRM pipeline view: Gap Scans, consults, paid packs, retainer status" ], "reporting_models": [ "Monthly financial-model.csv reconciliation against actuals" ], "data_duplication_notes": [ "The delivered pack PDF and the editable spreadsheet Matrix intentionally duplicate the same data in two formats for client convenience -- the spreadsheet is the source of truth for any post-delivery correction" ], "data_retention": [ "Client evidence and released packs retained per compliance-checklist.md pending final counsel-set retention period", "Hidden-ingredient pattern library retained indefinitely in anonymized/generalized form" ], "data_quality_risks": [ "Stale supplier spec used after an undisclosed substitution", "Franchisee-modified menu diverging from the released Matrix without a Refresh" ], "use_cases": [ { "name": "Produce a founding Completeness Pack", "actor": "Culinary/ops leader + Culinary/allergen-ops specialist", "context": "Menu Allergen Completeness Pack Production", "goal": "Ship a released, evidence-backed Big-9 disclosure pack within the 10-business-day SLA", "preconditions": [ "Kickoff scheduled", "Evidence Checklist started" ], "main_flow": [ "StartIntake", "EvidenceItemReceived (repeated)", "IntakeCompletenessGatePassed", "ExtractIngredients", "MapItemToBigNine", "Exception Queue resolution", "SignRelease", "RunQASample", "DeliverPack" ], "alternative_flows": [ "Evidence gap unresolved -> item ships HOLD" ], "business_rules": [ "No blank cells", "Written Alternative required on digital channels" ], "ai_role": "Extraction, mapping draft, disclosure copy draft, claim scrub", "human_role": "Intake gating, exception resolution, release signature, QA sample", "commands": [ "StartIntake", "ExtractIngredients", "MapItemToBigNine", "ResolveExceptionItem", "SignRelease", "RunQASample", "DeliverPack" ], "events": [ "IntakeCompletenessGatePassed", "MatrixDraftReady", "PackReleased", "PackDelivered" ], "aggregates": [ "EvidenceChecklistAggregate", "NormalizedMenuAggregate", "BigNineMatrixAggregate", "PackReleaseAggregate", "DeliveryAggregate" ], "success": "Pack delivered within SLA with all items resolved or explicitly HOLD-marked", "failure_handling": "SLA extension communicated in writing if evidence blocks completion", "audit": "Full event log retained per compliance-checklist.md" }, { "name": "Run a free Gap Scan", "actor": "Prospect", "context": "Sales & Diagnostic Funnel", "goal": "Get an itemized gap report from a public menu within 2 business days", "preconditions": [ "Public menu URL or PDF submitted" ], "main_flow": [ "Menu submitted", "Automated gap detection", "Itemized Gap Scan PDF generated", "Delivered to prospect" ], "alternative_flows": [ "Brand not covered under the 20-location test -> Gap Scan states this plainly" ], "business_rules": [ "Gap Scan is diagnosis only, never a Completeness Pack" ], "ai_role": "Gap detection from public menu content", "human_role": "Founder reviews before send at launch volume", "commands": [ "SubmitGapScanRequest" ], "events": [ "GapScanRequested", "GapScanDelivered" ], "aggregates": [ "N/A -- lightweight funnel object, not a core aggregate" ], "success": "Prospect receives an accurate, honest gap report", "failure_handling": "Manual follow-up if automated detection is inconclusive", "audit": "CRM log of submission and delivery" }, { "name": "Run a Quarterly Refresh", "actor": "Culinary/ops leader + Culinary/allergen-ops specialist", "context": "Portfolio & Refresh", "goal": "Re-run the pipeline against supplier/menu deltas and keep the Change Log current", "preconditions": [ "Active Refresh Retainer", "Prior Completeness Pack on file" ], "main_flow": [ "Client reports or system detects a change", "ScheduleRefresh", "Delta-scoped Extraction/Mapping", "Exception Queue on new/changed items only", "SignRelease (refresh)", "DeliverPack (refresh)" ], "alternative_flows": [ "No material change found -> Change Log updated with a null result, no re-release needed" ], "business_rules": [ "Same no-blank-cell and Written Alternative rules apply to refresh packs" ], "ai_role": "Change detection, delta extraction/mapping", "human_role": "Specialist review on any changed item", "commands": [ "ScheduleRefresh", "ResolveExceptionItem", "SignRelease" ], "events": [ "RefreshScheduled", "PackReleased", "PackDelivered" ], "aggregates": [ "RefreshRetainerAggregate", "BigNineMatrixAggregate", "PackReleaseAggregate" ], "success": "Change Log current, any new allergen risk resolved before the next reprint", "failure_handling": "Escalate if the client won't supply the changed supplier spec", "audit": "Change Log entry per refresh cycle" }, { "name": "Confirm 30-day deployment", "actor": "Founder / account lead", "context": "Portfolio & Refresh", "goal": "Confirm the released pack is live across the client's declared channels", "preconditions": [ "PackDelivered" ], "main_flow": [ "30-day check email sent", "Client confirms channel-by-channel deployment", "DeploymentConfirmed logged" ], "alternative_flows": [ "Channels not yet deployed -> escalation flow with Channel Checklist as the guide" ], "business_rules": [ "Deployment confirmation, not pack delivery, is the north-star metric" ], "ai_role": "None", "human_role": "Founder/account lead conducts the check", "commands": [ "ConfirmDeployment" ], "events": [ "DeploymentConfirmed" ], "aggregates": [ "RefreshRetainerAggregate" ], "success": "All declared channels confirmed live", "failure_handling": "Escalation flow to release approver", "audit": "Deployment confirmation logged per pack" } ], "architecture": { "style": "modular-monolith-event-driven", "why": "Single team + single regulated vertical per blueprint + strong consistency requirements around specialist release / delivery / release-decision favor a monolith. Event-driven internals give us the audit-friendly append-only log without the operational cost of microservices.", "rejected_alternatives": [ "Microservices — no independent scaling or team boundary justifies distributed cost yet.", "Serverless-workflow-only — reviewer specialist release and audit invariants are easier to keep correct in a monolith.", "No-code / low-code — cannot enforce OutputValidator, prompt versioning, or per-tenant retrieval isolation with fidelity." ], "backend_modules": [ "Service Fulfillment", "AI Orchestration", "Quality Assurance", "Compliance & Governance", "Sales & Intake", "Client Onboarding & Profile", "Client Delivery & Success", "Knowledge Base & Retrieval", "Analytics & Reporting" ], "frontend_modules": [ "Operator dashboard", "Reviewer console", "Client portal", "Owner console", "Ops (prompt registry) console" ], "api_boundaries": [ "/intake/*", "/artifacts/*", "/reviewer/*", "/compliance/*", "/knowledge/*", "/admin/*" ], "database_strategy": "One managed Postgres; schema-per-context; cross-context reads via published projections; RLS on protected tables.", "event_bus": "In-process event dispatcher backed by an outbox table (transactional publish); upgrade path to a real broker if throughput demands.", "queue": "Background job queue (managed) for AI runs, delivery adapters, and reindex jobs.", "workflow_engine": "None initially — orchestrate via domain events + policies; add a workflow engine if orchestrations exceed 5 sequential steps.", "ai_orchestration": "AI Orchestration context owns bounded agents; OutputValidator + prompt registry + tenant-scoped retrieval; retries with backoff.", "rag_layer": "Per-tenant partitioned retrieval indices in a managed vector DB; ingestion pipeline in Knowledge Base context.", "file_storage": "Managed blob storage with per-tenant prefixes + signed URLs; artifacts hashed on write.", "authn_authz": "IdP (Google / Okta) for authn; RBAC via dedicated roles table with server-side checks + RLS.", "admin_dashboard": "Ops-facing admin for tenants, users, feature flags, prompt versions.", "client_portal": "Customer-facing portal: submit intake, see status, receive artifacts.", "operator_dashboard": "Internal: intake queue, reviewer queue, exception-queue queue, delivery health.", "observability": "Structured logs with tenant + request ids; RED metrics per workflow; error tracking with source maps; model-call spans with cost + latency; SLO review weekly.", "audit_logging": "Append-only audit log for all state transitions; hash-chained snapshots on signed artifacts.", "deployment": "Single production region + multi-AZ managed DB; per-PR preview deploys; migrations gated on review." }, "module_structure": { "tree": "/src\n /contexts\n /sales-intake\n /domain\n /application\n /infrastructure\n /interfaces\n /client-onboarding\n /domain\n /application\n /infrastructure\n /interfaces\n /service-fulfillment\n /domain\n /application\n /infrastructure\n /interfaces\n /ai-orchestration\n /domain\n /application\n /infrastructure\n /interfaces\n /quality-assurance\n /domain\n /application\n /infrastructure\n /interfaces\n /compliance-governance\n /domain\n /application\n /infrastructure\n /interfaces\n /client-delivery\n /domain\n /application\n /infrastructure\n /interfaces\n /knowledge-base\n /domain\n /application\n /infrastructure\n /interfaces\n /analytics\n /domain\n /application\n /infrastructure\n /interfaces\n /shared\n /kernel # tiny — Ids, Money, Tenant, Actor\n /events # published-language event contracts\n /auth # session + role primitives\n /observability # logging, metrics, tracing\n /config", "modules": [ { "name": "service-fulfillment", "purpose": "PackRequest → Completeness Pack lifecycle", "owned_domain": [ "PackRequest", "Draft", "Completeness Pack", "Delivery" ], "application_services": [ "OpenIntake", "AttachEvidence", "SubmitForSpecialist Release", "DeliverCompletenessPack" ], "infra_adapters": [ "Pack delivery adapter", "Outbox publisher" ], "public_interfaces": [ "/intake/*", "/artifacts/*" ], "forbidden_deps": [ "billing infra", "identity provider internals" ] }, { "name": "ai-orchestration", "purpose": "Bounded AI agents", "owned_domain": [ "AgentRun", "PromptVersion" ], "application_services": [ "StartAgentRun", "PublishPromptVersion" ], "infra_adapters": [ "OpenAI/Anthropic client", "Retrieval router" ], "public_interfaces": [ "internal" ], "forbidden_deps": [ "cross-tenant retrieval", "direct delivery" ] }, { "name": "quality-assurance", "purpose": "Specialist Release + retraction", "owned_domain": [ "Specialist Release", "Retraction" ], "application_services": [ "ApproveArtifact", "FileRetraction" ], "infra_adapters": [ "Signature service" ], "public_interfaces": [ "/reviewer/*" ], "forbidden_deps": [ "draft content mutation" ] }, { "name": "compliance-governance", "purpose": "Owner-action ledger + release decision", "owned_domain": [ "OwnerActionLedger", "ReleaseDecision", "DSARRequest" ], "application_services": [ "ResolveOwnerAction", "ProcessDSAR" ], "infra_adapters": [ "Email adapter" ], "public_interfaces": [ "/compliance/*" ], "forbidden_deps": [ "draft content" ] } ], "dependency_rules": [ "Domain layer must not depend on infrastructure.", "Application layer may depend on domain.", "Infrastructure implements ports defined by application/domain.", "Interfaces call application services.", "Shared kernel must remain small (Ids, Money, Tenant, Actor).", "Contexts communicate through published events or explicit application APIs — never via direct database access to another context." ] }, "security_governance": { "controls": [ { "risk": "Prompt injection via customer input", "context": "AI Orchestration", "impact": "high", "control": "Input scrubber + OutputValidator + tenant-scoped retrieval", "audit": "AgentRun trace" }, { "risk": "Cross-tenant retrieval leak", "context": "Knowledge Base", "impact": "severe", "control": "Per-tenant index partitions + TenantIsolationSpec enforced at router", "audit": "Retrieval call log" }, { "risk": "Signature spoofing", "context": "Quality Assurance", "impact": "severe", "control": "Signature bound to authenticated session; server-side validation", "audit": "Signature manifest" }, { "risk": "Premature public claim", "context": "Compliance & Governance", "impact": "high", "control": "ReleaseReadinessSpec on OwnerActionLedger", "audit": "Release-decision log" }, { "risk": "Privilege exception-queue", "context": "Identity & Access", "impact": "high", "control": "Roles in dedicated table + server-side checks + RLS", "audit": "Role assignment log" }, { "risk": "Silent delivery failure", "context": "Client Delivery & Success", "impact": "medium", "control": "Adapter receipt required; alert customer within 1h on failure", "audit": "Delivery receipt archive" } ], "ai_governance": [ "Every prompt version has a named owner + evaluator run + rollout flag", "AI outputs marked as suggestions until reviewer specialist release", "Model + prompt inventory maintained in Ops console" ], "prompt_injection_defense": [ "Strip / neutralize instruction-like patterns in customer inputs before prompt assembly", "Never concatenate raw customer input into a system prompt", "OutputValidator rejects outputs that reference forbidden actions" ], "sensitive_data_handling": [ "PII scrubbed from logs", "Regulated data classes never sent to external model providers unless BAA/DPA covers it", "Per-tenant blob storage prefixes + signed URLs" ], "access_control_matrix": [ { "role": "Customer operator", "context": "Service Fulfillment", "capabilities": [ "OpenIntake", "AttachEvidence", "View own artifacts" ] }, { "role": "allergen-ops specialist", "context": "Quality Assurance", "capabilities": [ "ApproveArtifact", "RejectArtifact", "Co-sign retraction" ] }, { "role": "Business owner", "context": "Compliance & Governance", "capabilities": [ "ResolveOwnerAction", "Set release decision" ] }, { "role": "Legal", "context": "Quality Assurance + Compliance", "capabilities": [ "Co-sign retraction", "Handle DSAR" ] }, { "role": "Ops", "context": "AI Orchestration", "capabilities": [ "PublishPromptVersion", "Set confidence threshold" ] }, { "role": "Platform admin", "context": "Identity & Access", "capabilities": [ "Provision users", "Assign roles" ] } ], "audit_log_requirements": [ "Append-only", "Actor + tenant + timestamp + command + before/after hash", "PII scrubbed", "Exportable per tenant on request (DSAR support)" ] }, "observability": { "metrics": [ { "metric": "Reviewer-signed artifacts / week / tenant", "type": "business", "context": "Service Fulfillment", "why": "North star: repeatable value delivery", "target": "≥ contracted cadence", "alert_threshold": "< 80% of contracted cadence" }, { "metric": "AI draft acceptance rate", "type": "ai-quality", "context": "AI Orchestration", "why": "Signals grounding + prompt fit", "target": "≥ 70% by Phase 2", "alert_threshold": "< 50% weekly" }, { "metric": "Exception Queue rate", "type": "ai-quality", "context": "AI Orchestration", "why": "Guardrails firing correctly", "target": "5-15%", "alert_threshold": "> 30% weekly" }, { "metric": "Cycle time to specialist release (p50 + p95)", "type": "operational", "context": "Quality Assurance", "why": "Reviewer throughput", "target": "p95 ≤ 5 business days", "alert_threshold": "> 5 business days" }, { "metric": "Specialist Release-to-retraction ratio", "type": "risk", "context": "Quality Assurance", "why": "Correctness signal", "target": "< 1%", "alert_threshold": "any retraction week-over-week" }, { "metric": "Delivery failure rate", "type": "reliability", "context": "Client Delivery & Success", "why": "Customer-facing reliability", "target": "< 0.5%", "alert_threshold": "> 1% daily" }, { "metric": "Owner-action open count", "type": "business", "context": "Compliance & Governance", "why": "Public-release readiness", "target": "0 for launched blueprints", "alert_threshold": "any blocker aging > 30 days" }, { "metric": "Model cost per artifact", "type": "financial", "context": "AI Orchestration", "why": "Margin control", "target": "≤ target per pricing model", "alert_threshold": "> 1.5× target" }, { "metric": "Cross-tenant retrieval violation attempts", "type": "risk", "context": "Knowledge Base", "why": "Security invariant", "target": "0", "alert_threshold": "any > 0" }, { "metric": "First-artifact time per tenant", "type": "customer", "context": "Client Onboarding & Profile", "why": "Activation", "target": "≤ 2 weeks", "alert_threshold": "> 4 weeks" } ], "dashboards": [ "Operator dashboard", "Reviewer queue", "Delivery health", "AI cost + exception-queue", "Compliance blockers" ], "audit_reports": [ "Per-tenant audit-log export", "Signature manifest export" ], "quality_review_reports": [ "Reviewer calibration report", "Exception Queue-outcome report" ], "ai_evaluation_reports": [ "Evaluator regression report", "Prompt-rollout diff" ], "client_outcome_reports": [ "Artifacts delivered", "Cycle time", "Retraction rate" ] }, "testing_strategy": { "tests": [ { "type": "Domain unit", "validates": "Aggregate invariants", "context": "all core contexts", "example": "CompletenessPackAggregate rejects deliver without specialist release" }, { "type": "Aggregate invariant", "validates": "Consistency boundaries", "context": "Service Fulfillment / QA", "example": "Signed artifact is immutable" }, { "type": "Policy", "validates": "Reactive rules", "context": "AI Orchestration", "example": "Escalates below confidence threshold" }, { "type": "Specification", "validates": "Reusable rules", "context": "Compliance", "example": "ReleaseReadinessSpec blocks 'ready' with open owner actions" }, { "type": "Application use-case", "validates": "End-to-end command flow", "context": "Fulfillment + QA", "example": "Deliver signed artifact happy path" }, { "type": "Integration", "validates": "Adapter behavior", "context": "External Integrations", "example": "Stripe subscription webhook translates correctly" }, { "type": "Contract", "validates": "Published-language event schemas", "context": "cross-context", "example": "DraftProduced payload matches consumer expectations" }, { "type": "AI prompt eval", "validates": "Prompt quality vs golden dataset", "context": "AI Orchestration", "example": "Drafter accepts ≥ 40% in shadow mode" }, { "type": "RAG retrieval", "validates": "Tenant isolation + coverage", "context": "Knowledge Base", "example": "Cross-tenant lookup returns zero rows" }, { "type": "Golden dataset", "validates": "AI regression", "context": "AI Orchestration", "example": "No regression on past accepted artifacts" }, { "type": "Human review simulation", "validates": "Exception Queue UX", "context": "QA", "example": "Reviewer can complete specialist release in ≤ 5 clicks" }, { "type": "End-to-end", "validates": "Critical path", "context": "all", "example": "Intake → specialist release → delivery in staging" }, { "type": "Security", "validates": "Auth + RLS + injection defense", "context": "Identity + AI Orchestration", "example": "Prompt-injection payload is neutralized" }, { "type": "Regression", "validates": "No drift on prior fixes", "context": "all", "example": "Prior retraction bug does not reappear" } ], "critical_domain_rules": [ "No delivery without specialist release", "No AI output without OutputValidator pass", "No retrieval outside tenant partition", "No public-release flip with open blockers" ], "ai_eval_dataset": [ "50 past reviewer-accepted artifacts per vertical (redacted)", "20 rejected drafts (ground truth for exception-queue)", "10 injection-payload cases" ], "regression_plan": "Every PR runs domain + policy + spec unit tests. Every prompt release runs Evaluator with regression gate. Weekly critical-path smoke test in staging.", "contract_testing_plan": "Published-language event schemas versioned in /shared/events; consumer tests run in CI against schema-version compatibility.", "manual_qa_checklist": [ "Specialist Release flow: signature captured + timestamp + hash", "Retraction flow: co-sign captured + customer notified", "Delivery flow: receipt archived", "DSAR flow: export completes end-to-end" ] }, "mvp_roadmap": [ { "phase": "Phase 0 — Manual workflow with instrumented capture", "goal": "Deliver one artifact end-to-end manually, capture every step as a domain event.", "features": [ "Manual intake form", "Evidence upload", "Human draft", "Reviewer specialist release via signed form" ], "contexts": [ "Sales & Intake", "Service Fulfillment", "Quality Assurance" ], "ai_needs": [ "[PLACEHOLDER] owner to complete" ], "human_workflows": [ "Reviewer specialist release" ], "data_needs": [ "pack request", "recipe/spec evidence", "Completeness Pack" ], "integrations": [ "Email" ], "risks": [ "Un-audited manual step" ], "exit_criteria": [ "1 real artifact delivered + specialist-released" ] }, { "phase": "Phase 1 — AI-assisted drafting for internal use only", "goal": "Introduce Drafter Agent with reviewer gate; no customer-facing AI language.", "features": [ "Drafter Agent (internal)", "OutputValidator", "Exception Queue route" ], "contexts": [ "AI Orchestration", "Service Fulfillment" ], "ai_needs": [ "Drafter, Classifier" ], "human_workflows": [ "Exception Queue review" ], "data_needs": [ "AgentRun", "PromptVersion" ], "integrations": [ "OpenAI / Anthropic" ], "risks": [ "Prompt injection", "Grounding drift" ], "exit_criteria": [ "AI draft acceptance rate ≥ 40% in shadow mode" ] }, { "phase": "Phase 2 — Operator dashboard + owner-action ledger", "goal": "Make the workflow legible + governable for the owner.", "features": [ "Operator dashboard", "Owner-action ledger", "Release-decision engine" ], "contexts": [ "Compliance & Governance" ], "ai_needs": [], "human_workflows": [ "Owner action resolution" ], "data_needs": [ "OwnerActionLedger" ], "integrations": [ "IdP" ], "risks": [ "Ungoverned public claims" ], "exit_criteria": [ "Release decisions computed from ledger" ] }, { "phase": "Phase 3 — Client delivery portal", "goal": "Give customers a portal to see status + receive artifacts.", "features": [ "Client portal", "Pack delivery adapter", "Revision workflow" ], "contexts": [ "Client Delivery & Success" ], "ai_needs": [], "human_workflows": [ "Success cadence" ], "data_needs": [ "Delivery" ], "integrations": [ "Email" ], "risks": [ "Silent delivery failure" ], "exit_criteria": [ "Delivery-failure alert within 1h" ] }, { "phase": "Phase 4 — Automated QA + reporting", "goal": "Wire metrics, retraction runbook, and evaluator agent.", "features": [ "Evaluator Agent", "Retraction workflow", "Dashboards" ], "contexts": [ "Analytics & Reporting", "Quality Assurance" ], "ai_needs": [ "Evaluator" ], "human_workflows": [ "Retraction co-sign" ], "data_needs": [ "Retraction" ], "integrations": [], "risks": [ "Vanity metrics" ], "exit_criteria": [ "North-star + guardrail metrics live" ] }, { "phase": "Phase 5 — Scale + optimization", "goal": "Reduce cost per artifact, increase reviewer throughput.", "features": [ "Prompt versioning UI", "Cost budgeting", "Multi-reviewer queue" ], "contexts": [ "AI Orchestration", "Quality Assurance" ], "ai_needs": [ "Cost meter" ], "human_workflows": [ "Multi-reviewer routing" ], "data_needs": [], "integrations": [], "risks": [ "Regression on rollout" ], "exit_criteria": [ "Model cost per artifact ≤ target" ] } ], "scaling_roadmap": [ { "stage": "≤ 5 tenants", "trigger": "Design-partner cohort", "architecture_change": "Single-region modular monolith + managed DB", "operational_change": "Founder-led ops; weekly working session", "risk": "Single-owner queue" }, { "stage": "5-25 tenants", "trigger": "First paid conversions", "architecture_change": "Extract heaviest module (AI Orchestration) behind an internal queue; keep monolith", "operational_change": "Named on-call rotation; SOC 2 Type I scoping", "risk": "Reviewer bottleneck" }, { "stage": "25-100 tenants", "trigger": "Multi-reviewer demand", "architecture_change": "Split AI Orchestration into its own service if throughput/isolation demands it; per-tenant retrieval sharding", "operational_change": "Dedicated success + prompt-ops roles", "risk": "Prompt version drift" }, { "stage": "100+ tenants", "trigger": "Enterprise + regulated segments", "architecture_change": "Regional deployments; per-region data residency; segregated compliance environments", "operational_change": "Dedicated SRE + compliance team; SOC 2 Type II + framework additions", "risk": "Compliance framework demand exceeds team capacity" } ], "risk_register": [ { "risk": "Allergen miss reaches a guest via a released pack", "likelihood": "Medium", "impact": "High", "signal": "Post-delivery correction rate rising", "mitigation": "Evidence-only mapping, mandatory HOLD, E&O insurance", "owner": "Culinary/allergen-ops specialist", "context": "Release" }, { "risk": "Client withholds supplier specs, blocking release", "likelihood": "High", "impact": "Medium", "signal": "SLA miss rate on evidence grounds", "mitigation": "Intake completeness gate, HOLD ships with named buyer action", "owner": "Intake operator", "context": "Intake" }, { "risk": "Specialist becomes a single point of failure", "likelihood": "Medium", "impact": "High", "signal": "Release backlog growing week over week", "mitigation": "Build-before-scale checkpoints pause new-logo intake before backlog compounds", "owner": "Founder", "context": "Release" }, { "risk": "Delivery-app channel drift after release", "likelihood": "High", "impact": "Medium", "signal": "30-day deployment check shows partial deployment", "mitigation": "Delivery-Channel Sync add-on, deployment-confirmation KPI", "owner": "Founder / account lead", "context": "Portfolio & Refresh" }, { "risk": "Pattern-library miss on a novel supplier product", "likelihood": "Medium", "impact": "Medium", "signal": "A hidden allergen surfaces post-delivery that evidence should have caught", "mitigation": "Learning loop promotes every specialist correction to the pattern library", "context": "Mapping & Rules", "owner": "Culinary/allergen-ops specialist" }, { "risk": "Multi-state copycat legislation fragments the rule engine", "likelihood": "Medium", "impact": "Low-Medium", "signal": "A copycat state bill (MD/NJ/IL/OH/MO/NY/MI) passes with materially different thresholds", "mitigation": "Rule engine is modular per state by design; expands TAM rather than breaking the model", "owner": "Founder", "context": "Mapping & Rules" } ], "adrs": [ { "id": "ADR-1", "decision": "Deterministic rules, not the LLM, own the no-blank-cell and sesame-column invariants", "status": "Accepted", "context": "An LLM alone could plausibly fill a cell without real evidence", "options": [ "LLM self-checks its own output", "Deterministic rule layer separate from the LLM" ], "chosen": "Deterministic rule layer", "business_reason": "Guessed allergen calls are the top liability risk", "technical_reason": "Rules are auditable, versioned, and testable independent of model behavior", "tradeoffs": [ "[PLACEHOLDER] owner to complete" ], "risks": [ "[PLACEHOLDER] owner to complete" ], "revisit_trigger": "A missed invariant traced to the rule layer, not the model" }, { "id": "ADR-2", "decision": "Specialist release is mandatory on every pack, regardless of AI confidence", "status": "Accepted", "context": "High-confidence AI output could tempt an auto-release shortcut at scale", "options": [ "Auto-release on High confidence items", "Mandatory specialist signature on every pack" ], "chosen": "Mandatory specialist signature", "business_reason": "Accountability chokepoint is the core trust claim to buyers", "technical_reason": "Keeps the release event's authorization model simple and consistent", "tradeoffs": "Caps throughput at specialist capacity", "risks": "Specialist becomes a bottleneck at volume", "revisit_trigger": "Verified track record over 100+ packs might justify auto-release for High-confidence, no-Exception-Queue packs -- not before" }, { "id": "ADR-3", "decision": "Hidden-ingredient pattern library stores generalized patterns only, never client-specific recipes verbatim", "status": "Accepted", "context": "Cross-client learning is valuable but recipes are confidential", "options": [ "Store client recipes for cross-client retrieval", "Store only generalized, anonymized patterns" ], "chosen": "Generalized patterns only", "business_reason": "Confidentiality commitment to clients", "technical_reason": "Avoids a data-handling liability surface", "tradeoffs": "Slightly less precise pattern matching than raw recipe retrieval would give", "risks": "Over-generalization misses a client-specific edge case", "revisit_trigger": "None expected -- this is a confidentiality-driven design constraint, not a performance tradeoff to revisit" } ], "self_audit": { "scores": [ { "category": "Domain clarity", "score": 4.5, "weakness": "Depends on assumptions not yet validated with pilot data.", "improvement": "Maintain the current standard; re-audit after the first pilots land real data." }, { "category": "Bounded-context separation", "score": 4, "weakness": "Depends on assumptions not yet validated with pilot data.", "improvement": "Maintain the current standard; re-audit after the first pilots land real data." }, { "category": "AI-safety controls", "score": 4.5, "weakness": "Depends on assumptions not yet validated with pilot data.", "improvement": "Maintain the current standard; re-audit after the first pilots land real data." }, { "category": "Evidence rigor", "score": 4.5, "weakness": "Depends on assumptions not yet validated with pilot data.", "improvement": "Maintain the current standard; re-audit after the first pilots land real data." }, { "category": "Buildability at launch scale", "score": 4, "weakness": "Depends on assumptions not yet validated with pilot data.", "improvement": "Maintain the current standard; re-audit after the first pilots land real data." } ], "weakest_parts": [ "Franchise-level multi-brand reporting is deferred, not designed -- acceptable at launch scale but a gap if a large franchisor signs early", "Exact TAM figure for the 20+ unit / CA-door cohort remains an estimate, not a registry count" ], "biggest_assumptions": [ "Buyers will pay a DFY premium over operating SaaS themselves", "Recipe/supplier evidence is collectible within the SLA window for most clients" ], "highest_risk_decisions": [ "Mandatory specialist release caps throughput at one person's capacity at launch" ], "needs_domain_expert": [ "Confirm the hidden-ingredient pattern library's initial seed list with a real culinary/allergen-ops practitioner before pilot 1" ], "needs_legal": [ "Engagement-letter outline and E&O insurance confirmation before the first paid client (see compliance-checklist.md)" ], "needs_prototype": [ "Extraction/mapping prompt pair should be validated against 3-5 real client recipe sets before pilot 1, not just the blueprint's illustrative examples" ], "validate_before_prod": [ "Confidence-band thresholds (High/Medium/Low) should be tuned against actual pilot-cohort extraction accuracy, not assumed from the blueprint alone" ] }, "final_recommendations": [ "Keep the specialist-release chokepoint human regardless of model quality improvements -- it is the trust claim, not a temporary limitation", "Do not build the lightweight intake portal before the 10-pilot build-before-scale checkpoint", "Track deployment confirmation, not pack delivery, as the north-star metric", "Seed the hidden-ingredient pattern library from real specialist corrections starting with pilot 1, not from generic industry lists alone", "Revisit multi-state expansion only after CA unit economics clear the day-90 gate in launch-plan.md" ], "extensions": { "service_business_reality_check": { "is_service_business": true, "paid_outcome_clear": true, "workflow_present": true, "ai_native_fit_score": 4.4, "red_flags": [ "[PLACEHOLDER] owner to complete" ] }, "ai_native_fit": { "score": 4.4, "why": "Cross-document evidence synthesis at SKU scale with judgment concentrated at a single release chokepoint is a strong fit for AI-plus-specialist delivery", "disqualifiers": [ "[PLACEHOLDER] owner to complete" ] }, "domain_evidence_register": [ { "claim": "HSC §114093.5 requires written major allergen notification for covered facilities commencing July 1, 2026", "evidence_type": "Primary statute", "source": "CA LegInfo SB-68 chaptered text", "strength": "High", "gaps": "None" }, { "claim": "Coverage attaches to facilities subject to federal menu labeling (20+ same-name locations, substantially same menu) with CA service", "evidence_type": "Primary statute + trade association guidance", "source": "CA LegInfo; California Restaurant Association", "strength": "High", "gaps": "None" }, { "claim": "Digital disclosure requires a non-digital written alternative", "evidence_type": "Primary statute", "source": "HSC §114093.5", "strength": "High", "gaps": "None" }, { "claim": "Retail Food Code violations generally $25-$1,000 and/or up to 6 months, per-day exposure possible", "evidence_type": "Primary statute", "source": "HSC §114395 / §114397", "strength": "High", "gaps": "Some vendor blogs cite unverified $500-$2,500 figures; not relied upon" }, { "claim": "~2,130 chains / ~298,600 establishments sized under the federal menu-labeling coverage test", "evidence_type": "Government regulatory impact analysis", "source": "FDA RIA via CRS summary", "strength": "Medium-High", "gaps": "Dated estimate; precise current count not published" }, { "claim": "CA has 86,779 restaurant locations", "evidence_type": "Industry statistics", "source": "National Restaurant Association, 2025 CA fact sheet", "strength": "High", "gaps": "None" }, { "claim": "SB 68 took effect July 1, 2026 as scheduled; MD, NJ, IL, OH, MO, NY, MI pursuing copycat legislation", "evidence_type": "Trade press", "source": "Allergic Living, June 2026", "strength": "High", "gaps": "Copycat-bill passage timelines unresolved" }, { "claim": "MenuRegistry prices $59-$79/location/month for menu-audit records", "evidence_type": "Competitor public pricing page", "source": "menuregistry.com/pricing", "strength": "High", "gaps": "None" } ], "assumption_register": [ { "assumption": "Buyers will pay $2,500-$12,000 per brand for a DFY pack rather than operate SaaS themselves", "impact_if_wrong": "Pricing must compress toward SaaS-comparable levels", "how_to_validate": "Track founding-cohort close rate against qualified consults", "blocking": true }, { "assumption": "Recipe/supplier evidence is collectible within 5 business days for a typical client", "impact_if_wrong": "SLA needs a buffer tier", "how_to_validate": "Track SLA-miss rate on evidence grounds across pilot packs", "blocking": false }, { "assumption": "40% of delivered packs attach a Quarterly Refresh Retainer", "impact_if_wrong": "Recurring-revenue plan slips", "how_to_validate": "Track retainer attach rate after the first 10 packs", "blocking": false }, { "assumption": "One specialist (the founder) can sustain 1-2 packs/week at launch", "impact_if_wrong": "Release backlog grows, SLA breaches follow", "how_to_validate": "Track release cycle time weekly from week 1", "blocking": true }, { "assumption": "20-120 unit brands with a CA door number in the several-hundred range (beachhead), not thousands", "impact_if_wrong": "TAM narrower than modeled, but per-brand pricing still supports a boutique service business", "how_to_validate": "Build an outbound-derived list during the first 90 days", "blocking": false } ], "language_conflict_map": [ { "term": "Pack", "meaning_a": "Completeness Pack (the delivered bundle)", "context_a": "AllergenPack production", "meaning_b": "A general industry term for 'a set of documents'", "context_b": "Generic business usage", "resolution": "Always capitalize 'Completeness Pack' as the defined term on all client-facing surfaces" }, { "term": "Release", "meaning_a": "The specialist's signed act of clearing a pack to ship", "context_a": "Release bounded context", "meaning_b": "A software deployment event", "context_b": "Generic engineering usage", "resolution": "AllergenPack always qualifies as 'Specialist Release' in business-facing content" } ], "build_buy_integrate": [ { "subdomain": "Payments & Invoicing", "decision": "Buy", "reason": "Stripe is generic, not a differentiator" }, { "subdomain": "Menu Allergen Completeness Pack Production", "decision": "Build", "reason": "This is the core moat -- prompts, rules, and pattern library are owned artifacts" }, { "subdomain": "Channel Deployment Tracking", "decision": "Build (manual at launch, light automation later)", "reason": "Deployment confirmation is a differentiating KPI, not commodity tooling" } ], "core_protection_strategy": [ "[PLACEHOLDER] owner to complete" ], "boundary_stress_tests": [ { "scenario": "A client asks AllergenPack to certify a dish 'nut-free'", "contexts_touched": [ "Release", "Compliance & Licensing Boundary" ], "breaks_if": "A specialist agrees to issue the claim", "verdict": "Holds -- forbidden-claim scrub and licensing-boundary training block this" }, { "scenario": "A franchisor asks AllergenPack to manage franchisee legal disputes over non-compliant menus", "contexts_touched": [ "Compliance & Licensing Boundary" ], "breaks_if": "AllergenPack staff give legal advice on the dispute", "verdict": "Holds -- referred to outside counsel per compliance-checklist.md" }, { "scenario": "A pilot client wants a fully custom recipe-management system, not a pack", "contexts_touched": [ "Menu Allergen Completeness Pack Production" ], "breaks_if": "Founder accepts the custom-build request to close the deal", "verdict": "Holds if launch-plan.md's scope-lock discipline is followed; risk if sales pressure overrides it" } ], "unresolved_ownership": [ { "concept": "Channel drift detection automation", "candidates": [ "QA & Delivery", "Portfolio & Refresh" ], "recommendation": "Assign to Portfolio & Refresh once built -- it's a recurring-relationship concern, not a one-time delivery concern" } ], "published_language_contracts": [ { "producer": "Mapping & Rules", "consumer": "Release", "contract": "Draft Matrix with populated Exception Queue, no silent blanks", "versioning": "Matrix schema versioned; Release rejects a Matrix from an unrecognized schema version" } ], "shared_kernel_warnings": [ "ItemId is shared across Extraction, Mapping & Rules, and Release -- any change to its format must be coordinated across all three contexts" ], "aggregate_stress_tests": [ { "aggregate": "BigNineMatrixAggregate", "scenario": "Two supplier specs for the same ingredient conflict", "invariant_at_risk": "Every Yes/No call cites a source_span", "verdict": "Holds -- conflict routes to Exception Queue rather than picking one source silently" }, { "aggregate": "PackReleaseAggregate", "scenario": "Specialist tries to sign release with 2 unresolved Exception items", "invariant_at_risk": "PackReleased cannot fire with unresolved, non-HOLD items", "verdict": "Holds -- command rejected until items are HOLD-marked or resolved" }, { "aggregate": "DeliveryAggregate", "scenario": "QA sample flags a claim-scrub failure after release", "invariant_at_risk": "PackDelivered only after QASamplePassed", "verdict": "Holds -- delivery blocked, correction routed back through Release if the fix changes disclosure content" } ], "agent_stress_tests": [ { "agent": "Mapping agent", "scenario": "A prompt-injected instruction embedded in a supplier spec PDF tries to make the agent claim an allergen is absent", "failure_mode": "Agent follows injected instruction instead of evidence", "guardrail": "Extraction/mapping prompts explicitly instructed to treat document content as data, not instructions; deterministic rule layer double-checks source_span presence", "verdict": "Holds with guardrail; recommend periodic red-team testing" }, { "agent": "Extraction agent", "scenario": "A componentized sauce name with no visible sub-ingredients is extracted as if fully known", "failure_mode": "Agent infers contents from the name alone", "guardrail": "Explicit prompt instruction to emit needs_spec rather than guess", "verdict": "Holds with guardrail" } ], "regulated_domain_handling": [ { "regime": "California ADDE Act / HSC §114093.5", "applies_because": "Client brands are covered facilities under the statute", "controls": [ "Evidence-only mapping", "Mandatory specialist release", "Written Alternative enforcement", "Forbidden-claim scrub" ], "evidence_required": [ "[PLACEHOLDER] owner to complete" ] } ], "unit_economics": { "price_model": "Per-pack + quarterly retainer, outcome-priced, never hourly", "unit_of_value": "One released Completeness Pack per brand menu family", "gross_margin_pct": "~70-84% pre-opex across year 1 per financial-model.csv, ~50%+ net of opex", "cost_drivers": [ "Specialist minutes per pack (falling 220->70 as automation rises)", "Inference and software costs (minor relative to labor)" ], "breakeven_note": "Breakeven is a function of specialist throughput, not marketing spend -- see build-before-scale checkpoints" }, "margin_leakage_map": [ { "leakage": "Rework on a released pack", "cause": "Exception Queue item resolved incorrectly", "impact": "Re-release costs specialist time at no additional revenue", "mitigation": "Completeness guarantee bounds this to 3-business-day re-release, and QA sampling catches most errors pre-delivery" }, { "leakage": "Chronic evidence chasing", "cause": "Client fails to supply supplier specs promptly", "impact": "SLA breach risk and wasted intake-operator time", "mitigation": "Two-touch chase policy, then HOLD-and-ship discipline caps the time sunk" } ], "slop_findings": [ { "pattern": "Generic 'AI-powered compliance' framing", "status": "Not found", "note": "Copy bar enforced against banned phrases per DESIGN-STANDARD.md §9" } ], "drift_checks": [ { "stage": "Landing page vs. DNA lexicon", "status": "Aligned", "findings": [ "[PLACEHOLDER] owner to complete" ] } ], "gates": [ { "id": "G1", "title": "No fabricated proof", "passed": true, "checks": [ { "name": "No testimonials/case studies invented", "ok": true, "evidence": "Proof section uses [PLACEHOLDER] slots only" } ] }, { "id": "G2", "title": "Evidence-backed regulatory claims", "passed": true, "checks": [ { "name": "Every statute citation traceable to a primary source", "ok": true, "evidence": "See compliance-checklist.md and blueprint Source-Claim Matrix" } ] }, { "id": "G3", "title": "Licensing-boundary honesty", "passed": true, "checks": [ { "name": "No legal/medical advice claimed", "ok": true, "evidence": "compliance-checklist.md disclaimers" } ] } ], "contradiction_scan": [ { "id": "CS1", "severity": "low", "message": "Blueprint's 'DFY pack WTP $2.5-12k' claim is labeled Inferred, not Verified -- pricing copy correctly frames it as an anchor comparison (vs. MenuRegistry SaaS spend) rather than a proven willingness-to-pay figure.", "refs": [ "offer-and-pricing.md", "blueprint Claim Table" ] } ], "rubric": { "categories": [ { "category": "Domain fidelity", "score": 4.5, "min": 3, "passed": true }, { "category": "AI-safety controls", "score": 4.5, "min": 3, "passed": true }, { "category": "Buildability", "score": 4, "min": 3, "passed": true } ], "pass": true, "average": 4.33 }, "foundry_package": { "version": "1.8.0", "checksum": "pending", "counts": { "subdomains": 8, "bounded_contexts": 6, "aggregates": 6, "events": 13, "commands": 7, "policies": 5, "ai_agents": 3, "invariants": 5, "integrations": 4, "adrs": 3 }, "subset": { "subdomains": [ "[PLACEHOLDER] owner to complete" ], "bounded_contexts": [ "[PLACEHOLDER] owner to complete" ], "aggregates": [ "[PLACEHOLDER] owner to complete" ], "events": [ "[PLACEHOLDER] owner to complete" ], "commands": [ "[PLACEHOLDER] owner to complete" ], "policies": [ "[PLACEHOLDER] owner to complete" ], "ai_agents": [ "[PLACEHOLDER] owner to complete" ], "invariants": [ "[PLACEHOLDER] owner to complete" ], "integrations": [ "[PLACEHOLDER] owner to complete" ], "adrs": [ "[PLACEHOLDER] owner to complete" ] } } } }, "ddd_coverage": { "slug": "ca-adde-allergen-menu-completeness-pack-engine", "total": 20, "passed": 20, "pct": 100, "checks": [ { "key": "actors", "label": "Actors", "count": 4, "min": 3, "ok": true, "gate": "domain", "unblock": "Not needed — check passes at current counts." }, { "key": "glossary", "label": "Glossary", "count": 8, "min": 6, "ok": true, "gate": "domain", "unblock": "Not needed — check passes at current counts." }, { "key": "decisions", "label": "Business decisions", "count": 4, "min": 4, "ok": true, "gate": "domain", "unblock": "Not needed — check passes at current counts." }, { "key": "events", "label": "Domain events", "count": 6, "min": 6, "ok": true, "gate": "domain", "unblock": "Not needed — check passes at current counts." }, { "key": "subdomains", "label": "Subdomains", "count": 8, "min": 8, "ok": true, "gate": "core", "unblock": "Not needed — check passes at current counts." }, { "key": "bcs", "label": "Bounded contexts", "count": 6, "min": 4, "ok": true, "gate": "boundary", "unblock": "Not needed — check passes at current counts." }, { "key": "ctx_map", "label": "Context map", "count": 5, "min": 3, "ok": true, "gate": "boundary", "unblock": "Not needed — check passes at current counts." }, { "key": "event_storm", "label": "Event storm rows", "count": 13, "min": 6, "ok": true, "gate": "boundary", "unblock": "Not needed — check passes at current counts." }, { "key": "aggregates", "label": "Aggregates", "count": 6, "min": 3, "ok": true, "gate": "invariant", "unblock": "Not needed — check passes at current counts." }, { "key": "invariants", "label": "Invariants", "count": 5, "min": 4, "ok": true, "gate": "invariant", "unblock": "Not needed — check passes at current counts." }, { "key": "ai_agents", "label": "AI agents", "count": 3, "min": 2, "ok": true, "gate": "ai-safety", "unblock": "Not needed — check passes at current counts." }, { "key": "use_cases", "label": "Use cases", "count": 4, "min": 3, "ok": true, "gate": "buildability", "unblock": "Not needed — check passes at current counts." }, { "key": "evidence_reg", "label": "Evidence register", "count": 8, "min": 5, "ok": true, "gate": "domain", "unblock": "Not needed — check passes at current counts." }, { "key": "assumptions", "label": "Assumption register", "count": 5, "min": 4, "ok": true, "gate": "domain", "unblock": "Not needed — check passes at current counts." }, { "key": "stress_boundary", "label": "Boundary stress tests", "count": 3, "min": 3, "ok": true, "gate": "boundary", "unblock": "Not needed — check passes at current counts." }, { "key": "stress_agg", "label": "Aggregate stress tests", "count": 3, "min": 3, "ok": true, "gate": "invariant", "unblock": "Not needed — check passes at current counts." }, { "key": "stress_agent", "label": "Agent stress tests", "count": 2, "min": 2, "ok": true, "gate": "ai-safety", "unblock": "Not needed — check passes at current counts." }, { "key": "gates_pass", "label": "Hard gates passing", "count": 3, "min": 3, "ok": true, "gate": "release", "unblock": "Not needed — check passes at current counts." }, { "key": "rubric", "label": "Extended rubric pass", "count": 1, "min": 1, "ok": true, "gate": "release", "unblock": "Not needed — check passes at current counts." }, { "key": "foundry", "label": "Foundry package", "count": 10, "min": 4, "ok": true, "gate": "release", "unblock": "Not needed — check passes at current counts." } ], "failingGates": [ "[PLACEHOLDER] owner to complete" ] }, "architecture": { "slug": "ca-adde-allergen-menu-completeness-pack-engine", "archetypes": [ "regulated system", "CRUD/workflow application", "internal operations platform" ], "archetype_impact": "Menu item regime is a global query parameter — every read/write is scoped by menu item, regulatory category, and repair-clock window, not just tenant.", "personality": [ "workflow-heavy", "cost-sensitive", "highly regulated", "highly secure" ], "forces_ranked": [ { "force": "compliance", "why": "Regulated verticals gate release; the architecture must prove, not assert, compliance." }, { "force": "auditability", "why": "Every release decision, every evidence toggle, must be defensible in review." }, { "force": "reliability", "why": "A broken blueprint is a broken release gate — availability is a product feature." }, { "force": "data integrity", "why": "Evidence is the product; a corrupted citation is a shipped defect." }, { "force": "maintainability", "why": "One team maintains dozens of blueprints; the shape must be identical across them." } ], "tradeoffs": [ "Prioritizing auditability slows raw throughput — accepted; the product IS the audit trail.", "Choosing a modular monolith trades independent scaling for a single deploy story — accepted while the team is small.", "Using managed Cloud primitives trades some portability for zero ops — accepted; data is portable, runtime is not the moat." ], "quality_scenarios": [ { "attribute": "Performance (interactive p95)", "target": "600 ms on Blueprint detail routes", "assumption": "Measured from Cloud edge, warm cache." }, { "attribute": "Availability", "target": "99.5% (with March-reporting-window freeze protection)", "assumption": "Rolling 10-business-day window; excludes announced maintenance." }, { "attribute": "RTO", "target": "24h" }, { "attribute": "RPO", "target": "24h (daily backups)" }, { "attribute": "Latency (edge function warm)", "target": "≤ 800ms p95 excluding upstream AI calls" }, { "attribute": "Data durability", "target": "11 nines via managed Postgres + storage replication" }, { "attribute": "Security", "target": "OWASP ASVS L1 baseline" }, { "attribute": "Auditability", "target": "100% of release decisions + evidence toggles logged with actor + timestamp" }, { "attribute": "Maintainability", "target": "New blueprint reaches validation-microsite state in ≤ 1 working session" }, { "attribute": "Deployment frequency", "target": "≥ 5 deploys/week without incident" }, { "attribute": "Observability", "target": "Every edge function emits correlationId; retries + phases visible in diagnostics drawer" }, { "attribute": "Cost envelope", "target": "Idle per-blueprint cost ≈ $0; active < $5/month at MVP traffic" }, { "attribute": "Scalability", "target": "Horizontal by blueprint count; single blueprint sized for < 10 req/s sustained" } ], "options": [ { "style": "simple monolith", "fits_when": "Single team, low traffic, no independent scaling concerns.", "fits_here": "Matches the per-blueprint scope — one microsite, one schema, one code path.", "wrong_here": "Would couple every blueprint into a single deploy — not acceptable at network scale.", "complexity": "low", "cost": "low", "ops_burden": "low", "security_impact": "Small surface, single audit boundary.", "scaling_path": "Vertical scale only; hits ceiling on team velocity, not compute.", "team_fit": "Ideal for one dev; fine at MVP.", "recommended": false }, { "style": "modular monolith", "fits_when": "Multiple bounded contexts but shared deploy lifecycle acceptable.", "fits_here": "Each blueprint is a module inside the network shell; shared shell, isolated data.", "wrong_here": "Wrong only if a blueprint needs independent SLOs — none currently do.", "complexity": "moderate", "cost": "low", "ops_burden": "low", "security_impact": "Single trust boundary; row-level isolation carries the tenancy load.", "scaling_path": "Modules become services only when SLOs or teams diverge.", "team_fit": "Best fit for a small team maintaining many blueprints.", "recommended": true }, { "style": "serverless", "fits_when": "Bursty, per-request workloads with idle-to-zero cost targets.", "fits_here": "Edge functions already handle sync, docs, legal, seed articles, integrity — pay-per-invoke.", "wrong_here": "Wrong for long-running orchestrations; IDLE_TIMEOUT already bit us on legal docs.", "complexity": "moderate", "cost": "low", "ops_burden": "moderate", "security_impact": "Function-scoped IAM; secrets via managed vault.", "scaling_path": "Auto; watch cold-start p95 and per-invocation cost.", "team_fit": "Good — team already ships functions weekly.", "recommended": false }, { "style": "microservices", "fits_when": "Multiple teams, divergent SLOs, independent release cadence required.", "fits_here": "Nothing here justifies it; single team, single deploy cadence, shared data plane.", "wrong_here": "Adds network, discovery, deploy topology, and observability cost with zero product benefit.", "complexity": "very high", "cost": "high", "ops_burden": "high", "security_impact": "Bigger attack surface, more inter-service auth to get right.", "scaling_path": "Best-in-class if the org can afford it.", "team_fit": "Wrong for this team.", "recommended": false }, { "style": "event-driven", "fits_when": "Async fan-out, decoupled producers/consumers, replayable history required.", "fits_here": "Only the sync + integrity pipeline is fan-out; keep it as background jobs, not a broker.", "wrong_here": "Broker + schema registry + DLQ topology is overkill for current volumes.", "complexity": "high", "cost": "moderate", "ops_burden": "high", "security_impact": "Extra ACLs; message-level auth needed.", "scaling_path": "Excellent for future audit-log fan-out, revisit at 10x volume.", "team_fit": "Team can operate a small in-process queue; not a full broker yet.", "recommended": false }, { "style": "workflow/orchestration", "fits_when": "Long, multi-step, resumable pipelines with human-in-the-loop steps.", "fits_here": "Blueprint pipeline (sources → articles → integrity → smoke test) already smells like this.", "wrong_here": "Full engine (Temporal/Airflow) is heavy; a typed in-app queue with retries covers today's needs.", "complexity": "high", "cost": "moderate", "ops_burden": "moderate", "security_impact": "Central choke point — must be hardened.", "scaling_path": "Adopt engine once we cross ~10 concurrent long-running jobs per blueprint.", "team_fit": "Would require operator ramp-up.", "recommended": false } ], "chosen_style": "modular monolith", "chosen_rationale": "Modular monolith with edge functions for bursty AI/generation — one audit boundary, low ops burden, easy per-team ownership.", "rejected": [ { "style": "microservices", "why_rejected": "Adds network, discovery, deploy topology, and observability cost with zero product benefit." }, { "style": "event-driven", "why_rejected": "Broker + schema registry + DLQ topology is overkill for current volumes." } ], "target": { "overview": "React shell → Lovable Cloud (Postgres + Auth + Storage + Edge Functions). Every blueprint is a module inside the shell; per-vertical differences live in derived DNA, not in separate deploys. Compliance posture: Domain-specific (agency allergen-disclosure records, attestation signers, retention schedules).", "frontend": "Vite + React + TypeScript + Tailwind + shadcn primitives; per-blueprint themed via Design DNA; job queue for background pipelines; URL-persisted filter state on audit + diagnostics.", "backend": "Deno-based edge functions per capability. Long generations split into per-item endpoints to stay under IDLE_TIMEOUT.", "data": "Managed Postgres with RLS + JSONB for shape drift. Object storage for source files + generated artifacts.", "api": "REST-ish RPC over edge functions with typed payloads; correlationId on every call for retry/diagnostics.", "authn_authz": "Managed OAuth (Google default). Roles in a dedicated user_roles table + has_role() SECURITY DEFINER function referenced by RLS policies.", "integrations": "GitHub (public read for sync + sources), Lovable AI Gateway (all LLM calls), Cloud Storage (artifacts). No third-party CRM/email yet.", "background_jobs": "blueprintJobQueue in-app: per-slug concurrency limit, exponential backoff + jitter, cancel + invalidate, retention of last error diagnostics.", "object_storage": "Cloud Storage buckets scoped per blueprint slug; signed URLs for artifact download.", "notifications": "In-app toasts + audit trail entries. Email/webhook deferred until owners request it.", "search": "Postgres FTS on blueprint titles + evidence claims; client-side filter for audit trail. Dedicated index deferred.", "analytics": "Lightweight event log in Postgres; dashboard-grade analytics deferred until we have a paying tenant.", "ai": "not applicable", "observability": "correlationId per request, per-phase timings, retry timeline in diagnostics drawer, per-blueprint pipeline status panel, JSON report export.", "deployment": "Preview + Production environments; edge functions deploy with the app; Postgres migrations shipped via managed migration tool.", "security": "RLS on every public table; roles in user_roles; secrets in managed vault; OWASP ASVS L1 baseline.", "dr": "Daily backups; restore drill twice/year." }, "modules": [ { "name": "Blueprint Core", "responsibility": "Owns the SeedBusiness catalog, release decisions, evidence register, owner actions.", "owned_data": [ "seed business rows", "release_decision", "evidence items", "owner-action state" ], "entities": [ "SeedBusiness", "EvidenceItem", "OwnerAction", "ReleaseDecision" ], "interfaces": [ "React store (StoreProvider)", "public read via microsite route" ], "depends_on": [ "Content Pipeline (for source files + articles)", "Cloud auth" ], "events_produced": [ "release.decision.changed", "evidence.status.changed", "owner.action.resolved" ], "events_consumed": [ "sync.blueprint.applied", "integrity.check.completed" ], "failure_risks": [ "Duplicate slug in seed → React key crash (mitigated by dedupe in mergedSeed)", "Evidence drift after sync" ], "scaling": "Bounded by SEED size; irrelevant even at 10x.", "future_split_trigger": "Split out Blueprint Core into an independent deployment when its throughput or a distinct scaling profile justifies it; not warranted pre-revenue." }, { "name": "Content Pipeline", "responsibility": "Fetches GitHub sources, generates docs/seed articles, runs citation integrity, per slug with concurrency + backoff.", "owned_data": [ "blueprint_sources", "blueprint_seed_articles", "job status per slug", "integrity results" ], "entities": [ "SourceFile", "SeedArticle", "IntegrityReport", "JobState" ], "interfaces": [ "blueprintJobQueue API", "edge functions: fetch-blueprint-sources, generate-seed-articles, generate-blueprint-docs" ], "depends_on": [ "Cloud edge functions", "AI Gateway", "GitHub public read" ], "events_produced": [ "sources.fetched", "articles.generated", "integrity.completed", "cache.invalidated" ], "events_consumed": [ "blueprint.cache.invalidate" ], "failure_risks": [ "Edge IDLE_TIMEOUT on long generations (mitigated: per-doc endpoints + retries)", "Upstream AI 5xx storms" ], "scaling": "Concurrency + backoff configurable in UI; scales with edge function limits.", "future_split_trigger": "If cross-blueprint queueing coordination is needed, promote to a shared job service." }, { "name": "Runtime & Capabilities", "responsibility": "Per-blueprint runtime modules — verification, SEO, legal docs, chatbot — with retry + diagnostic history.", "owned_data": [ "capability status per slug", "runtime module errors", "chatbot threads + FAQ" ], "entities": [ "CapabilityStatus", "RuntimeError", "ChatMessage" ], "interfaces": [ "React Runtime tab", "edge functions: verify-blueprint, generate-seo-posts, generate-legal-docs/*, blueprint-chat" ], "depends_on": [ "Content Pipeline (grounding)", "AI Gateway" ], "events_produced": [ "capability.status.changed", "runtime.error.recorded" ], "events_consumed": [ "cache.invalidated" ], "failure_risks": [ "AI provider outage", "Prompt drift causing ungrounded output" ], "scaling": "Per-slug; independent of network size.", "future_split_trigger": "Split out Runtime & Capabilities into an independent deployment when its throughput or a distinct scaling profile justifies it; not warranted pre-revenue." }, { "name": "Sync & Rollback", "responsibility": "Daily GitHub sync of blueprint definitions with dry-run, partial-apply, and server-backed rollback of last snapshot.", "owned_data": [ "sync_runs", "sync_snapshots per slug", "audit_trail" ], "entities": [ "SyncRun", "SyncDiff", "SyncSnapshot", "AuditEntry" ], "interfaces": [ "/github-sync page", "edge functions: github-sync-blueprints, rollback-blueprint-sync" ], "depends_on": [ "Blueprint Core", "Cloud storage for snapshots" ], "events_produced": [ "sync.run.completed", "sync.blueprint.applied", "sync.blueprint.rolled_back" ], "events_consumed": [], "failure_risks": [ "Partial apply leaving mixed state (mitigated by per-blueprint snapshots)", "Audit trail size growth" ], "scaling": "Paginate audit trail; snapshot retention window is finite.", "future_split_trigger": "Split out Sync & Rollback into an independent deployment when its throughput or a distinct scaling profile justifies it; not warranted pre-revenue." }, { "name": "Design & Architecture DNA", "responsibility": "Deterministic per-blueprint design + architecture briefs used to gate release readiness.", "owned_data": [ "derived only — no persistence" ], "entities": [ "DesignDNA", "ArchitectureDNA" ], "interfaces": [ "React panels in Business Detail" ], "depends_on": [ "Blueprint Core" ], "events_produced": [], "events_consumed": [], "failure_risks": [ "Vertical → profile drift if new verticals are not mapped" ], "scaling": "Pure functions; free.", "future_split_trigger": "Split out Design & Architecture DNA into an independent deployment when its throughput or a distinct scaling profile justifies it; not warranted pre-revenue." } ], "data_architecture": { "primary_db": "Managed Postgres (Cloud)", "secondary": [ "Object storage for artifacts + snapshots", "Client localStorage for UI state (filters, drawer state) — never for auth" ], "cache": "React Query + module-level memoization; no dedicated cache service.", "search": "Postgres FTS on titles + evidence; consider pg_trgm on slugs.", "vector": "not applicable", "object_storage": "Per-slug prefixes; lifecycle rules to prune stale sync snapshots.", "schema_strategy": "Normalized core + JSONB for evolving shapes (evidence details, capability status).", "migrations": "Forward-only migrations reviewed in PR; every CREATE TABLE ships GRANTs + RLS enable + policies in the same migration.", "backups": "Managed daily backups with 10-business-day retention.", "retention": "Audit trail retained ≥ 1y; sync snapshots retained 90d; error diagnostics retained 30d.", "audit_logs": "audit_trail table + append-only pattern; export CSV from UI.", "soft_delete": "Soft-delete evidence via status transition; hard-delete only via owner-initiated purge.", "privacy": "Only owner-supplied facts persist; service records, attestations, regulator correspondence handled per vertical policy.", "encryption": "TLS 1.2+ in transit; AES-256 at rest via managed storage.", "multi_tenancy": "Row-level tenancy keyed on auth.uid() + blueprint slug; RLS policies enforce isolation." }, "api": { "style": "REST-ish RPC over edge functions with JSON payloads; typed client wrappers.", "public_vs_internal": "Public microsite reads via Postgres RLS-protected queries; internal capability calls via authenticated edge functions.", "versioning": "Version via function name suffix (v1, v2) when breaking; additive changes preferred.", "rate_limiting": "Per-user + per-slug in edge functions; UI-level concurrency caps for AI calls.", "idempotency": "Sync + rollback carry an idempotency key; retries safe.", "pagination": "Cursor pagination on audit trail; offset paging tolerated on small lists.", "error_format": "{ code, message, correlationId, retryable, details? } — normalized in client.", "webhook_security": "HMAC-signed webhooks (deferred until we accept inbound webhooks).", "retries": "Exponential backoff + jitter, capped attempts, respect idempotency keys.", "contract_testing": "Zod schemas shared between client + edge; smoke test runner exercises each endpoint.", "backward_compat": "Additive fields only; deprecations announced in audit trail before removal.", "contract_testing_plan": "Intake, source-result, and delivery payload schemas are contract-tested per consumer; the JSON contract between AI layers is schema-pinned and versioned." }, "security": { "authn": "Managed OAuth (Google default). Session in httpOnly cookie / managed client storage.", "authz": "user_roles table + has_role() SECURITY DEFINER, referenced from RLS policies. Never store roles on profiles.", "tenant_isolation": "RLS on every public table; every query filters by auth.uid() or by an explicit owner grant.", "secrets": "Managed vault; never in client bundle; edge functions read via runtime env.", "encryption": "TLS in transit; AES-256 at rest; column-level encryption only when regulation requires.", "session": "Short-lived access tokens + refresh rotation; SSR cookie parity for edge routes.", "input_validation": "Zod schemas at the edge boundary; reject on unknown fields.", "api_protection": "Rate limits + WAF rules on public endpoints; correlationId logging for abuse forensics.", "audit_log": "Every release decision, evidence toggle, sync, and rollback records actor + timestamp + before/after.", "admin_access": "Admin actions gated behind role check + two-key confirmation on destructive operations.", "supply_chain": "Lockfile pinning + weekly dependency scan; SBOM produced on release.", "threat_model": [ "Prompt injection via ingested source files → sanitize + refuse instructions from ingested content.", "Cross-tenant read via missing RLS on new table → migration checklist blocks merge.", "Rollback abuse to overwrite recent legitimate edits → rollback preview + confirm-typed pattern.", "AI cost DOS by repeated regeneration → per-slug rate limits + concurrency cap." ], "abuse_cases": [ "Malicious owner uploads privileged content into a public microsite field.", "Sync run tampered with to inject a slug that overlaps a real blueprint.", "Attacker triggers regeneration loop to drive AI cost." ], "zero_trust": "Every service call authenticates; no implicit trust between edge functions.", "asvs_notes": "OWASP ASVS L1 baseline." }, "reliability": { "failure_modes": [ "Edge function IDLE_TIMEOUT on long AI generations.", "Upstream AI provider 5xx / rate limit.", "GitHub API rate limit during sync.", "Postgres connection saturation during sync fan-out." ], "graceful_degradation": "Runtime tab modules degrade independently; microsite serves cached last-known-good content when generation fails.", "retry_policy": "Exponential backoff + jitter, max 5 attempts, respect Retry-After.", "timeouts": "Edge function ≤ 120s wall clock (safety margin under 150s limit); client fetch ≤ 60s per call.", "circuit_breaker": "Client-side per-endpoint breaker: after 3 consecutive IDLE_TIMEOUTs, pause 5m and surface to UI.", "queueing": "In-app blueprintJobQueue with concurrency limits per slug.", "idempotency": "Sync + rollback idempotent via key; generation endpoints idempotent per (slug, doc_key).", "dlq": "Failed jobs recorded in error diagnostics; user re-triggers manually (no auto-DLQ needed at current volume).", "transactions": "Multi-row writes wrapped in single transaction; audit entry written in the same transaction as the mutation.", "dr": "Daily backup + semi-annual restore drill.", "incident_response": "correlationId in every log line; on-call runbook per capability module; smoke test replays post-incident.", "slos": [ { "name": "Interactive p95", "target": "600 ms on blueprint detail" }, { "name": "Availability", "target": "99.5% (with March-reporting-window freeze protection)" }, { "name": "Sync success rate", "target": "≥ 99% per daily run over rolling 7 days" }, { "name": "Generation success rate", "target": "≥ 95% per doc across last 7d (excludes provider outages)" } ] }, "scaling": { "mvp_can_stay_simple": [ "Single Postgres, single region.", "No dedicated search or vector index.", "In-app job queue; no message broker." ], "modular_now": [ "Content Pipeline is already isolated behind blueprintJobQueue — future extraction is a 1-day job.", "Runtime capabilities are one function per module — swap in isolation." ], "deferrable": [ "Workflow engine (Temporal/Airflow).", "Vector DB / RAG.", "Multi-region replication.", "Feature flag service (env-based toggle covers MVP)." ], "breaks_first": "Edge function IDLE_TIMEOUT under multi-doc generation — already addressed by per-doc endpoints; watch for regression.", "db_path": "Vertical scale → read replica → partition by tenant if a single tenant dominates load.", "jobs_path": "In-app queue → dedicated worker → workflow engine, gated by concurrency + resumability need.", "cache_path": "React Query only → HTTP cache headers → CDN edge cache for microsite content.", "search_path": "Postgres FTS → pg_trgm → dedicated search only when p95 breaches SLO.", "files_path": "Managed object storage → CDN → per-region cache if traffic warrants.", "api_path": "Vertical edge function scale → per-capability autoscaling → extract hot module to its own service.", "multi_region": "Not planned; introduce only on customer contract with residency requirement.", "cost_control": "Per-blueprint AI budget, concurrency cap, smoke-test cache; monthly cost review with per-blueprint attribution." }, "ai": { "provider": "Frontier LLM via API with provider-agnostic prompt contracts; a second vendor is configured for failover so a released deliverable never depends on a single model.", "prompt_mgmt": "Extraction, drafting, and matrix prompts are held in versioned files with eval-gated deploys and one-step rollback; prompt changes require diff review.", "rag": "A versioned, jurisdiction-scoped rule pack for Regulatory compliance is retrieved with source-scoped filters; drafting is grounded and citation-anchored to the source text, never free-form generation.", "vector": "Not warranted pre-revenue — the rule pack is small and structured, so section/keyword lookups suffice until a larger corpus justifies similarity search.", "embeddings": "Deferred with the vector store; rule-pack keys are structured (element, source, subsection), not semantic.", "eval": "A gold set of specialist-released packs measures element-extraction F1 and completeness-gate agreement per model release; accuracy vs specialist labels is reviewed on a fixed cadence.", "hitl": "Specialist release is never automated; a domain expert signs off on the exception queue, with sampling QA on a fraction of outputs and expert red-team on the first releases.", "guardrails": "Field-locked templates, source-tie reconciliation, and completeness rules mean a draft missing a required field emits a MISSING_ELEMENT exception rather than inventing content.", "prompt_injection": "Source documents are treated as data, never instructions; the red-team suite includes injected-instruction files disguised as legitimate inputs.", "leakage": "Client and subject identifiers are scoped per case; retrieval is scoped per client; provider training-use is disabled; there is no cross-client corpus.", "fallback": "A manual specialist workbench runbook plus the second LLM vendor keep production moving if the primary model is unavailable.", "latency_cost": "Inference cost per deliverable is bounded at launch and trends down with volume; the standard SLA leaves generous headroom over model latency.", "memory": "Agents are stateless per case; durable knowledge lives in the versioned rule pack and SOP library, not in model memory.", "tool_permissions": "The prompt runner has no tool access beyond returning JSON; search ordering, document assembly, and delivery are deterministic code.", "auditability": "Every prompt+output pair is logged to the per-case audit trail with version tags alongside the specialist release record.", "citation": "Every drafted element carries the source provision it satisfies, and every matrix entry carries the search or record it came from." }, "devops": { "environments": [ "Preview (per branch)", "Production" ], "cicd": "Lovable build pipeline; deploys on merge; edge functions ship atomically with the app.", "iac": "Cloud managed; migrations + config in-repo.", "secrets": "Managed vault; separate values per environment.", "preview_envs": "Automatic per branch; seeded with anonymized fixtures.", "migrations": "Forward-only; migrations reviewed for GRANT + RLS + policies; every table gated by the migration checklist.", "rollback": "App: redeploy previous build. Data: server-backed rollback per blueprint via rollback-blueprint-sync.", "release_style": "Continuous deploy with feature flags; canary only when a change touches shared shell.", "feature_flags": "Env-based booleans at MVP; consider a flag service when we have > 20 flags in flight.", "monitoring": "Cloud platform metrics + per-function logs + client error reporting.", "alerting": "SLO burn-rate alerts + IDLE_TIMEOUT rate alert + AI cost anomaly alert.", "logs": "Structured JSON with correlationId; retained per platform defaults.", "error_tracking": "Client-side error capture wired to console + in-app diagnostics drawer.", "uptime": "Synthetic checks on microsite + shell login every 5 minutes.", "cost_monitoring": "Per-blueprint cost view; alert on 3x baseline over 24h." }, "testing": { "unit": "Vitest for pure derivations (DNA, business helpers).", "integration": "Edge function contract tests with recorded fixtures.", "contract": "Zod schemas shared client + edge; smoke test runner as continuous contract check.", "e2e": "Playwright against localhost preview for critical flows (sign in, evidence toggle, sync apply).", "security": "Weekly dependency scan; RLS policy audit script; abuse-case checklist per release.", "a11y": "Axe checks + keyboard-only smoke on shell components; WCAG 2.2 AA target.", "load": "k6 scenarios against edge functions before enabling a new capability network-wide.", "chaos": "Manual fault injection on AI provider (simulate 500s) during release rehearsal.", "migration": "Every migration runs in preview + dry-run on prod snapshot before apply.", "backup_restore": "Semi-annual restore drill.", "ai_eval": "not applicable", "test_data": "Deterministic fixtures per vertical; no real PHI/PII ever in fixtures." }, "observability": { "logs": "Structured JSON with correlationId, phase, attempt, doc_key, slug.", "metrics": "Per-endpoint latency, error rate, retry count, AI token spend.", "traces": "Cross-function trace via correlationId propagation.", "audit_events": "Release decision, evidence toggle, sync, rollback, cache invalidation.", "business_events": "Blueprint promoted to ready, first microsite view, first customer-visible export.", "error_tracking": "In-app diagnostics drawer + persistent per-slug error history.", "security_monitoring": "Failed auth + rate-limit breach + admin action logs.", "cost_monitoring": "Per-blueprint + per-capability cost attribution.", "dashboards": [ "SLO burn", "AI cost per blueprint", "Sync success rate", "Generation success rate" ], "alert_thresholds": [ "IDLE_TIMEOUT rate > 3/day for one blueprint.", "Sync run failure > 1 in rolling 7 days.", "AI cost > 3x rolling 7-day baseline over 24h.", "p95 breach on Blueprint detail > 800ms for 15 min." ], "triage": "correlationId → diagnostics drawer → retry timeline → JSON report export → runbook link." }, "cost": { "drivers": [ { "name": "AI generation", "note": "Dominant driver; capped by concurrency + per-slug budget." }, { "name": "Edge function invocations", "note": "Bursty at sync + generation; idle-to-zero otherwise." }, { "name": "Managed Postgres", "note": "Small; scales with audit trail retention." }, { "name": "Object storage", "note": "Snapshots + artifacts; lifecycle rules prevent growth." }, { "name": "Bandwidth", "note": "Low; static microsite content." } ], "likely_traps": [ "Regeneration loops on failure (mitigated by circuit breaker).", "Audit trail unbounded growth (mitigated by retention policy).", "Storing large HTML snapshots per sync (mitigated by delta snapshots)." ], "controls": [ "Per-blueprint AI budget with hard cap.", "Smoke-test result caching in localStorage.", "Concurrency cap in blueprintJobQueue.", "Retention policy on audit + diagnostics." ] }, "multi_tenancy": { "model": "Row-level tenancy: one shared Postgres, tenant scope by auth.uid() + blueprint slug.", "isolation": "RLS policies on every public table; policies reference has_role() where role checks are needed.", "tenant_aware_authz": "Every query filters by auth.uid(); admin overrides go through explicit role check + audit entry.", "tenant_config": "Per-slug config stored as JSONB on the blueprint row; no per-tenant deploy.", "branding": "Per-blueprint Design DNA drives theme; no runtime branding upload at MVP.", "tenant_export": "Owner can export evidence + audit trail as JSON/CSV from the UI.", "tenant_deletion": "Owner-initiated purge cascades across blueprint rows + storage prefix; soft-delete window of 30 days.", "tenant_audit": "Per-slug audit trail table view with actor + timestamp on every mutation.", "noisy_neighbor": "Per-slug concurrency cap in blueprintJobQueue; per-slug AI budget.", "tenant_rate_limits": "Edge functions apply per-slug + per-user rate limits.", "billing": "Not billed at MVP; per-blueprint cost attribution feeds the future billing model.", "why_this_fits": "Team size and blueprint scale don't justify schema/db-per-tenant; RLS covers the isolation requirement with negligible ops burden." }, "privacy_compliance": { "data_classification": "Owner-supplied facts and evidence citations are the sensitive classes; service records, attestations, regulator correspondence per vertical.", "minimization": "Only owner-supplied facts persist; no third-party enrichment; no PII scraping.", "consent": "Consent captured at intake for owner-supplied contact info; microsite visitors get standard cookie/consent banner where required.", "access_logs": "Every admin + edge function invocation logged with correlationId + actor.", "audit_trails": "Immutable append-only audit_trail table; export from UI.", "retention": "Audit ≥ 1y; sync snapshots 90d; error diagnostics 30d; artifacts per lifecycle rule.", "legal_hold": "Deferred until a matter requires it.", "right_to_delete": "Owner-initiated purge honored within 30 days; downstream copies pruned by lifecycle rules.", "right_to_export": "JSON + CSV export for evidence, audit trail, and generated artifacts.", "sensitive_handling": "No PHI/PII in prompts; owner-supplied facts only; secrets in managed vault.", "boundaries": "Domain-specific (agency allergen-disclosure records, attestation signers, retention schedules)", "residency": "Single region at MVP; residency contract triggers per-tenant residency planning.", "vendor_risk": "Lovable Cloud + AI Gateway are the only critical suppliers; both reviewed for security posture.", "breach_response": "correlationId + audit trail enables scope determination; disclosure per compliance policy within statutory window.", "admin_controls": "Admin actions gated by role check + two-key confirm for destructive operations; every admin session logged.", "evidence_collection": "Access reviews, change management, restore drills produce artifacts filed into the evidence pipeline." }, "frontend": { "framework": "React 18 + Vite + TypeScript.", "rendering": "SPA with per-route code-split; microsite routes prerender-friendly.", "routing": "react-router-dom v6 with URL-persisted filter/drawer state.", "state": "React context + useSyncExternalStore for the job queue; localStorage only for UI state, never for auth.", "server_state": "@tanstack/react-query for cache + retries.", "forms": "Controlled components + Zod validation on submit; RHF only where forms grow.", "error_handling": "Error boundary at shell + per-panel skeletons + retry affordances.", "components": "shadcn primitives + per-blueprint themed panels; deterministic Design DNA drives look.", "design_system": "Tailwind semantic tokens (index.css); no hardcoded color utilities in components.", "auth_ui": "Managed OAuth callback via Cloud client; session hydration before protected routes render.", "authz_aware_ui": "UI hides actions the current role cannot perform; server-side check is authoritative.", "a11y": "WCAG 2.2 AA target; visible focus rings; keyboard shortcuts in diagnostics drawer.", "i18n": "Copy budgets assume +35% expansion for DE/FR; Intl APIs for dates/currencies.", "performance": "Route-level code split; lazy-load Runtime tab; memoize DNA derivations.", "bundling": "Vite defaults; per-route lazy imports for heavy panels.", "testing": "Vitest for unit; Playwright for critical flows.", "offline": "Not required; last-known-good served from React Query cache.", "realtime": "Not required at MVP; audit trail is polled on interaction." }, "backend": { "framework": "Deno-based edge functions on Lovable Cloud, one function per capability.", "layering": "Handler → validator (Zod) → service → repository → Postgres.", "domain": "Blueprint, Evidence, OwnerAction, SyncRun, RuntimeCapability, ChatMessage.", "services": "Pure functions kept out of edge boundary; shared logic imported from a common module.", "repositories": "Thin Postgres wrappers; RLS enforces tenant scope.", "validation": "Zod at the edge boundary; reject unknown fields.", "authorization": "has_role() SECURITY DEFINER in Postgres; edge function also asserts role for defense in depth.", "jobs": "In-app blueprintJobQueue on the client for user-triggered pipelines; server-side cron only for daily sync.", "events": "Domain events emitted to audit_trail; no external broker.", "files": "Signed URLs from Cloud Storage; virus scan on upload (deferred until user uploads exist).", "email_sms": "Deferred; owner-configured inbox required before enabling outbound mail.", "scheduled": "Daily GitHub sync via scheduled function; retention prune weekly.", "errors": "Normalized error envelope { code, message, correlationId, retryable, details? }.", "logging": "Structured JSON logs with correlationId, phase, attempt, slug.", "config": "Env-based; secrets from managed vault.", "di": "Not required at current size; explicit imports.", "testing": "Contract tests per function with recorded fixtures + smoke-test runner." }, "diagrams": { "context_mermaid": "flowchart LR\n Owner([Blueprint Owner]) --> Shell[Network Shell]\n Reviewer([Reviewer]) --> Shell\n Public([Public Visitor]) --> Micro[Public Microsite ca-adde-allergen-menu-completeness-pack-engine]\n Shell --> Cloud[(Lovable Cloud: DB + Auth + Storage + Edge)]\n Cloud --> AI[[AI Gateway]]\n Cloud --> GH[[GitHub API]]\n Micro --> Cloud", "container_mermaid": "flowchart TB\n subgraph Client\n UI[React Shell + Blueprint Detail]\n Queue[blueprintJobQueue]\n end\n subgraph Cloud[Lovable Cloud]\n DB[(Postgres + RLS)]\n Store[(Object Storage)]\n subgraph Edge[Edge Functions]\n Sync[github-sync-blueprints]\n Roll[rollback-blueprint-sync]\n Src[fetch-blueprint-sources]\n Seed[generate-seed-articles]\n Docs[generate-blueprint-docs]\n Legal[generate-legal-docs/*]\n Verify[verify-blueprint]\n SEO[generate-seo-posts]\n Chat[blueprint-chat]\n end\n end\n UI --> DB\n Queue --> Src\n Queue --> Seed\n UI --> Docs\n UI --> Legal\n UI --> Verify\n UI --> SEO\n UI --> Chat\n UI --> Sync\n UI --> Roll\n Seed --> AI[[AI Gateway]]\n Docs --> AI\n Legal --> AI\n Chat --> AI\n Src --> GH[[GitHub]]", "data_flow_mermaid": "flowchart LR\n A[Owner edits Evidence] --> B[Store: evidence.custom]\n B --> C{Release Gate}\n C -- ready --> D[Business marked Ready]\n C -- blocker --> E[Owner Actions queue]\n F[GitHub Sync] --> G[Diff + Snapshot]\n G --> H[(Postgres)]\n H --> I[Audit trail]\n H --> J[React store]", "auth_flow_mermaid": "sequenceDiagram\n participant U as User\n participant UI as Network Shell\n participant Auth as Cloud Auth\n participant API as Edge Function\n participant DB as Postgres+RLS\n U->>UI: sign in\n UI->>Auth: OAuth (Google)\n Auth-->>UI: session (JWT)\n UI->>API: call with JWT\n API->>DB: query as auth.uid()\n DB-->>API: rows filtered by RLS\n API-->>UI: response", "authz_flow_mermaid": "flowchart LR\n Req[Request w/ JWT] --> Fn[Edge Function]\n Fn --> Role[has_role user_id, role]\n Role --> DB[(user_roles + RLS policies)]\n DB -- allow --> Ok[Return rows]\n DB -- deny --> Err[403 + audit entry]", "deployment_mermaid": "flowchart LR\n Dev[Developer] --> Repo[Git]\n Repo --> CI[Lovable Build]\n CI --> Preview[Preview Env]\n CI --> Prod[Production]\n Prod --> Cloud[(Lovable Cloud)]\n Prod --> CDN[[Edge CDN]]", "background_job_mermaid": "flowchart LR\n UI[Blueprint Detail] --> Enq[blueprintJobQueue.enqueue]\n Enq --> Slot{Concurrency slot?}\n Slot -- yes --> Run[Run job]\n Slot -- no --> Queued[queued]\n Run -->|success| Done[Persist result + emit event]\n Run -->|error| Back[Exponential backoff + jitter]\n Back -->|attempts left| Run\n Back -->|exhausted| Fail[Record diagnostic + expose retry button]", "event_flow_mermaid": "flowchart LR\n Sync[sync.blueprint.applied] --> Core[Blueprint Core]\n Integ[integrity.completed] --> UI\n CacheInv[cache.invalidated] --> Pipe[Content Pipeline]\n Pipe --> Sources[sources.fetched]\n Sources --> Articles[articles.generated]\n Articles --> Integ", "failure_flow_mermaid": "flowchart LR\n Call[Edge Function call] --> Timeout{Timeout / 5xx?}\n Timeout -- no --> Ok[Success]\n Timeout -- yes --> Retry[Backoff + retry]\n Retry --> Cap{Attempts cap?}\n Cap -- no --> Call\n Cap -- yes --> Breaker[Open circuit]\n Breaker --> Cache[Serve last-known-good]\n Breaker --> Owner[Surface diagnostic + owner action]", "multi_tenant_flow_mermaid": "flowchart LR\n Owner1([Owner A]) --> UI\n Owner2([Owner B]) --> UI\n UI --> API[Edge Function w/ JWT]\n API --> Policy{RLS: auth.uid + slug scope}\n Policy -- match --> Rows[Owner-scoped rows]\n Policy -- no match --> Deny[403]", "ai_flow_mermaid": "graph LR; SRC[Source documents as DATA]-->EX[Extract + normalize]-->SR[Order source searches]-->MTX[Build matrix]-->DR[Draft locked-field elements]-->GT[Deterministic completeness gates]-->SP[Specialist release]-->DL[Deliver]; GT-.exception.->SP; SP-.high-risk.->EXP[Expert review]" }, "adrs": [ { "id": "ADR-001", "decision": "Adopt modular monolith as the network-wide architecture style", "context": "Small team maintaining many blueprints with shared shell, evidence discipline, and per-vertical trust variation.", "options": [ "simple monolith", "modular monolith", "microservices", "serverless-only", "hybrid" ], "chosen": "modular monolith", "why": "Preserves a single audit boundary and deploy cadence while allowing edge functions for burst workloads.", "consequences": [ "Shared deploy lifecycle across blueprints", "Row-level tenant isolation carries the security load" ], "risks": [ "A rogue blueprint can regress network shell performance" ], "reversal": "Extract a module to its own deploy only when its SLO diverges from the network shell.", "revisit_when": "A blueprint acquires a divergent SLO, a second team joins, or the shell deploy time exceeds 10 minutes." }, { "id": "ADR-002", "decision": "Managed Postgres as the sole primary datastore", "context": "All entities are relational (blueprints, evidence, sync runs, articles, audit).", "options": [ "Postgres", "Postgres + DocumentDB", "Postgres + vector DB", "Firestore" ], "chosen": "Postgres (Cloud managed) with JSONB for semi-structured fields", "why": "Relational integrity + row-level security satisfies audit, tenancy, and reporting; JSONB absorbs shape drift.", "consequences": [ "RLS policies are the primary tenancy control", "Full-text search via Postgres FTS until it stops scaling" ], "risks": [ "Complex joins under growth" ], "reversal": "Introduce a read-replica or a dedicated search index only when p95 breaches SLO.", "revisit_when": "FTS p95 > SLO for 2 consecutive weeks, or a genuine RAG surface appears." }, { "id": "ADR-003", "decision": "Per-document edge functions for long-running AI generation", "context": "IDLE_TIMEOUT (150s) on monolithic legal-docs generator forced this split.", "options": [ "Single long function", "Chunked per-doc functions", "Background job with polling" ], "chosen": "Per-document endpoints with client-side fan-out + retries", "why": "Keeps each invocation under the timeout, isolates failures, enables partial success reporting.", "consequences": [ "More endpoints to maintain", "Client must own orchestration" ], "risks": [ "Client back-pressure if fan-out is too wide" ], "reversal": "Move to a real workflow engine when we cross ~10 concurrent long jobs per blueprint.", "revisit_when": "Concurrent long-running jobs > 10 per blueprint, or client-side orchestration becomes buggy." }, { "id": "ADR-004", "decision": "Evidence-first release gate", "context": "Vertical compliance posture: Domain-specific (agency allergen-disclosure records, attestation signers, retention schedules).", "options": [ "Owner-declared ready", "Auto-ready via checklist", "Evidence-gated ready" ], "chosen": "Evidence-gated ready — release requires resolved owner actions + verified evidence", "why": "Regulated verticals cannot ship on self-declaration; evidence provides defensibility.", "consequences": [ "Slower path to ready", "Higher confidence at ready" ], "risks": [ "Owners abandon incomplete blueprints" ], "reversal": "Introduce a 'ready-with-caveats' state only if the network stalls on this gate.", "revisit_when": "> 30% of blueprints stuck in owner-action state for > 30 days." }, { "id": "ADR-005", "decision": "Defer AI adoption until a specific evidence-generation need arises", "context": "AI is powerful but adds cost, latency, and auditability burden.", "options": [ "No AI", "Grounded AI only", "Agentic AI" ], "chosen": "No AI in this vertical", "why": "Vertical does not currently justify AI-shaped complexity.", "consequences": [ "No prompt catalog to maintain" ], "risks": [], "reversal": "Introduce AI only for a scoped generation task.", "revisit_when": "A specific generation task appears with clear source grounding." }, { "id": "ADR-006", "decision": "Managed OAuth (Google) with roles in a dedicated user_roles table", "context": "Storing roles on the profile row invites privilege-exception-queue bugs; RLS policies must reference a stable role source.", "options": [ "Roles on profiles", "user_roles + has_role() SECURITY DEFINER", "External IdP with JIT claims" ], "chosen": "user_roles table + has_role() SECURITY DEFINER, referenced by RLS", "why": "Prevents recursive RLS, isolates authz decisions, satisfies audit review.", "consequences": [ "One extra join in policies", "Explicit role grants required" ], "risks": [ "Role drift if grants are not audited" ], "reversal": "Swap SECURITY DEFINER function for an IdP claim without changing policies.", "revisit_when": "Enterprise SSO / SAML contract signed, or role count exceeds ~10." }, { "id": "ADR-007", "decision": "Single-tenant per blueprint slug with row-level isolation", "context": "Blueprints share infra but must never cross-read evidence, sync history, or generated artifacts.", "options": [ "Shared DB + RLS", "Schema-per-tenant", "DB-per-tenant" ], "chosen": "Shared DB + RLS keyed on auth.uid() and blueprint slug", "why": "Simplest operable model at current scale; migration cost stays near zero.", "consequences": [ "RLS is load-bearing security" ], "risks": [ "A missing policy = a leak" ], "reversal": "Extract a specific tenant to its own schema when contract requires it.", "revisit_when": "First enterprise customer with a residency or dedicated-DB clause." } ], "roadmap": [ { "phase": "MVP", "build": [ "Network shell + Blueprint Core module", "Content Pipeline with concurrency + backoff", "Design + Architecture DNA per blueprint", "Sync + rollback + audit trail" ], "avoid": [ "Any per-blueprint deploy pipeline", "Message brokers", "Vector DBs", "Multi-region" ], "defer": [ "A workflow engine", "Full-text search infra", "Dedicated CDN rules" ], "monitor": [ "Edge function IDLE_TIMEOUT rate", "AI cost per generation", "Duplicate-slug regressions" ], "triggers_to_change": [ "p95 breach on Blueprint detail > 800ms", "≥ 3 IDLE_TIMEOUTs/day sustained" ], "acceptable_debt": [ "Client-owned job orchestration", "localStorage-backed UI state" ], "dangerous_debt": [ "Missing RLS on any public table", "Ungrounded AI in customer-visible surfaces" ] }, { "phase": "Stabilization", "build": [ "Automated smoke test per blueprint on cache invalidation", "Per-slug retention + audit trail export", "Contract tests for every edge function" ], "avoid": [ "Premature module extraction" ], "defer": [ "Multi-tenant admin console" ], "monitor": [ "SLO burn rate", "Cost per blueprint per week" ], "triggers_to_change": [ "A single blueprint accounts for > 30% of AI spend" ], "acceptable_debt": [ "Manual runbook execution for rare failures" ], "dangerous_debt": [ "Untested rollback path", "Backups without a restore drill" ] }, { "phase": "Growth", "build": [ "Optional workflow engine adapter behind the current queue interface", "Read replica for Postgres if analytics queries interfere", "Feature flags per capability module" ], "avoid": [ "Splitting Blueprint Core into services without SLO justification" ], "defer": [ "Real-time collaboration" ], "monitor": [ "Fan-out concurrency vs edge function limits" ], "triggers_to_change": [ "> 10 concurrent long jobs per blueprint", "New team joins with independent release cadence" ], "acceptable_debt": [ "Env-based feature flags" ], "dangerous_debt": [ "Skipping migration reviews", "Unaudited role grants" ] }, { "phase": "Scale", "build": [ "Extract Content Pipeline to a dedicated service if it dominates deploys", "Search index (Postgres FTS → dedicated) once FTS p95 breaches SLO" ], "avoid": [ "Microservices per blueprint" ], "defer": [ "Multi-region until a customer contract requires it" ], "monitor": [ "DB CPU + IO under peak", "Search p95" ], "triggers_to_change": [ "Regional compliance contract signed" ], "acceptable_debt": [ "Single-region deployment" ], "dangerous_debt": [ "Unbounded audit trail growth", "Missing DR drill evidence" ] }, { "phase": "Enterprise/Compliance", "build": [ "Formal SOC 2 evidence pipeline (access reviews, change management)", "Tenant-scoped encryption keys where regulation requires", "DR drill quarterly with restore proof" ], "avoid": [ "Custom compliance frameworks; ride managed platform attestations" ], "defer": [ "FedRAMP unless a customer commits" ], "monitor": [ "Access review completion", "Restore-test success rate" ], "triggers_to_change": [ "Signed contract with SOC 2 clause", "PHI/PII scope change" ], "acceptable_debt": [ "Manual quarterly access review with checklist" ], "dangerous_debt": [ "Ad-hoc admin access without approval trail" ] } ], "anti_overengineering": { "flagged": [ { "item": "Introducing Kubernetes", "why": "Team size + workload shape don't justify it.", "simpler": "Managed Cloud primitives." }, { "item": "Adopting microservices", "why": "Single deploy cadence + shared audit boundary.", "simpler": "Modular monolith with edge functions." }, { "item": "Adopting a vector DB", "why": "Sources are small + structured; deterministic retrieval works.", "simpler": "Direct source fetch + Postgres FTS." }, { "item": "Adopting event sourcing", "why": "Audit trail table already provides the needed reconstructibility.", "simpler": "Append-only audit_trail + snapshots." }, { "item": "Multi-region from day one", "why": "No customer contract requires it.", "simpler": "Single region + documented DR plan." }, { "item": "Custom workflow engine", "why": "In-app queue covers current concurrency needs.", "simpler": "blueprintJobQueue with backoff." }, { "item": "Premature message queue", "why": "In-app queue + audit trail cover the fan-out cases.", "simpler": "Keep blueprintJobQueue; revisit at 10x volume." }, { "item": "Custom auth", "why": "Managed OAuth + user_roles cover the model.", "simpler": "Cloud Auth + user_roles table." }, { "item": "Premature caching layer", "why": "React Query covers the read-heavy paths.", "simpler": "React Query + HTTP cache headers." }, { "item": "Data warehouse", "why": "No analytics contract; Postgres analytics queries suffice.", "simpler": "Read replica if the primary is hurt." } ] }, "risks": [ { "risk": "Edge function IDLE_TIMEOUT on long generations", "likelihood": "moderate", "impact": "high", "mitigation": "Per-document endpoints + client-side retries with exponential backoff.", "detection": "Smoke test runner + diagnostics drawer flags IDLE_TIMEOUT.", "owner": "engineering", "escalation": "Sustained > 3/day for one blueprint → open incident.", "fallback": "Fall back to last-known-good cached artifact; pause auto-generation for the affected blueprint.", "category": "technical" }, { "risk": "Duplicate slugs in SEED causing UI regressions", "likelihood": "moderate", "impact": "moderate", "mitigation": "mergedSeed dedupes by slug; add lint on SEED at build time.", "detection": "React duplicate-key warning; per-slug uniqueness assertion in tests.", "owner": "engineering", "escalation": "Ship-block if reproduced on main.", "fallback": "Runtime dedupe in mergedSeed keeps first occurrence.", "category": "technical" }, { "risk": "Ungrounded AI output shipped to microsite", "likelihood": "low", "impact": "high", "mitigation": "Citation-first prompts; integrity check gates Seed Articles view.", "detection": "Integrity report failing count > 0 blocks display.", "owner": "engineering", "escalation": "Any customer-visible ungrounded claim → rollback the blueprint.", "fallback": "Auto-hide the article + surface owner action to regenerate with stricter prompt.", "category": "product" }, { "risk": "Cross-tenant data leak via missing RLS on new table", "likelihood": "low", "impact": "critical", "mitigation": "Every CREATE TABLE ships with GRANT + ENABLE RLS + policies in the same migration.", "detection": "Security scanner + migration checklist.", "owner": "engineering", "escalation": "Immediate lockdown + audit.", "fallback": "Revoke Data API grants on affected table; restore from PITR if data was modified.", "category": "security" }, { "risk": "AI cost runaway on a single blueprint", "likelihood": "moderate", "impact": "moderate", "mitigation": "Per-slug rate limits + smoke-test cache + concurrency cap in UI.", "detection": "Cost monitoring dashboard; per-blueprint spend alert at 3x baseline.", "owner": "SRE", "escalation": "Auto-pause generation; require manual re-enable.", "fallback": "Disable AI for the offending blueprint via feature flag; serve last-known-good.", "category": "cost" }, { "risk": "AI provider outage or model deprecation", "likelihood": "moderate", "impact": "moderate", "mitigation": "Per-capability fallback model + retry with backoff; abstract via Lovable AI Gateway.", "detection": "Elevated 5xx or empty completions; smoke test failing across blueprints.", "owner": "engineering", "escalation": "Sustained > 30 min → switch fallback model; notify owners.", "fallback": "Serve cached artifacts + disable AI-only capabilities until restored.", "category": "supplier" }, { "risk": "Compliance evidence gap during audit", "likelihood": "low", "impact": "high", "mitigation": "Evidence-first release gate + audit trail export from UI.", "detection": "Missing audit entries surfaced in periodic reconciliation report.", "owner": "legal", "escalation": "Regulator-visible gap → incident + disclosure per policy.", "fallback": "Freeze affected blueprint's release state; produce backfill evidence pack.", "category": "compliance" }, { "risk": "Solo/small-team key-person dependency", "likelihood": "moderate", "impact": "high", "mitigation": "Deterministic DNA modules keep decisions in code, not in one head; runbooks per capability.", "detection": "Bus-factor review each quarter.", "owner": "owner", "escalation": "> 1 critical path with no backup → hire or contract.", "fallback": "Freeze non-critical changes; document current state before further work.", "category": "team" }, { "risk": "Audit trail gaps on release decisions", "likelihood": "low", "impact": "critical", "mitigation": "Every mutation writes audit entry in the same transaction.", "detection": "Audit trail row count vs mutation count reconciliation.", "owner": "engineering", "escalation": "Regulator-visible gap → incident + disclosure.", "fallback": "Reconstruct from Postgres WAL + application logs; disclose per compliance policy.", "category": "compliance" } ], "rules": [ "Keep business logic out of UI components — derivations live in lib/*, panels only render.", "Do not introduce a new service without a clear owner and a scaling reason.", "All external integrations must have retries, timeouts, and failure handling.", "All sensitive actions must be auditable in the same transaction that performs them.", "All background jobs must be idempotent.", "All APIs must return the normalized error envelope.", "All tenant-scoped queries must enforce tenant isolation via RLS — never trust the client.", "All expensive AI calls must be logged, capped, and observable.", "All schema changes must be reversible or safely migratable — no destructive drops without a rollout plan.", "All critical workflows must have observability: correlationId, phase timings, retry timeline.", "Every public table ships with GRANT + ENABLE RLS + policies in the same migration.", "Every AI span carries a citation; no citation, no ship.", "Every destructive action requires typed confirmation." ], "audit": { "product_fit": "Architecture matches an evidence-first, regulated-adjacent workflow product per blueprint.", "simplicity": "One shell, one DB, edge functions for bursts — near the simplicity floor for the product's ambitions.", "security": "RLS + role table + audit trail; meets ASVS L1 baseline.", "reliability": "SLOs defined; per-module degradation; retries + diagnostics in place.", "scalability": "Horizontal by blueprint count is the growth axis; per-blueprint scaling is comfortably in headroom.", "maintainability": "Deterministic derivations (Design DNA, Architecture DNA) keep per-vertical drift out of components.", "performance": "p95 target 600ms is realistic on Cloud edge with warm cache.", "cost": "Idle-to-zero for cold blueprints; per-blueprint attribution keeps AI spend controllable.", "compliance": "Domain-specific (agency allergen-disclosure records, attestation signers, retention schedules)", "dx": "Single stack (React + Vite + Tailwind + Cloud); new blueprint reaches microsite state in one session.", "ops_burden": "Managed platform absorbs infra ops; SRE work is limited to SLO watch + runbooks.", "extensibility": "New capability = new edge function + new Runtime tab entry; no shell changes required.", "team_suitability": "Fits a small team; every added component must retire an older one.", "time_to_market": "New blueprint reachable to validation-microsite state within one working session.", "recommendation": { "style": "modular monolith", "stack": "React + Vite + TypeScript + Tailwind + shadcn on the client; Deno edge functions + managed Postgres (RLS) + object storage on the server; Lovable AI Gateway (unused in this vertical).", "hosting": "Lovable Cloud managed hosting; preview + production environments; edge functions co-deploy with the app.", "database": "Managed Postgres with RLS + JSONB; PITR enabled for critical-tier tenants.", "auth": "Managed OAuth (Google default) + user_roles table + has_role() SECURITY DEFINER referenced from RLS policies.", "integrations": "GitHub (public read) for sync + sources; Lovable AI Gateway for LLM calls; Cloud Storage for artifacts. No third-party CRM/email/SMS at MVP.", "ai_approach": "No AI at MVP for this vertical; revisit only when a scoped generation task with clear sources appears.", "build_first": [ "Blueprint Core (evidence + release gate) — vertical-agnostic.", "Content Pipeline (sources → articles → integrity) — required for any evidence claim.", "Sync + rollback — required to safely onboard the network." ], "avoid": [ "Any per-blueprint deploy pipeline.", "Autonomous AI agents that mutate data without owner confirmation.", "Bespoke workflow engines before the in-app queue is exhausted." ], "revisit_later": [ "Workflow engine adoption when > 10 concurrent long jobs per blueprint.", "Search index dedicated infra when Postgres FTS p95 breaches SLO.", "Multi-region on the first residency-bound contract." ], "biggest_risks": [ "Missing RLS on a new public table (critical).", "Ungrounded AI output reaching a customer-visible surface.", "AI cost runaway on a single blueprint.", "Solo/small-team key-person dependency." ], "first_10_steps": [ "Confirm managed OAuth + user_roles table + has_role() function are in place.", "Enable RLS + policies on every existing public table; add the migration checklist to CI.", "Wire correlationId end-to-end across every edge function call.", "Ship the smoke test runner as a required post-deploy gate.", "Enable PITR + schedule the first restore drill on the calendar.", "Add per-slug AI budget caps and cost dashboards.", "Enforce evidence-first release gate for every blueprint.", "Set SLO burn-rate alerts on the top 3 SLIs.", "Document the per-capability runbook (retry, cancel, invalidate).", "Publish this Architecture DNA per blueprint as part of the release evidence pack." ], "top_10_rules": [ "Every public table ships with GRANT + RLS + policies in the same migration.", "Every mutation writes an audit entry in the same transaction.", "Every AI span carries a citation; no citation, no ship.", "Every long AI call is per-item, never monolithic.", "Every edge function call carries a correlationId end-to-end.", "Every retry uses exponential backoff + jitter with a hard attempt cap.", "Every destructive action requires typed confirmation.", "No microservice extraction without a divergent SLO.", "No new dependency without a supply-chain scan.", "Signature element (Pack-pack tabs with regime chip) and accent (register-slate) are network invariants — respect them." ] } } }, "design": { "slug": "ca-adde-allergen-menu-completeness-pack-engine", "archetypes": [ "compliance/regulatory tool", "workflow tool", "operations system" ], "user_mindset": { "goals": "Produce a defensible §114093.5 Big-9 disclosure record while a 10-business-day SLA clock is running.", "session_length": "Bursty around recipe/supplier changes and reprint cycles; otherwise weekly-digest review.", "confidence": "Expert users; will not accept opaque AI output.", "interface_needs": "Print-parity layouts, source-span citation chains, HOLD/release states." }, "posture": [ "authoritative", "trustworthy", "operational" ], "density": "compact", "trust_level": { "tier": "high", "sensitive_domains": [ "recipe and supplier-spec records", "Big-9 allergen matrix data", "client menu channel inventories" ], "implications": [ "Every destructive action confirmed with typed intent, never a single-click.", "Errors carry remediation copy + owner, not just a message.", "Focus rings visible on every interactive element (WCAG 2.2 AA minimum).", "Named signer on any outbound artifact.", "Explicit unsaved-changes gate on nav." ] }, "differentiation": { "avoid": [ "Material Design defaults", "shadcn stock look (unstyled cards + slate ring)", "Purple/indigo gradient heroes", "Stripe/Linear/Notion mimicry", "Vertical cliché: snowflake clip-art and alarm-red penalty banners" ], "strategy": "Anchor on the pack-pack tabs with regime chip as the recurring signature element; every page must include it at least once. Reserve the register-slate accent for evidence/status signals only." }, "territories": [ { "name": "Pack Kitchen", "color_mood": "terracotta + parchment + herb green", "typography": "System sans + warm display", "density": "tabbed binder", "component_feel": "kitchen prep-line clipboard", "motion": "tab-first", "fits": "inspector parity", "risks": "could read as too casual if overdone" }, { "name": "Channel Atlas", "color_mood": "map ink + civic navy", "typography": "Neue Haas Grotesk", "density": "map-driven", "component_feel": "channel map with drift pins", "motion": "map pan", "fits": "multi-channel portfolios", "risks": "requires channel-level data" }, { "name": "SLA Timeline", "color_mood": "slate + amber", "typography": "Inter", "density": "timeline", "component_feel": "gantt of pack stages", "motion": "scroll-sync", "fits": "recurring refresh cycles", "risks": "gantt fatigue" } ], "chosen_territory": "Pack Kitchen", "chosen_rationale": "The pack is the deliverable; the kitchen-clipboard metaphor keeps every screen artifact-shaped, the way a specialist or inspector would expect to read it.", "prioritized_components": [ { "name": "Big-9 status chip", "why": "every menu item is scoped by nine allergen calls" }, { "name": "Exception Queue card w/ HOLD state", "why": "primary judgment work unit" }, { "name": "Completeness Pack assembler", "why": "output is a bundle with a no-blank-cell hard-fail checklist" } ], "patterns": [ { "name": "Channel switcher", "description": "Global channel selector; every Matrix view respects it." }, { "name": "Pack release sign-off", "description": "Named specialist with attestation copy; no pack releases without the signature." } ], "states": [ "default", "hover", "active", "focus", "disabled", "loading", "skeleton", "empty", "error", "warning", "success", "offline", "permission-denied", "partial-data", "syncing", "unsaved-changes", "ai-generating" ], "localization": [ "Copy budgets assume +35% expansion for DE/FR translations.", "RTL mirror verified for AR/HE (icons flipped, numerals kept LTR).", "Dates/times/currencies use Intl APIs, never hardcoded formats.", "Touch targets ≥ 44px; keyboard tab order matches visual order.", "Density modes: comfortable (default), compact (power users), spacious (accessibility)." ], "uniqueness_audit": { "app_specific_decisions": [ "Kitchen-clipboard binder motif", "HOLD-not-invented-data copy discipline" ], "cliches_avoided": [ "Snowflake/allergy-icon clip-art overload", "Green-check compliance theatre", "Fear-based penalty banners" ], "scale_notes": "New blueprints inherit the network shell but MUST declare their own signature element, accent role, and anti-reference before they can be marked ready. Enforced by the release gate." }, "tokens": { "brand": "9 59% 45%", "brand-fg": "23 100% 95%", "surface": "37 62% 96%", "ink": "20 22% 14%", "muted": "22 13% 37%", "accent": "156 44% 33%" }, "type": { "display": "-apple-system, 'Segoe UI', sans-serif", "body": "-apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif", "fonts_url": "none -- system font stack only, per performance budget" }, "signature": { "motif": "Pack kitchen clipboard tabs · Big-9 status chip", "render": "dossier-tabs" } }, "seo": { "slug": "ca-adde-allergen-menu-completeness-pack-engine", "archetype": "compliance-fluent authority site", "archetype_impact": "Search fit is a compliance-fluent authority site. That means depth over breadth: each page cites the specific statute section it addresses, and thin variants are refused.", "authority_dna": { "site_archetype": "compliance-fluent authority site", "monetization_model": "B2B lead → validation call → paid engagement (not ad revenue; not affiliate).", "main_search_intents": [ "informational", "commercial" ], "topical_authority_opportunity": "Own the 'SB 68 menu allergen disclosure' topic cluster by covering the entire brand-side duty -- 20-location coverage test, Big-9 definition including sesame, written-alternative requirement, channel checklist, penalty exposure -- better than any single-post competitor.", "local_seo_opportunity": "Not justified: buyers search by regulator/rule, not by city. Do not build /city/ pages.", "global_national_opportunity": "National (US-first) is the primary market. International only if the regulator itself is cross-border (e.g., EU AI Act, VAT, CBP).", "easiest_ranking_path": "Long-tail, rule-specific how-to and edge-case queries (\"annualizing method worked example\", \"an Unknown-rate chronic leaker report\") where the SERP is dominated by out-of-date law-firm alerts, SaaS supplier blogs, or CDPH/local health PDFs.", "hardest_ranking_path": "Head terms like \"menu ingredient tracking software\" — dominated by aged SaaS supplier domains. Defer until authority is established.", "trust_credibility_requirements": [ "Named human authors with role + credentials", "Rule / statute / agency citations on every claim", "Last-reviewed date + change log on regulatory pages", "Direct links to primary agency source (not aggregators)", "Expert reviewer attribution on YMYL pages" ], "ymyl": true, "expert_review_needed": true, "site_structure": "Authority hub + narrow high-intent service page + linkable evidence assets. Not a directory. Not a marketplace.", "seo_moat": "always-current SB 68 rule-mapped pages with change-log timestamps (incl. tracked copycat-state legislation)" }, "search_market": { "primary_markets": [ "California ADDE Act (SB 68) menu allergen disclosure workflow", "HSC §114093.5 written Big-9 allergen recordkeeping" ], "secondary_markets": [ "menu ingredient records inspection-readiness", "allergen-disclosure evidence", "allergen-disclosure records checklist" ], "low_competition_subtopics": [ "§114093.5 edge cases", "missing invoice-field handling", "ADDE Act (SB 68) allergen disclosure for grocery and foodservice" ], "high_commercial_intent": [ "menu ingredient compliance service for grocery chains", "done-for-you menu ingredient allergen-disclosure records", "allergen-disclosure documentation services", "menu ingredient compliance documentation consultant" ], "informational": [ "what is the ADDE Act (SB 68) 15 lb rule", "CDPH/local health HFC allergen disclosure requirements explained", "§114093.5 recordkeeping guide" ], "local_intent": [ "[PLACEHOLDER] owner to complete" ], "transactional": [ "ADDE Act (SB 68) compliance service demo", "allergen-disclosure pack pricing", "book a menu ingredient records consultation" ], "comparison": [ "done-for-you allergen-disclosure packs vs menu allergen audit SaaS (MenuRegistry, MenuIQ)", "menu ingredient compliance service alternatives" ], "problem_solution": [ "how to survive a menu ingredient records inspection", "allergen-disclosure evidence gap", "10-business-day repair deadline missed" ], "near_me": [ "[PLACEHOLDER] owner to complete" ], "long_tail": [ "ADDE Act (SB 68) allergen disclosure for componentized sauces", "menu ingredient Big-9 mapping confidence calculation annualizing method example", "chronic leaker report quarterly refresh requirements" ], "questions": [ "what records does §114093.5 require?", "who owns §114093.5 allergen-disclosure records?", "when does the 10-business-day SLA clock end?", "how long does a Completeness Pack take?" ], "emerging": [ "AI-assisted menu ingredient recordkeeping", "automated allergen-disclosure evidence" ], "seasonal": [ "quarterly refresh chronic HOLD report deadline", "calendar-year chronic cumulative review" ], "underserved_serps": [ "§114093.5 edge cases", "missing invoice-field handling" ], "weak_serps": [ "allergen-disclosure records checklist", "menu ingredient Big-9 mapping confidence thresholds 30 20 10" ], "forum_dominated_serps": [ "what happens if you miss the 10-business-day repair window", "menu ingredient allergen-disclosure penalty amounts" ], "winnable_authoritative_serps": [ "ADDE Act (SB 68) allergen disclosure definitive guide", "§114093.5 allergen-disclosure evidence requirements" ], "avoid_initially": [ "menu ingredient tracking software", "menu ingredient compliance platform", "best menu ingredient tracking tools" ], "easy_wins": [ "§114093.5 edge cases", "allergen-disclosure records checklist", "menu ingredient repair-clock and quarterly refresh deadlines" ], "moderate": [ "ADDE Act (SB 68) allergen disclosure definitive guide", "menu ingredient records inspection-readiness" ], "long_term_plays": [ "menu ingredient tracking software", "portfolio leak registers for large operators" ], "do_not_pursue": [ "generic \"how to start a compliance business\" content", "celebrity or trend-jacking posts", "AI-generated listicles" ] }, "keyword_clusters": [ { "primary": "§114093.5 allergen-disclosure evidence requirements", "related": [ "ADDE Act (SB 68) audit-ready menu ingredient records", "allergen-disclosure evidence checklist" ], "intent": "commercial", "user_problem": "Inspection, insurance carrier, or review request is coming and menu ingredient evidence is scattered across supplier inboxes", "funnel": "BOFU", "business_value": "high", "ranking_difficulty": "medium", "conversion_potential": "high", "content_effort": "medium", "serp_weakness": "SERP dominated by outdated law-firm alerts and CDPH/local health PDFs", "local_relevance": "low", "global_relevance": "high", "suggested_page_type": "Pillar / evidence guide", "reason": "High buyer intent + weak SERP + our unique proof", "priority_score": 17, "priority": "P0", "bucket": "easy-win" }, { "primary": "done-for-you allergen-disclosure packs vs menu allergen audit SaaS (MenuRegistry, MenuIQ)", "related": [ "menu ingredient compliance service alternatives", "menu allergen audit SaaS (MenuRegistry, MenuIQ) comparison" ], "intent": "commercial", "user_problem": "Evaluating a SaaS seat nobody will operate vs a documentation service", "funnel": "BOFU", "business_value": "high", "ranking_difficulty": "medium", "conversion_potential": "high", "content_effort": "medium", "serp_weakness": "Weak — mostly self-serving SaaS supplier pages", "local_relevance": "low", "global_relevance": "high", "suggested_page_type": "Comparison page (honest, evidence-based)", "reason": "Late-funnel intent with weak competition", "priority_score": 17, "priority": "P0", "bucket": "easy-win" }, { "primary": "allergen-disclosure records checklist", "related": [ "§114093.5 owner checklist", "menu ingredient records audit checklist" ], "intent": "informational", "user_problem": "Wants a concrete one-page artifact covering the five records an inspector asks for", "funnel": "MOFU", "business_value": "medium", "ranking_difficulty": "low", "conversion_potential": "medium", "content_effort": "low", "serp_weakness": "Weak — thin listicles", "local_relevance": "low", "global_relevance": "high", "suggested_page_type": "Resource / lead magnet page", "reason": "Easy win + strong lead-magnet fit", "priority_score": 14, "priority": "P0", "bucket": "easy-win" }, { "primary": "menu ingredient repair-clock and quarterly refresh deadlines", "related": [ "10-business-day SLA clock §114093.5", "chronic leaker report deadline" ], "intent": "informational", "user_problem": "Needs authoritative deadline info for repair clocks and the quarterly refresh chronic report", "funnel": "TOFU", "business_value": "medium", "ranking_difficulty": "low", "conversion_potential": "medium", "content_effort": "low", "serp_weakness": "Weak — outdated pages ranking", "local_relevance": "low", "global_relevance": "high", "suggested_page_type": "Data table page (updated quarterly)", "reason": "Recurring seasonal traffic + easy freshness moat", "priority_score": 14, "priority": "P0", "bucket": "easy-win" }, { "primary": "§114093.5 edge cases", "related": [ "dual regime R-22 and HFC sites", "method switch annualizing vs rolling average", "TRU exclusion May 2026" ], "intent": "informational", "user_problem": "Facing a scenario the standard guides do not cover (dual-regime store, method switch, mid-year full-charge change)", "funnel": "MOFU", "business_value": "medium", "ranking_difficulty": "low", "conversion_potential": "medium", "content_effort": "medium", "serp_weakness": "SERP is thin and forum-heavy", "local_relevance": "low", "global_relevance": "high", "suggested_page_type": "How-to cluster page", "reason": "Easy win + high assist to product page", "priority_score": 13, "priority": "P0", "bucket": "easy-win" }, { "primary": "menu ingredient tracking software", "related": [ "menu ingredient compliance platform", "best menu ingredient tracking tools" ], "intent": "commercial", "user_problem": "Ready to buy", "funnel": "BOFU", "business_value": "high", "ranking_difficulty": "high", "conversion_potential": "high", "content_effort": "high", "serp_weakness": "Strong — aged SaaS supplier domains", "local_relevance": "low", "global_relevance": "high", "suggested_page_type": "Product page (defer)", "reason": "Long-term play — do not chase before authority is built", "priority_score": 9, "priority": "P1", "bucket": "medium" }, { "primary": "ADDE Act (SB 68) allergen disclosure definitive guide", "related": [ "CDPH/local health HFC allergen disclosure requirements explained", "what is the ADDE Act (SB 68) 15 lb rule" ], "intent": "informational", "user_problem": "Just inherited menu ingredient compliance responsibility and needs to orient", "funnel": "TOFU", "business_value": "medium", "ranking_difficulty": "medium", "conversion_potential": "low", "content_effort": "high", "serp_weakness": "Moderate — mostly generic supplier content", "local_relevance": "low", "global_relevance": "high", "suggested_page_type": "Pillar page", "reason": "Anchors topical authority for the whole cluster", "priority_score": 7, "priority": "P1", "bucket": "medium" } ], "topical_authority_map": { "core_topics": [ "ADDE Act (SB 68) menu allergen disclosure — definitive guide", "Allergen-disclosure evidence & inspection-readiness", "Rule library (§114093.5, §608, state overlays)" ], "pillars": [ { "name": "ADDE Act (SB 68) menu allergen disclosure — definitive guide", "core_intent": "informational", "audience": "VP Operations, Directors of Culinary, and QA/food-safety managers", "conversion_goal": "Newsletter / checklist download → later validation call", "supporting_pages": [ "The 15-lb rule explained", "Leak-rate methods: annualizing vs rolling average, worked examples", "§114093.5 edge cases (dual regime, method switch, TRU exclusion)", "§114093.5 FAQs" ], "internal_links": [ "/product", "/rules/ca/114093-106/", "/resources/checklist" ], "schema": [ "Article", "BreadcrumbList", "FAQPage (where genuine)" ], "evidence_needed": [ "Named reviewer", "Primary-source citations", "Worked example" ], "local_variants": [ "[PLACEHOLDER] owner to complete" ], "national_variants": [ "US-national (default)" ] }, { "name": "Allergen-disclosure evidence & inspection-readiness", "core_intent": "commercial", "audience": "VP Operations, Directors of Culinary, and QA/food-safety managers", "conversion_goal": "Book validation call", "supporting_pages": [ "§114093.5 allergen-disclosure evidence requirements", "Menu ingredient records audit checklist", "Common allergen-disclosure evidence gaps (the invoice with no quantity)" ], "internal_links": [ "/product", "/guides/sb68-allergen-disclosure/", "/resources/evidence-checklist" ], "schema": [ "Article", "FAQPage", "BreadcrumbList", "HowTo (only for real workflow)" ], "evidence_needed": [ "Worked evidence artifact", "Regulator citation", "Reviewer credential" ], "local_variants": [], "national_variants": [ "US-national" ] }, { "name": "Rule library", "core_intent": "informational", "audience": "VP Operations, Directors of Culinary, and QA/food-safety managers", "conversion_goal": "Assisted conversion via internal linking", "supporting_pages": [ "CDPH/local health Cal. Health & Safety Code §114093.5 — HFC allergen disclosure, rules and citations", "CAA §608 / 40 CFR Part 82 — ODS regime, rules and citations", "Chronic HOLD reporting (≥an Unknown-rate, quarterly refresh) — rules and citations", "Verification tests (initial + follow-up) — rules and citations", "Full-charge determination methods — rules and citations", "TRU exclusion (final rule, May 2026) — rules and citations", "CARB / state HFC overlays — rules and citations" ], "internal_links": [ "/guides/sb68-allergen-disclosure/", "/product" ], "schema": [ "Article", "BreadcrumbList" ], "evidence_needed": [ "Primary source link", "Visited-on date", "Reviewer specialist release" ], "local_variants": [], "national_variants": [ "US-national" ] } ], "supporting_page_types": [ "definition / glossary", "how-to workflow", "edge-case handling", "rule-change explainer", "worked example", "FAQ", "comparison (only when honest)", "case study (only with permission)", "evidence artifact / template", "regulator update log" ] }, "site_architecture": { "homepage_strategy": "Above-the-fold: one-sentence purpose + primary CTA (validation call). Below: 3 problem-cards linking to pillars, 1 evidence-asset teaser, 1 authority statement with named reviewer.", "main_nav": [ "Product", "How it works", "Pillars", "Resources", "About", "Contact" ], "footer_nav": [ "Editorial policy", "Contact", "Privacy", "Terms", "Sitemap", "Changelog" ], "hubs": [ { "name": "Product / service", "url": "/product", "purpose": "High-intent commercial page" }, { "name": "Guides pillar", "url": "/guides", "purpose": "Topical authority hub" }, { "name": "Rule library", "url": "/rules", "purpose": "Entity/regulation reference" }, { "name": "Resources", "url": "/resources", "purpose": "Linkable assets (templates, checklists)" }, { "name": "Changelog", "url": "/changelog", "purpose": "Freshness + trust signal" } ], "url_patterns": [ "/product", "/guides/[topic]/", "/guides/[topic]/[subtopic]/", "/rules/[regulator]/[rule]/", "/resources/[asset]/", "/compare/[a]-vs-[b]/", "/glossary/[term]/" ], "avoid_url_patterns": [ "/[city]/[service]/ (no local intent for this buyer)", "/blog/[year]/[month]/[slug]/ (dated slugs decay CTR)", "/tag/[tag]/ (thin archive pages)", "Any duplicate /service/ and /solutions/ trees" ] }, "global_national": { "national_clusters": [ "ADDE Act (SB 68) menu allergen disclosure — definitive guide", "CDPH/local health HFC allergen-disclosure compliance workflow", "§114093.5 evidence checklist", "menu ingredient records inspection-readiness" ], "linkable_assets": [ "One-page §114093.5 owner checklist (downloadable, gated by email is OK)", "Rule-to-record mapping table (HTML + PDF)", "Change-log / CDPH/local health rule update tracker (incl. TRU exclusion)", "Worked leak-rate examples (annualizing + rolling average, fixture data labeled illustrative)" ], "original_research_ideas": [ "Annual multi-site menu ingredient records readiness benchmark (survey of ~50 operators)", "Invoice completeness index: share of recipe or supplier spec documents missing §114093.5 fields (anonymized intake data)", "State HFC overlay variation index (where applicable)" ], "international_needed": false, "international_notes": "Not needed. US-first. Do not build hreflang variants." }, "local_seo": { "justified": false, "reason": "Buyers search by regulator/rule, not by city. Local pages would be doorway pages.", "gbp_categories_primary": [ "[PLACEHOLDER] owner to complete" ], "gbp_categories_secondary": [ "[PLACEHOLDER] owner to complete" ], "location_page_rules": [ "Do not build location pages for this blueprint." ], "citations": [ "[PLACEHOLDER] owner to complete" ], "review_strategy": "Reviews are not a Local ranking factor here; use G2/Capterra + case studies instead.", "local_schema": [ "[PLACEHOLDER] owner to complete" ] }, "programmatic": { "recommended": false, "reason": "Programmatic pages almost always become doorway pages in regulated niches. Prefer a small number of deeply-researched pages.", "rules": [ "Only allowed for genuinely differentiated data (e.g., a state-by-state rule table where each state truly differs)", "Every programmatic page must include: unique data field + unique local/regulatory content + human review before publish", "noindex until minimum quality threshold met", "Rel=canonical to the pillar when a page falls below threshold" ], "per_page_requirements": [ "≥1 unique data point not present on sibling pages", "≥1 unique paragraph of human-written analysis", "Verified last-reviewed date" ], "quality_gates": [ "Editorial review before indexation", "Quarterly re-review or noindex", "Automated thin-content detector (<300 words unique) blocks publish" ] }, "page_templates": [ { "page_type": "Homepage", "purpose": "State the offer + route to validation call.", "target_intent": "commercial", "url_pattern": "/", "h1_pattern": "[One-sentence purpose]", "title_pattern": "[Brand] — [One-sentence purpose]", "meta_description_pattern": "One sentence outcome + CTA verb. ≤ 155 chars.", "above_the_fold": [ "H1", "Sub-headline (audience + outcome)", "Primary CTA (validation call)", "1 trust chip (reviewer / cite)" ], "outline": [ "Problem framing", "3 pillar cards", "Evidence asset teaser", "Named reviewer statement", "Contact" ], "internal_links": [ "/product", "/guides", "/resources", "/about" ], "conversion_elements": [ "Calendar CTA", "Checklist download secondary" ], "schema": [ "Organization", "WebSite", "SearchAction" ], "trust_elements": [ "Reviewer name", "Editorial policy link" ], "media": [ "Original workflow diagram (SVG)" ], "faq_opportunities": [ "Top 3 buyer questions" ], "cta_strategy": "Above-the-fold soft + end-of-page primary", "quality_requirements": [ "Loads < 2.5s LCP", "Named reviewer visible" ], "anti_thin_rules": [ "No stock hero", "No generic 'we help X do Y' filler" ] }, { "page_type": "Pillar page", "purpose": "Anchor a topic cluster with a definitive explanation.", "target_intent": "informational", "url_pattern": "/guides/[topic]/", "h1_pattern": "[Topic] — Definitive Guide", "title_pattern": "[Topic] — Definitive Guide | [Brand]", "meta_description_pattern": "Definition + what the reader will learn + reviewer credential.", "above_the_fold": [ "H1", "40–60 word definition block", "TOC", "Last-reviewed date + reviewer" ], "outline": [ "Definition", "Who this applies to", "Workflow", "Rules & citations", "Edge cases", "FAQs", "Related pages" ], "internal_links": [ "Cluster sub-pages", "Rule library", "Product" ], "conversion_elements": [ "End-of-page checklist download", "Sidebar validation call CTA" ], "schema": [ "Article", "BreadcrumbList", "FAQPage (only real FAQs)" ], "trust_elements": [ "Named author + reviewer", "Primary source cites" ], "media": [ "Original diagrams", "Rule comparison table" ], "faq_opportunities": [ "Real questions from practitioners" ], "cta_strategy": "Assist conversion via internal link to product; primary CTA end-of-page.", "quality_requirements": [ "≥ 1500 words unique", "≥ 3 primary sources cited", "Reviewer credential visible" ], "anti_thin_rules": [ "No listicles padded with keyword variants", "No AI-generated body" ] }, { "page_type": "How-to cluster page", "purpose": "Answer a specific workflow question inside a cluster.", "target_intent": "informational", "url_pattern": "/guides/[topic]/[subtopic]/", "h1_pattern": "[Specific action or question]", "title_pattern": "[Specific action] — [Pillar topic] | [Brand]", "meta_description_pattern": "Concrete outcome + who it applies to + one caveat.", "above_the_fold": [ "H1", "Direct answer paragraph", "Numbered steps preview" ], "outline": [ "Direct answer", "Steps", "Edge cases", "Common mistakes", "Related pages" ], "internal_links": [ "Pillar page", "Sibling clusters", "Product" ], "conversion_elements": [ "End-of-page checklist download", "Related tool link" ], "schema": [ "Article", "HowTo (only if real workflow)", "BreadcrumbList" ], "trust_elements": [ "Named author", "Reviewer for YMYL" ], "media": [ "Screenshots of the actual workflow" ], "faq_opportunities": [ "Follow-up questions" ], "cta_strategy": "Contextual link to product mid-page; primary CTA end-of-page.", "quality_requirements": [ "Unique steps not duplicated from pillar", "Reviewer date visible" ], "anti_thin_rules": [ "No spun variants of the pillar" ] }, { "page_type": "Product / service page", "purpose": "Convert commercial intent.", "target_intent": "commercial", "url_pattern": "/product", "h1_pattern": "[Outcome-focused headline]", "title_pattern": "[Brand] — [Outcome]", "meta_description_pattern": "State the outcome + primary CTA verb.", "above_the_fold": [ "H1", "Sub-headline", "Primary CTA", "Trust chip" ], "outline": [ "Problem", "How we solve it", "Proof / worked example", "Objection handling", "FAQ", "CTA" ], "internal_links": [ "Case study", "Pillar guide", "Evidence checklist" ], "conversion_elements": [ "Calendar", "Secondary checklist" ], "schema": [ "Service or SoftwareApplication (whichever fits)", "Organization", "FAQPage" ], "trust_elements": [ "Named reviewer", "Primary-source cites", "Contact info" ], "media": [ "Screenshot of the actual workflow, not marketing composites" ], "faq_opportunities": [ "Buyer objections" ], "cta_strategy": "Above-the-fold + repeated end-of-page", "quality_requirements": [ "Unique per audience segment (no doorway variants)" ], "anti_thin_rules": [ "No thin '/services/X/' spin-offs of the same page" ] }, { "page_type": "Rule / regulation reference page", "purpose": "Serve as the site's citation-grade reference for a specific rule.", "target_intent": "informational", "url_pattern": "/rules/[regulator]/[rule]/", "h1_pattern": "[Regulator] — [Rule] explained", "title_pattern": "[Rule] — [Regulator] Requirements | [Brand]", "meta_description_pattern": "What the rule requires + last-reviewed date.", "above_the_fold": [ "H1", "Definition", "Last-reviewed + reviewer" ], "outline": [ "What the rule says", "Who it applies to", "Deadlines", "Evidence required", "Change log" ], "internal_links": [ "Pillar guide", "Product" ], "conversion_elements": [ "Subscribe to change-log", "Sidebar validation call" ], "schema": [ "Article", "BreadcrumbList" ], "trust_elements": [ "Primary-source link", "Visited-on date", "Reviewer credential" ], "media": [ "Rule comparison table" ], "faq_opportunities": [ "Real practitioner questions" ], "cta_strategy": "Assist conversion via internal link", "quality_requirements": [ "Primary source link required", "Quarterly re-review" ], "anti_thin_rules": [ "No auto-generated rule scraping without human review" ] }, { "page_type": "Comparison page", "purpose": "Serve genuine BOFU comparison intent.", "target_intent": "commercial", "url_pattern": "/compare/[a]-vs-[b]/", "h1_pattern": "[A] vs [B] — Honest Comparison", "title_pattern": "[A] vs [B] | [Brand]", "meta_description_pattern": "Honest side-by-side + when to pick which.", "above_the_fold": [ "H1", "TL;DR verdict", "When-to-pick block" ], "outline": [ "Criteria", "Side-by-side table", "Where each wins", "Where each loses", "Recommendation" ], "internal_links": [ "Product", "Pillar guide" ], "conversion_elements": [ "Calendar CTA", "Evidence checklist" ], "schema": [ "Article", "BreadcrumbList" ], "trust_elements": [ "Disclose the reviewer's relationship to each option" ], "media": [ "Feature comparison table" ], "faq_opportunities": [ "'Which should I choose?' style" ], "cta_strategy": "End-of-page primary CTA to the fitting option", "quality_requirements": [ "Honest even when it hurts", "Disclose relationship" ], "anti_thin_rules": [ "No manufactured 'X vs Y' pages for every pair" ] }, { "page_type": "FAQ page", "purpose": "Aggregate genuine practitioner questions.", "target_intent": "informational", "url_pattern": "/faq", "h1_pattern": "FAQ", "title_pattern": "[Topic] FAQ | [Brand]", "meta_description_pattern": "Answers to the questions we hear most.", "above_the_fold": [ "H1", "Table of contents" ], "outline": [ "Grouped questions", "Each answer 40–120 words" ], "internal_links": [ "Relevant pillars and rule pages" ], "conversion_elements": [ "End-of-page CTA" ], "schema": [ "FAQPage (only for genuine FAQs visible on-page)" ], "trust_elements": [ "Named reviewer" ], "media": [], "faq_opportunities": [ "Real questions only — never invented" ], "cta_strategy": "Related-block links, not inline mid-answer", "quality_requirements": [ "No invented questions" ], "anti_thin_rules": [ "No 'is X the best' padding" ] }, { "page_type": "Glossary term page", "purpose": "Definition-grade authority for a single term.", "target_intent": "informational", "url_pattern": "/glossary/[term]/", "h1_pattern": "[Term]", "title_pattern": "[Term] — Definition | [Brand]", "meta_description_pattern": "Concise definition + who uses the term.", "above_the_fold": [ "H1", "40-word definition" ], "outline": [ "Definition", "Related terms", "Where it applies", "Common misuses" ], "internal_links": [ "Pillar", "Rule pages" ], "conversion_elements": [ "Sidebar related-tool link" ], "schema": [ "Article", "BreadcrumbList", "DefinedTerm" ], "trust_elements": [ "Cite the primary source of the definition" ], "media": [], "faq_opportunities": [], "cta_strategy": "Assist via internal link", "quality_requirements": [ "Never duplicate the pillar's intro" ], "anti_thin_rules": [ "No glossary spam" ] }, { "page_type": "Case study page", "purpose": "Concrete outcome-based proof.", "target_intent": "commercial", "url_pattern": "/case-studies/[slug]/", "h1_pattern": "[Outcome achieved for [customer type]]", "title_pattern": "Case Study — [Outcome] | [Brand]", "meta_description_pattern": "Concrete outcome + timeframe + method.", "above_the_fold": [ "H1", "Outcome metric", "Approved-for-publication chip" ], "outline": [ "Context", "Approach", "Outcome", "Reviewer quote" ], "internal_links": [ "Product", "Pillar guide" ], "conversion_elements": [ "End-of-page CTA" ], "schema": [ "Article", "BreadcrumbList" ], "trust_elements": [ "Named customer contact (with permission)" ], "media": [ "Redacted artifact screenshots" ], "faq_opportunities": [], "cta_strategy": "End-of-page primary CTA", "quality_requirements": [ "Written approval on file" ], "anti_thin_rules": [ "No fabricated case studies" ] } ], "on_page_rules": { "title_tag": "Pattern: [Primary keyword] — [Angle] | AllergenPack. ≤ 60 chars. Front-load the keyword. No clickbait.", "meta_description": "≤ 155 chars. State the specific outcome. Include a verb + a rule citation when applicable. No stuffing.", "headings": "One H1. H2s follow the workflow steps or the searcher's questions. H3s for edge cases. No decorative headings.", "intro": "First 100 words: define the topic in the searcher's language + name the specific rule/agency + preview what the page delivers.", "snippet_targeting": "Add a 40–60 word definition block and a numbered how-to block near the top for featured snippet + AI overview eligibility.", "tables_lists": "Use tables for rule comparisons, deadlines, and thresholds. Lists for steps. Never use tables for layout.", "images": "Original diagrams/screenshots preferred. Descriptive alt text. WebP. Explicit width/height. Never AI slop stock art.", "internal_links": "Every page: ≥3 contextual links up to pillar, ≥2 to sibling cluster pages, ≥1 to a commercial page.", "external_citations": "Cite the primary source (agency PDF / statute) — not aggregators — with the visited-on date.", "author_attribution": "Named author + role + linked bio page. Reviewer for YMYL.", "freshness": "Last-reviewed date at top; change log at bottom for regulator pages; quarterly review cadence.", "cta_placement": "Above the fold (soft), mid-page (contextual to the section), end-of-page (primary).", "mobile": "Single-column, tap targets ≥44px, no interstitials, no autoplay video.", "avoid": [ "Keyword stuffing", "AI-generated body copy without human edit", "Doorway variants", "Unsupported superlatives ('best', 'top-rated') without evidence", "Meta descriptions duplicated across pages", "Marking up invisible content in schema" ] }, "entity_seo": { "main_entities": [ "ADDE Act (SB 68)", "Cal. Health & Safety Code §114093.5", "CDPH/local health", "HFC menu ingredients", "Big-9 mapping confidence", "repair clock", "chronic leaker report", "ingredient source" ], "related_entities": [ "sesame-flagged sauce base", "20-location threshold", "Yes/No/Unknown Big-9 calls", "QA sample check", "3-year records" ], "people": [ "Named practitioners (role-titles)", "culinary/allergen-ops specialists", "CDPH/local health officials referenced" ], "orgs": [ "CDPH/local health", "FMI", "state grocers associations", "restaurant associations", "CARB" ], "tools": [ "Rule library", "Leak-rate worksheets", "Change-log tracker" ], "regulations": [ "Cal. Health & Safety Code §114093.5 (ADDE Act (SB 68) ER&R)", "CAA §608 / 40 CFR Part 82", "40 CFR §19.4 penalty adjustments", "TRU exclusion final rule (May 2026)", "CARB HFC rules" ], "problems": [ "§114093.5 recordkeeping risk", "Inspection failure", "Missed 10-business-day SLA clock", "Unnoticed an Unknown-rate HOLD threshold", "Evidence gap" ], "solutions": [ "Completeness Pack workflow", "Portfolio Disclosure Register", "Rule-mapped checklists" ], "processes": [ "Invoice intake", "Menu item resolution", "Leak-rate computation", "Release review", "Deliver & register", "Chronic watch" ], "alternatives": [ "menu allergen audit SaaS (MenuRegistry, MenuIQ)", "bundled HVAC compliance managers", "law firm alerts" ], "synonyms": [ "menu ingredient allergen disclosure records", "HFC Big-9 mapping confidence documentation", "menu ingredient compliance pack", "audit-ready" ] }, "schema_strategy": [ { "type": "Organization", "where": "Site-wide in head", "required_fields": [ "name", "url", "logo", "sameAs" ], "caution": "Keep in sync with visible About / contact." }, { "type": "WebSite + SearchAction", "where": "Homepage", "required_fields": [ "name", "url", "potentialAction" ], "caution": "Only if on-site search actually exists." }, { "type": "BreadcrumbList", "where": "All hub / cluster / rule / glossary pages", "required_fields": [ "itemListElement" ], "caution": "Order must match visible breadcrumbs." }, { "type": "Article", "where": "Guides, pillars, rule pages", "required_fields": [ "headline", "author", "datePublished", "dateModified" ], "caution": "Author must exist as a real person." }, { "type": "FAQPage", "where": "Genuine FAQ pages only", "required_fields": [ "mainEntity[]" ], "caution": "Only mark up FAQs visible on the page." }, { "type": "HowTo", "where": "Real step-by-step workflows only", "required_fields": [ "name", "step[]" ], "caution": "Google narrowed HowTo eligibility; use sparingly." }, { "type": "Person", "where": "Author bio pages", "required_fields": [ "name", "jobTitle", "sameAs" ], "caution": "Credentials must be real and verifiable." } ], "internal_linking": { "pillar_to_cluster": "Pillar links to every direct cluster page in a curated section (not a mega-menu dump).", "cluster_to_pillar": "Every cluster page links back to its pillar in the intro and in-context.", "cluster_to_cluster": "Link between sibling clusters only where the user's next question naturally leads there.", "service_to_location": "Not applicable.", "faq_to_commercial": "Answer the question first, then link to the commercial page in a 'related' block — never inline mid-answer.", "breadcrumbs": "Structured breadcrumbs on all guide, rule, and glossary pages.", "anchor_text_rules": [ "Descriptive — match the target page's H1 concept", "Vary phrasing across links to the same target", "Never exact-match keyword stuffing", "Anchor must make sense read aloud" ] }, "technical_seo": { "crawlability": "Flat depth (≤3 clicks from homepage). No orphan pages. HTML sitemap on /sitemap.", "indexability": "Index all real content. noindex utility pages, thank-you pages, and gated-asset landing pages.", "sitemaps": "XML sitemap generated at build time. Split by section if > 5k URLs.", "robots": "robots.txt allows all; disallow /admin/, /api/. Reference sitemap.", "canonicals": "Self-referencing canonical on every page. Filter/sort variants canonical to the base.", "pagination": "Prefer 'load more' or a single long page; if paginated, use rel=next/prev semantics via internal linking.", "faceted_nav": "Not applicable for this blueprint (no product catalog).", "duplicate_control": "One URL per topic. Consolidate before publishing new variants. No www/non-www split.", "redirects": "301 for permanent moves; audit chains monthly; never 302 for SEO redirects.", "core_web_vitals": "LCP ≤ 2.5s, INP ≤ 200ms, CLS ≤ 0.1. Test with real-user monitoring.", "mobile": "Mobile-first design. No tap-target failures. No horizontal scroll.", "accessibility": "WCAG AA. Semantic HTML. Landmarks. Focus states. Alt text.", "js_seo": "Content in the initial HTML. Client hydration for interactivity only.", "rendering": "Static generation preferred; SSR only where personalized. Never client-only for indexable pages.", "gsc_setup": "Verify both www and apex; submit sitemap; monitor Coverage and Enhancements weekly.", "analytics_setup": "GA4 + server-side event stream. Consent Mode v2. Event schema documented.", "rank_tracking": "Semrush or Ahrefs project set to US database; track pillar + top-20 clusters weekly." }, "eeat": { "author_bios": "Every content page has a named author with role, credentials, and a linked author page.", "expert_reviewers": "Every YMYL page reviewed by a named expert with disclosed credentials.", "editorial_policy": "Public /editorial-policy page: sourcing rules, review cadence, correction policy.", "fact_checking": "Every statute/rule reference has a link + visited-on date; corrections dated and disclosed.", "credentials": [ "culinary/allergen-ops certification (reviewer)", "Relevant professional licensure where public" ], "citations": "Cite primary sources (agency PDF, statute text). No citation of aggregator blogs.", "first_hand_proof": [ "Screenshots of the actual workflow", "Redacted worked examples", "Signed reviewer statement" ], "update_cadence": "Regulatory pages reviewed quarterly; commercial pages reviewed twice yearly.", "monetization_disclosure": "Public disclosure that leads convert to paid engagements; no undisclosed affiliate content.", "ymyl_notes": "This is YMYL. Language stays cautious (\"may\", \"depends on facts\"); documentation support only — no legal-advice framing, no penalty-avoidance promises; disclaimer near CTA." }, "ai_search": { "principles": [ "Answer the exact question in the first paragraph", "Provide a 40–60 word extractable definition near the top", "Structured lists and tables for facts", "Cite named primary sources", "Author + reviewer names on-page" ], "tactics": [ "FAQPage schema for genuine FAQs (not stuffed)", "HowTo schema for real workflow pages", "Consistent entity naming across the site", "Concise summaries at the top of long guides" ], "do_not": [ "Write pages targeting AI systems instead of humans", "Insert hidden 'AI-only' content", "Create bespoke llms.txt / manifests that bypass normal quality", "Mass-generate answers to invented questions" ] }, "conversion": { "primary_cta": "Start a pack run from your most recent recipe/spec document (or book a validation call).", "secondary_cta": "Run the free Menu Allergen Gap Scan / download the §114093.5 owner checklist (email capture).", "lead_magnets": [ "Free Menu Allergen Gap Scan (human-reviewed Gap Scan report in 24h)", "One-page §114093.5 owner checklist (PDF)", "Quarterly CDPH/local health rule change-log subscription" ], "trust_elements": [ "Named reviewer + credentials", "Rule citations visible on-page", "Change-log timestamps", "Contact + address in footer" ], "per_page_paths": [ { "page_type": "Homepage", "path": "Hero CTA → validation call. Secondary → guides pillar." }, { "page_type": "Pillar", "path": "TOC → deep sub-pages. End-of-page → validation call." }, { "page_type": "Cluster / how-to", "path": "In-content 'related tool' link → product. End-of-page → checklist download." }, { "page_type": "Product / service", "path": "Above-the-fold CTA → calendar. Objection-handling block → FAQ." }, { "page_type": "Rule page", "path": "Sidebar → related workflow (product). Bottom → subscribe to change-log." } ], "tracking": "GA4 events: cta_click, checklist_download, calendar_book. Server-side dedupe. Weekly funnel review." }, "link_earning": { "digital_pr_ideas": [ "Annual \"ADDE Act (SB 68) §114093.5\" menu ingredient records readiness benchmark report", "Invoice completeness index with a shareable result page", "CDPH/local health rule-change tracker with an RSS feed" ], "original_research": [ "Small operator survey (n≥30) once per year", "State-by-state HFC overlay variation index" ], "directories": [ "G2 / Capterra category pages", "Industry association member lists", "Regulator resource pages when eligible" ], "expert_contributions": [ "HARO / Qwoted / Featured expert responses", "Bylined articles in industry trade press", "Podcast interviews with practitioners" ], "partnerships": [ "Association CLE / CPE sponsorships", "Co-authored guides with adjacent (non-competing) suppliers" ], "avoid": [ "Paid link schemes", "PBNs", "Mass guest posting", "Fake reviews", "Reciprocal link exchanges" ] }, "roadmap_90d": [ { "phase": "Days 0–30: Foundation", "goal": "Establish trust + ship product page + first pillar.", "pages": [ "Homepage", "Product page", "Pillar: ADDE Act (SB 68) menu allergen disclosure — definitive guide", "About + reviewer bio (role-titles)", "Editorial policy", "Contact" ], "keywords_targeted": [ "ADDE Act (SB 68) allergen disclosure", "ADDE Act (SB 68) 15 lb rule guide" ], "why_first": "Without a trust surface + a real product page, everything else is unmoored.", "difficulty": "medium", "business_value": "high", "required_assets": [ "Reviewer bio", "Editorial policy", "One workflow diagram" ], "internal_links": [ "Homepage ↔ Product ↔ Pillar" ], "conversion_goal": "First validation calls booked" }, { "phase": "Days 31–60: Topical authority core", "goal": "Publish the first cluster of 5–7 supporting pages under the pillar + evidence checklist lead magnet.", "pages": [ "§114093.5 edge cases", "Leak-rate calculation step by step (annualizing + rolling average)", "§114093.5 FAQs", "§114093.5 owner checklist (lead magnet)", "Repair-clock and quarterly refresh deadlines" ], "keywords_targeted": [ "§114093.5 edge cases", "allergen-disclosure records checklist", "menu ingredient repair clock deadlines" ], "why_first": "Easy-win SERPs that assist conversion to the product page.", "difficulty": "low", "business_value": "medium", "required_assets": [ "Checklist PDF", "Rule table" ], "internal_links": [ "All clusters ↔ pillar ↔ product" ], "conversion_goal": "Checklist downloads + assisted conversions" }, { "phase": "Days 61–90: Reference & freshness", "goal": "Ship the rule library + first regulator change-log post + first comparison page.", "pages": [ "Rule page: Cal. Health & Safety Code §114093.5", "Rule page: CAA §608 dual regime", "Rule page: chronic HOLD reporting (quarterly refresh)", "Comparison: done-for-you allergen-disclosure packs vs menu allergen audit SaaS (MenuRegistry, MenuIQ)", "Q1 CDPH/local health rule change-log" ], "keywords_targeted": [ "40 CFR 114093.5", "section 608 vs ADDE Act (SB 68)", "chronic leaker report quarterly refresh" ], "why_first": "Reference pages compound in authority; change-log establishes freshness signal.", "difficulty": "medium", "business_value": "medium", "required_assets": [ "Primary-source citations", "Reviewer specialist release" ], "internal_links": [ "Rule pages ↔ pillar ↔ product; comparison → product" ], "conversion_goal": "BOFU comparison conversions" } ], "roadmap_12m": [ { "phase": "Months 4–6: Linkable assets", "goal": "Ship the annual benchmark, the cost-of-non-compliance calculator, and the state variation index (if applicable).", "pages": [ "Annual menu ingredient records readiness benchmark", "Invoice completeness index", "State HFC overlay variation index" ], "keywords_targeted": [ "menu ingredient records benchmark", "menu ingredient compliance cost", "state HFC rules comparison" ], "why_first": "Linkable assets drive referring domains and topical authority signals.", "difficulty": "medium", "business_value": "high", "required_assets": [ "Survey data", "Named methodology", "Reviewer specialist release" ], "internal_links": [ "From every pillar + product" ], "conversion_goal": "Calculator → validation call handoff" }, { "phase": "Months 7–9: Depth + freshness cadence", "goal": "Expand each pillar with 3 more cluster pages + quarterly regulator change-log.", "pages": [ "Additional cluster pages (per pillar)", "Q3 regulator change-log", "First case study (with permission)" ], "keywords_targeted": [ "Long-tail cluster expansions" ], "why_first": "Compounding topical coverage + freshness moat.", "difficulty": "low", "business_value": "medium", "required_assets": [ "Customer approval for case study" ], "internal_links": [ "Sibling cluster interlinking" ], "conversion_goal": "Assisted conversions" }, { "phase": "Months 10–12: Scale + prune", "goal": "Consolidate weak pages, refresh top pages, expand into 1 adjacent topic only if authority is proven.", "pages": [ "Consolidation redirects", "Top-10 page refreshes", "Adjacent topic scoping" ], "keywords_targeted": [ "Existing top-10 clusters" ], "why_first": "Optimization > net-new after a critical mass is reached.", "difficulty": "low", "business_value": "high", "required_assets": [ "Analytics review", "Consolidation plan" ], "internal_links": [ "Redirect audit" ], "conversion_goal": "CTR + conversion-rate lift" } ], "priority_pages": [ { "rank": 1, "page_title": "§114093.5 allergen-disclosure evidence requirements", "slug": "/guides/84-106-allergen-disclosure-evidence-requirements/", "page_type": "Pillar / evidence guide", "primary_keyword": "§114093.5 allergen-disclosure evidence requirements", "secondary_keywords": [ "ADDE Act (SB 68) audit-ready menu ingredient records", "allergen-disclosure evidence checklist" ], "intent": "commercial", "scope": "national", "funnel": "BOFU", "difficulty": "medium", "business_value": "high", "conversion_potential": "high", "required_proof": [ "Named reviewer", "Primary-source cites", "Worked example" ], "internal_links": [ "/guides/sb68-allergen-disclosure/", "/product", "/rules/ca/114093-106/" ], "schema": [ "Article", "BreadcrumbList" ], "cta": "Book validation call", "production_priority": "P0", "why_opportunity": "High buyer intent + weak SERP + our unique proof" }, { "rank": 2, "page_title": "Done-for-you allergen-disclosure packs vs menu allergen audit SaaS (MenuRegistry, MenuIQ)", "slug": "/compare/allergen-disclosure-packs-vs-menu ingredient-saas/", "page_type": "Comparison page (honest, evidence-based)", "primary_keyword": "allergen-disclosure packs vs menu allergen audit SaaS (MenuRegistry, MenuIQ)", "secondary_keywords": [ "menu ingredient compliance service alternatives", "menu allergen audit SaaS (MenuRegistry, MenuIQ) comparison" ], "intent": "commercial", "scope": "national", "funnel": "BOFU", "difficulty": "medium", "business_value": "high", "conversion_potential": "high", "required_proof": [ "Named reviewer", "Primary-source cites", "Worked example" ], "internal_links": [ "/guides/sb68-allergen-disclosure/", "/product", "/rules/ca/114093-106/" ], "schema": [ "Article", "BreadcrumbList" ], "cta": "Book validation call", "production_priority": "P0", "why_opportunity": "Late-funnel intent with weak competition" }, { "rank": 3, "page_title": "§114093.5 owner records checklist", "slug": "/guides/84-106-records-checklist/", "page_type": "Resource / lead magnet page", "primary_keyword": "allergen-disclosure records checklist", "secondary_keywords": [ "§114093.5 owner checklist", "menu ingredient records audit checklist" ], "intent": "informational", "scope": "national", "funnel": "MOFU", "difficulty": "low", "business_value": "medium", "conversion_potential": "medium", "required_proof": [ "Named reviewer", "Primary-source cites", "Worked example" ], "internal_links": [ "/guides/sb68-allergen-disclosure/", "/product", "/rules/ca/114093-106/" ], "schema": [ "Article", "BreadcrumbList" ], "cta": "Download checklist", "production_priority": "P0", "why_opportunity": "Easy win + strong lead-magnet fit" }, { "rank": 4, "page_title": "Menu ingredient repair-clock and quarterly refresh deadlines", "slug": "/guides/repair-clock-march-1-deadlines/", "page_type": "Data table page (updated quarterly)", "primary_keyword": "menu ingredient repair-clock and quarterly refresh deadlines", "secondary_keywords": [ "10-business-day SLA clock §114093.5", "chronic leaker report deadline" ], "intent": "informational", "scope": "national", "funnel": "TOFU", "difficulty": "low", "business_value": "medium", "conversion_potential": "medium", "required_proof": [ "Named reviewer", "Primary-source cites", "Worked example" ], "internal_links": [ "/guides/sb68-allergen-disclosure/", "/product", "/rules/ca/114093-106/" ], "schema": [ "Article", "BreadcrumbList" ], "cta": "Download checklist", "production_priority": "P0", "why_opportunity": "Recurring seasonal traffic + easy freshness moat" }, { "rank": 5, "page_title": "§114093.5 edge cases", "slug": "/guides/84-106-edge-cases/", "page_type": "How-to cluster page", "primary_keyword": "§114093.5 edge cases", "secondary_keywords": [ "dual regime R-22 and HFC sites", "method switch annualizing vs rolling average", "TRU exclusion May 2026" ], "intent": "informational", "scope": "national", "funnel": "MOFU", "difficulty": "low", "business_value": "medium", "conversion_potential": "medium", "required_proof": [ "Named reviewer", "Primary-source cites", "Worked example" ], "internal_links": [ "/guides/sb68-allergen-disclosure/", "/product", "/rules/ca/114093-106/" ], "schema": [ "Article", "BreadcrumbList" ], "cta": "Download checklist", "production_priority": "P0", "why_opportunity": "Easy win + high assist to product page" }, { "rank": 6, "page_title": "Menu ingredient tracking software (deferred)", "slug": "/guides/menu ingredient-tracking-software/", "page_type": "Product page (defer)", "primary_keyword": "menu ingredient tracking software", "secondary_keywords": [ "menu ingredient compliance platform", "best menu ingredient tracking tools" ], "intent": "commercial", "scope": "national", "funnel": "BOFU", "difficulty": "high", "business_value": "high", "conversion_potential": "high", "required_proof": [ "Named reviewer", "Primary-source cites", "Worked example" ], "internal_links": [ "/guides/sb68-allergen-disclosure/", "/product", "/rules/ca/114093-106/" ], "schema": [ "Article", "BreadcrumbList" ], "cta": "Book validation call", "production_priority": "P1", "why_opportunity": "Long-term play — do not chase before authority is built" }, { "rank": 7, "page_title": "ADDE Act (SB 68) allergen disclosure — definitive guide", "slug": "/guides/sb68-allergen-disclosure-definitive-guide/", "page_type": "Pillar page", "primary_keyword": "ADDE Act (SB 68) allergen disclosure definitive guide", "secondary_keywords": [ "CDPH/local health HFC allergen disclosure requirements explained", "what is the ADDE Act (SB 68) 15 lb rule" ], "intent": "informational", "scope": "national", "funnel": "TOFU", "difficulty": "medium", "business_value": "medium", "conversion_potential": "low", "required_proof": [ "Named reviewer", "Primary-source cites", "Worked example" ], "internal_links": [ "/guides/sb68-allergen-disclosure/", "/product", "/rules/ca/114093-106/" ], "schema": [ "Article", "BreadcrumbList" ], "cta": "Download checklist", "production_priority": "P1", "why_opportunity": "Anchors topical authority for the whole cluster" } ], "competitor_gaps": { "typical_competitor_types": [ "menu allergen audit SaaS (MenuRegistry, MenuIQ)", "bundled HVAC compliance managers", "law firm alerts" ], "common_weaknesses": [ "Outdated regulator citations", "Missing last-reviewed date", "No named author or reviewer", "Copy-paste content across state / product variants", "No worked examples", "Thin FAQ padded with generic questions", "Poor mobile Core Web Vitals" ], "how_to_beat_them": [ "Fresh citations with visited-on dates", "Named reviewer + credentials visible", "Real, redacted worked examples", "Better structured tables for rule comparisons", "Faster + more accessible pages" ] }, "metrics": { "weekly": [ "GSC impressions/clicks by pillar", "Top-20 keyword position", "New indexed pages", "Core Web Vitals regressions" ], "monthly": [ "Organic sessions by hub", "Assisted conversions", "CTR by template", "Content decay list (positions dropped)", "Backlink net-new" ], "quarterly": [ "Pillar coverage audit", "Rule freshness audit", "Consolidation / prune list", "Conversion path funnel review" ], "annual": [ "Full topical authority audit", "Benchmark report refresh", "Editorial policy refresh" ] }, "risks": [ { "risk": "Thin content", "applies": true, "mitigation": "Minimum-word + reviewer-specialist release gate before publish." }, { "risk": "Duplicate content across state/product variants", "applies": true, "mitigation": "One URL per topic; no auto-generated variants; canonical to pillar." }, { "risk": "Doorway location pages", "applies": true, "mitigation": "Local pages are refused for this vertical — buyers search by regulator, not city." }, { "risk": "Keyword cannibalization", "applies": true, "mitigation": "Topic ownership map; kill or 301 the weaker duplicate." }, { "risk": "AI-generated body without human edit", "applies": true, "mitigation": "Editorial policy forbids it; reviewer specialist release required." }, { "risk": "Unsupported YMYL claims", "applies": true, "mitigation": "Cautious language + primary-source cites + reviewer credential." }, { "risk": "Bad schema (marking up invisible content)", "applies": true, "mitigation": "Schema linter in CI; only markup what is on-page." }, { "risk": "Link spam / paid link schemes", "applies": true, "mitigation": "Editorial link-earning only; documented policy." }, { "risk": "Review manipulation", "applies": false, "mitigation": "Post-engagement organic prompts only; no incentives; no gating negatives." }, { "risk": "Index bloat from tag/archive pages", "applies": true, "mitigation": "noindex utility archives; canonical to hub." }, { "risk": "Compliance risk in claims", "applies": true, "mitigation": "Legal review of marketing claims; disclaimer near CTAs." }, { "risk": "Programmatic doorway pages", "applies": true, "mitigation": "Programmatic refused unless per-page uniqueness rules are met." } ], "first_20_pages": [ "Homepage", "Product / service page", "About + reviewer bio (role-titles)", "Editorial policy", "Contact", "Privacy", "Pillar: ADDE Act (SB 68) menu allergen disclosure — definitive guide", "Leak-rate calculation step by step (annualizing + rolling average)", "§114093.5 edge cases", "§114093.5 FAQs", "Pillar: allergen-disclosure evidence & inspection-readiness", "§114093.5 allergen-disclosure evidence requirements", "Menu ingredient records audit checklist", "Repair-clock and quarterly refresh deadlines", "§114093.5 owner checklist (lead magnet)", "Rule page: Cal. Health & Safety Code §114093.5", "Rule page: CAA §608 dual regime", "Rule page: chronic HOLD reporting", "Comparison: done-for-you allergen-disclosure packs vs menu allergen audit SaaS (MenuRegistry, MenuIQ)", "Q1 CDPH/local health rule change-log post" ], "first_10_tech_fixes": [ "XML sitemap generated at build", "robots.txt reviewed + sitemap referenced", "Self-referencing canonicals", "GSC + GA4 verified with server-side events", "Core Web Vitals baseline (LCP, INP, CLS)", "Structured breadcrumbs sitewide", "Author + editorial-policy pages published", "404 + 410 patterns defined", "Redirect audit (no chains)", "Semantic HTML + accessibility landmarks" ], "first_10_authority_actions": [ "Publish named reviewer bio(s)", "Public editorial policy + correction policy", "Cite primary regulator sources with visited-on dates", "Launch checklist lead magnet", "Pitch 3 HARO / Qwoted responses per week", "Publish 1 original data point / benchmark", "Reach out to 5 non-competing directories", "Guest post on 1 industry association blog", "Podcast interview outreach (5 shows)", "Set up quarterly regulator change-log post cadence" ], "final_recommendation": "Build a regulator-fluent authority site around \"ADDE Act (SB 68) menu allergen disclosure\". Ship the first 20 pages in 90 days (product + pillar + rule library + evidence assets), then compound with quarterly CDPH/local health rule-change posts and one annual benchmark. Refuse doorway pages, refuse mass AI content, treat named-reviewer (role-titled until owner facts close) + primary-source citations as non-negotiable, and never publish penalty figures without the actual-penalties-vary caveat.", "disclaimers": [ "All volume/difficulty/CPC labels are RELATIVE ESTIMATES (low/medium/high), not exact numbers. Validate with Semrush, Ahrefs, or Google Search Console before committing spend.", "This brief is deterministic per blueprint — it will not shift between renders. Any changes should be made in code, not in prompts.", "YMYL topic: language must stay cautious; nothing here is legal/medical/financial advice." ] }, "microsite": { "category": "Regulatory compliance", "shortTitle": "AllergenPack", "audience": "culinary, QA, and operations leaders at 20-120 unit US restaurant brands with at least one California location", "problem": "Since July 1, 2026, any restaurant brand with 20+ same-name US locations and a California door carries a written Big-9 allergen disclosure duty under HSC §114093.5 -- per-item, across every channel, with a non-digital written alternative required whenever any channel is digital. But the evidence that should drive that disclosure lives in scattered recipe cards and supplier specs, sesame hides in marinades, and nobody has mapped a full Big-9 Matrix against the current menu.", "offer": "On AllergenPack, culinary leaders stop guessing at allergen gaps and start shipping released packs. Send recipes and supplier specs; AI extracts the fields with source spans, deterministic rules run the Big-9 mapping against all nine allergens, and a named culinary/allergen-ops specialist releases a Completeness Pack -- Matrix, disclosure copy, Written Alternative, Channel Checklist, Source-Trace Appendix, Change Log -- in 10 business days.", "faq": [ { "q": "Is AllergenPack for the culinary desk or for compliance?", "a": "Both, because at 20-120 locations they're usually the same overworked people: Directors of Culinary, VP Operations, and QA/food-safety managers with no dedicated allergen-ops FTE. If your recipe and supplier documentation currently lives in a shared drive nobody has fully mapped, the workflow will match your reality immediately." }, { "q": "How is an AllergenPack pack run audit-ready?", "a": "Every Big-9 call carries a source span from your recipe or supplier spec -- missing evidence ships as an explicit HOLD, never invented data. Sesame always gets its own column. A specialist signs every release; nothing auto-releases regardless of AI confidence." }, { "q": "What arrives at the end of a pack run?", "a": "A PDF Completeness Pack -- Big-9 Matrix, disclosure copy, Written Alternative booklet/chart, Channel Checklist, Source-Trace Appendix, and Change Log -- plus an editable spreadsheet Matrix, delivered the same day as release with a 30-minute deployment walkthrough." }, { "q": "How does AllergenPack pricing work?", "a": "Outcome-based, never hourly, never contingent on avoided fines. Founding packs run $1,990-$4,900; standard packs $2,500-$12,000 by item count and channel complexity. The Quarterly Refresh Retainer runs $1,200-$3,500 per quarter." }, { "q": "How do I get started on AllergenPack?", "a": "Run the free Menu Allergen Gap Scan -- submit a public menu URL or PDF and get an itemized gap report within 2 business days, no obligation." }, { "q": "Do you certify our menu as allergen-free?", "a": "No -- and that boundary is the design. AllergenPack produces an evidence-based Completeness Pack from the documentation you supply; you remain the brand/PIC of record responsible for accuracy and deployment under the California Retail Food Code." }, { "q": "How long are pack records retained?", "a": "Per the retention period set out in compliance-checklist.md (finalized with counsel before the first paid client) -- evidence and released packs are retained, item-indexed, with a full export handoff available on termination." }, { "q": "What if a supplier will not provide the missing spec?", "a": "We chase with two templated, courteous requests five business days apart. If still silent after that, the item ships marked HOLD with the exact evidence needed to clear it -- never a guessed call, and never hourly chase billing." } ], "process": [ { "title": "Intake: send recipes and specs", "body": "Send recipe cards, supplier specs, current menus, and your channel inventory. Ambiguous item matches go to a human, not a guess." }, { "title": "Extract with source spans", "body": "AI pulls the Big-9-relevant ingredients from every document, each with a verbatim source span and confidence score. Anything without a source routes to specialist triage." }, { "title": "Map with deterministic rules", "body": "Big-9 calls run through versioned rules, not model judgment alone: no blank cells, sesame always its own column, absence of evidence is Unknown -- never a guessed No." }, { "title": "Specialist release gate", "body": "A named culinary/allergen-ops specialist clears every Exception Queue item -- resolved with evidence, or marked HOLD -- before anything ships." }, { "title": "Deliver and check", "body": "The PDF pack and editable Matrix land the same day as release, with a 30-minute deployment walkthrough and a 30-day deployment confirmation check." } ], "northStarCta": { "label": "Get your free Gap Scan", "href": "#diagnostic", "secondary_label": "See pack pricing", "secondary_href": "#pricing" }, "ubiquitousLanguage": { "audience": "culinary, QA, and operations leaders at 20-120 unit US restaurant brands with at least one California location", "domain": "California ADDE Act (SB 68) menu allergen disclosure recordkeeping (HSC §114093.5)", "deliverable": "Completeness Pack + specialist release", "reviewer": "Culinary/allergen-ops specialist", "record": "item-indexed Big-9 Matrix + Source-Trace Appendix", "unit_of_work": "pack run", "cta_primary": "Get your free Gap Scan", "cta_secondary": "See pack pricing", "regulator": "California local environmental health / CDPH", "regulator_full": "California Department of Public Health / local environmental health agencies", "statute": "Cal. Health & Safety Code §114093.5", "trigger_moment": "a recipe or supplier change, an upcoming reprint, or an inspection", "event_intake_started": "ca_adde_allergen_menu_completeness_pack_engine_intake_started", "event_conversation_requested": "ca_adde_allergen_menu_completeness_pack_engine_conversation_requested" }, "trust": { "standards": [ "Every Big-9 call in a Completeness Pack traces to a source span from your recipe or supplier spec -- missing evidence ships as an explicit HOLD, never invented data", "Big-9 mapping runs on versioned deterministic rules; a named specialist releases every pack -- nothing auto-releases", "Records are retained per compliance-checklist.md, item-indexed, with a full export handoff on termination" ], "response_time": "We reply within 2 business days on a Gap Scan -- a reprint cycle or inspection does not wait for a sales rep.", "data_handling": "Your recipes and supplier specs stay in per-client isolated folders and are never used to train models. AllergenPack provides documentation support only; it is not a law firm, does not perform clinical or medical review, and clients remain the brand/PIC of record. It does not guarantee inspection outcomes or fine avoidance." }, "hook": "The next health inspection or franchisee print request lands on a released pack, not a scramble -- AllergenPack holds the item-indexed Big-9 trail at rest.", "sub_headline": "AllergenPack stores every §114093.5 decision -- source span, deterministic call, releaser -- in an item-indexed Matrix a specialist or inspector can walk without your help.", "dream_outcome": "You answer the week: hand over a released, deployable allergen disclosure pack in 10 business days instead of a quarter of scrambling across recipe binders and supplier emails.", "specific_pains": [ "A supplier swaps the house teriyaki glaze recipe -- and by Friday nobody has checked whether the new formulation adds sesame oil or soy that isn't on the current disclosure.", "Ask for the allergen basis on a menu item from six months ago and someone opens an email thread search -- that's the record a health inspector would find first.", "A general-purpose model can produce a plausible-looking allergen matrix; only evidence-only mapping with a specialist release gate produces one a reviewer won't unwind.", "Delivery-app listings drift from the in-store board within a quarter of a menu refresh, and nobody notices until a guest does.", "An inspector reads the disclosure as a package: menu or digital-plus-alternative, per-item Big-9 calls, evidence behind them. Miss any leg and undocumented means unprovable." ], "cost_of_inaction": "A recipe change you don't evidence today is a disclosure gap that persists until the next audit catches it. Retail Food Code penalties run $25-$1,000 per violation and up to 6 months, with each day potentially a separate offense under §114397 -- but an inspection visual check that finds no written disclosure has a cost of its own beyond any fine.", "guarantee": "The Completeness Guarantee: if a pack ships with a blank Big-9 cell on a fully-evidenced item, we re-release that item free within 3 business days. Explicitly not guaranteed: inspection outcomes, fine avoidance, supplier cooperation, or the accuracy of client-attested recipe data.", "urgency": "Release capacity is gated by the human chokepoint -- every pack is signed by a named specialist -- and reprint season consumes specialist hours first. We cap new logos when the release desk is full, protecting the release gate rather than filling a pipeline.", "who_this_is_not_for": [ "Single-location independents -- the math rarely justifies a service; use the free channel checklist and run it yourself.", "Brands wanting a custom recipe-management software build -- that's a different engagement; we'll refer you elsewhere.", "Anyone looking for an allergen-free certification or a guarantee against reactions -- we decline that ask and document it; nobody can honestly sell it." ], "proof_pillars": [ { "title": "Deterministic rules, source-span checked", "body": "Every Big-9 call is backed by a cited source span and a versioned rule -- no blank cells, sesame always its own column, absence of evidence is Unknown, never a guessed No." }, { "title": "Specialist-released, every time", "body": "No pack auto-releases. A named culinary/allergen-ops specialist clears every Exception Queue item and signs the release record." }, { "title": "Item-indexed Matrix -- no rebuild", "body": "Every pack carries the source-traced chain that produced it. Reconstruction for an inspector or franchisee is a read operation, not a project." } ], "stakes_line": "The Matrix is the truth. Everything else -- the supplier's memory, the shared-drive folder nobody opens, the QR code with no written alternative -- is the story you tell yourself.", "deliverable": "Completeness Pack + specialist release", "unit_of_work": "pack run", "lexicon": { "regulator": "California local environmental health / CDPH", "regulator_full": "California Department of Public Health / local environmental health agencies", "statute": "Cal. Health & Safety Code §114093.5", "statute_frame": "the recipe-to-pack workflow where an unreleased pack is a self-inflicted inspection risk.", "persona": "Director of Culinary Operations", "persona_moment": "You're a Director of Culinary Operations. A supplier just changed the house teriyaki glaze formulation. Someone needs to know whether that adds sesame or soy to the disclosure -- with every call tied to a source you can point to.", "trigger_moment": "a recipe or supplier change, an upcoming reprint, or an inspection", "enforcement_stakes": "per-day exposure under the California Retail Food Code (HSC §114395/§114397; actual penalties vary case-by-case and are never predictable or guaranteed)", "retention": "per compliance-checklist.md", "cta_verb": "Get your free Gap Scan", "intake_checklist": [ "Recipe cards or standardized recipes for every standard menu item", "Supplier specification sheets or ingredient-label photos for every purchased component", "Current menu artifact per deployment channel (in-store, kiosk, app, web, delivery listings)", "Channel inventory list confirmed by the client", "Named release approver authorized to accept the pack" ], "trust_standards_specific": [ "Every Big-9 call traces to a source span from the recipe or supplier spec you supplied -- gaps ship explicit, never invented", "A named specialist signs every release; nothing auto-releases regardless of AI confidence", "Records retained per compliance-checklist.md, item-indexed, keyed to the triggering evidence", "§114093.5 requirements are mapped to your evidence line-by-line; hard fails (no source, no written alternative on a digital channel) block release", "AI is bounded to extraction and mapping drafts from structured input, disclosed, and gated on human release before any pack leaves the workspace" ], "regulator_faqs": [ { "q": "Do you sign the pack as our regulatory representative?", "a": "No -- you remain the brand/PIC of record and the duty holder under §114093.5. Our specialist signs the release; you attest recipe and supplier accuracy; anything sent to a regulator or inspector is reviewed, approved, and submitted by you." }, { "q": "How long is the record retained?", "a": "Per the retention period set out in compliance-checklist.md, finalized with counsel before the first paid client -- item-indexed and mirrored to your own storage where practical." }, { "q": "What if a recipe change lands on a Friday?", "a": "Intake runs on the 10-business-day SLA from completeness-gate pass, not from when anyone notices a change -- so nothing quietly ages over a weekend without a logged gap." }, { "q": "What if we started the disclosure work in-house?", "a": "Send what exists. We pick up mid-workflow, keep your work product intact, register what's usable as evidence, and only add the pieces the §114093.5 record is missing -- no rework, no compliance theater." } ] }, "proof_angle": { "id": "audit-readiness", "headline": "The next inspection or franchisee print request lands on a released pack, not a scramble -- AllergenPack holds the item-indexed trail at rest.", "lever": "AllergenPack stores every §114093.5 decision -- source span, deterministic call, releaser -- in an item-indexed Matrix a specialist or inspector can walk without your help.", "outcome_verb": "answer", "outcome_frame": "answer a menu allergen disclosure request in a day instead of a quarter", "proof_promise": "The Big-9 Matrix is the disclosure-request answer -- source-traced, specialist-signed, and reproducible the day the request arrives." }, "mechanism": { "name": "The AllergenPack §114093.5 pack factory", "steps": [ { "title": "Intake: send recipes and specs", "body": "Send recipe cards, supplier specs, current menus, and your channel inventory. Ambiguous item matches go to a human, not a guess." }, { "title": "Extract with source spans", "body": "AI pulls Big-9-relevant ingredients from every document, each with a verbatim source span and confidence score. Anything below the confidence bar routes to specialist triage." }, { "title": "Map in deterministic rules", "body": "Big-9 calls run through versioned rules: no blank cells, sesame always its own column, absence of evidence is Unknown -- never a guessed No." }, { "title": "Specialist release gate", "body": "A named culinary/allergen-ops specialist clears every Exception Queue item -- resolved with evidence or marked HOLD -- before anything ships." }, { "title": "Deliver, register, watch", "body": "The PDF pack and editable Matrix land the same day as release, with a 30-minute deployment walkthrough and a 30-day deployment confirmation check." } ] }, "offer_stack": [ { "item": "Completeness Pack per brand menu family", "note": "Big-9 Matrix, disclosure copy, Written Alternative, Channel Checklist, Source-Trace Appendix, Change Log" }, { "item": "Evidence-only Big-9 mapping", "note": "no ingredient call ships without a source span; missing evidence ships as an explicit HOLD, never a guessed number" }, { "item": "Specialist release on every pack", "note": "named culinary/allergen-ops specialist signs every release; nothing auto-releases regardless of AI confidence" }, { "item": "Channel Checklist", "note": "every deployment surface -- boards, kiosk, app, web, delivery listings -- mapped to what needs to change" }, { "item": "Change Log", "note": "living record of supplier substitutions and menu changes, ready for the next Quarterly Refresh" }, { "item": "HOLD register", "note": "you get the closable missing-evidence list before release -- formatted for supplier follow-up -- not a finding list after an inspector reads the pack" } ], "objections": [ { "q": "\"Doesn't our recipe platform already handle allergens?\"", "a": "Most recipe platforms store what your team types into them -- and at 20-120 locations, nobody has fully typed in every supplier substitution. AllergenPack is a production service, not a data-entry tool: we do the extraction, the mapping, the supplier-spec chase, and the release, and you receive a finished pack." }, { "q": "\"Isn't this what menu-audit SaaS already does?\"", "a": "A SaaS seat logs what your team enters into it. AllergenPack is a factory, not a dashboard: evidence in, released Completeness Pack out -- no platform migration, no ongoing tool to operate." }, { "q": "\"Are we going to be defending an AI-drafted disclosure?\"", "a": "No Big-9 call ships without a cited source span. AI extracts and drafts from structured input only; deterministic rules enforce completeness; a named specialist signs every release. If a source isn't attached, the item ships as an explicit HOLD." }, { "q": "\"Where does our recipe and supplier data live?\"", "a": "In per-client isolated folders with least-privilege access, never used to train models. The hidden-ingredient pattern library is built from generalized patterns only -- never a specific client's proprietary recipe verbatim." }, { "q": "\"What happens when the rule changes or other states pass copycat laws?\"", "a": "Rule-watch is a standing SOP with quarterly legislative checks. As of this build, Maryland, New Jersey, Illinois, Ohio, Missouri, New York, and Michigan are pursuing copycat allergen-disclosure bills -- the rule engine is modular per state by design, so a new law expands scope rather than breaking the model." }, { "q": "\"How is an AllergenPack engagement priced?\"", "a": "Per pack and per retainer term, published bands, never hourly, and never a contingency on avoided fines -- that framing is prohibited here. Anchor it against a few months of SaaS seat cost or the price of a rushed reprint after a failed inspection." } ], "indexable": true }, "evidence": [ { "id": "ca-adde-allergen-menu-completeness-pack-engine-e1", "business_slug": "ca-adde-allergen-menu-completeness-pack-engine", "area": "Identity", "claim_or_finding": "Legal entity, registered address, and jurisdiction of formation are not yet declared.", "status": "owner-action", "evidence": "No owner-supplied facts on file.", "verification_command": "Owner submits entity + jurisdiction pack.", "fix_owner": "owner", "remediation": "Provide entity name, registration number, and jurisdiction of formation.", "severity": "blocker" }, { "id": "ca-adde-allergen-menu-completeness-pack-engine-e2", "business_slug": "ca-adde-allergen-menu-completeness-pack-engine", "area": "Trust boundary", "claim_or_finding": "Public page is a validation microsite for a documentation-support service; not a law firm, not a certification body.", "status": "verified", "evidence": "Microsite carries explicit trust-boundary and documentation-support-only disclaimer block in the Compliance section.", "verification_command": "Inspect /ca-adde-allergen-menu-completeness-pack-engine for the compliance disclosure block.", "fix_owner": "engineering", "remediation": "None -- enforced by template.", "severity": "low" }, { "id": "ca-adde-allergen-menu-completeness-pack-engine-e3", "business_slug": "ca-adde-allergen-menu-completeness-pack-engine", "area": "Regulatory citation", "claim_or_finding": "HSC §114093.5 written allergen disclosure duty effective July 1, 2026 for covered facilities.", "status": "verified", "evidence": "CA LegInfo SB-68 chaptered bill text; corroborated by CA Restaurant Association and Fisher Phillips guidance; fresh 2026-07-13 verification confirmed enforcement began on schedule (Allergic Living, June 29 2026).", "verification_command": "Cross-check leginfo.legislature.ca.gov SB-68 text against HSC §114093.5 citation on the landing page and compliance-checklist.md.", "fix_owner": "content", "remediation": "None required.", "severity": "low" }, { "id": "ca-adde-allergen-menu-completeness-pack-engine-e4", "business_slug": "ca-adde-allergen-menu-completeness-pack-engine", "area": "Pricing evidence", "claim_or_finding": "MenuRegistry prices $59-$79 per location per month for menu-audit records, used as the SaaS pricing anchor.", "status": "verified", "evidence": "menuregistry.com/pricing (referenced); fresh fetch 2026-07-13 confirmed the ADDE Act guide page but did not surface itemized rates directly on that page -- pricing figure sourced from the blueprint's prior verified capture.", "verification_command": "Re-fetch menuregistry.com/pricing directly before next refresh cycle to reconfirm exact figures.", "fix_owner": "content", "remediation": "Reconfirm MenuRegistry's exact current rate card at next quarterly refresh.", "severity": "medium" }, { "id": "ca-adde-allergen-menu-completeness-pack-engine-e5", "business_slug": "ca-adde-allergen-menu-completeness-pack-engine", "area": "Market sizing", "claim_or_finding": "~2,130 chains / ~298,600 establishments sized under the federal menu-labeling coverage test SB 68 borrows; CA has 86,779 restaurant locations.", "status": "verified", "evidence": "FDA RIA via CRS summary (dated estimate); NRA California 2025 fact sheet.", "verification_command": "Compare stat-strip figures on the landing page against the cited sources.", "fix_owner": "content", "remediation": "Treat the exact count of 20+/CA-door brands as a range, not a fact -- already logged in product.unknowns.", "severity": "low" }, { "id": "ca-adde-allergen-menu-completeness-pack-engine-e6", "business_slug": "ca-adde-allergen-menu-completeness-pack-engine", "area": "Proof / testimonials", "claim_or_finding": "No client names, testimonials, or case results exist yet; all proof slots are [PLACEHOLDER].", "status": "owner-action", "evidence": "site/index.html proof section uses dashed placeholder styling per DESIGN-STANDARD.md §4.", "verification_command": "Inspect /ca-adde-allergen-menu-completeness-pack-engine proof section for placeholder styling and absence of fabricated names.", "fix_owner": "owner", "remediation": "Populate placeholders only after pilot packs actually ship and 30-day checks complete.", "severity": "medium" }, { "id": "ca-adde-allergen-menu-completeness-pack-engine-e7", "business_slug": "ca-adde-allergen-menu-completeness-pack-engine", "area": "Insurance / licensing", "claim_or_finding": "E&O insurance carrier and coverage limits not yet confirmed; engagement-letter outline is a non-binding template pending counsel review.", "status": "owner-action", "evidence": "compliance-checklist.md marks both items [PLACEHOLDER].", "verification_command": "Confirm before accepting the first paid client.", "fix_owner": "owner", "remediation": "Shop specialty E&O policies and engage counsel to finalize the engagement-letter template.", "severity": "blocker" }, { "id": "ca-adde-allergen-menu-completeness-pack-engine-e8", "business_slug": "ca-adde-allergen-menu-completeness-pack-engine", "area": "Multi-state expansion", "claim_or_finding": "Maryland, New Jersey, Illinois, Ohio, Missouri, New York, and Michigan are pursuing copycat allergen-disclosure legislation as of mid-2026.", "status": "verified", "evidence": "Allergic Living, 'ADDE Allergens on Menu Act Takes Effect, Inspiring More States,' 2026-06-29 (fresh fetch 2026-07-13).", "verification_command": "Re-check state legislative session status quarterly.", "fix_owner": "content", "remediation": "None required now; revisit if any bill passes.", "severity": "low" } ], "seo_pages": { "id": "seo-ca-adde-allergen-menu-completeness-pack-engine", "business_slug": "ca-adde-allergen-menu-completeness-pack-engine", "route": "/microsites/ca-adde-allergen-menu-completeness-pack-engine", "title": "ADDE Act (SB 68) Allergen-Disclosure Completeness Pa… · tp9o", "description": "AllergenPack for culinary and operations leaders at multi-unit restaurant brands. Release-ready Cal. Health & Safety Code §114093.5 Completeness Packs from your contract…", "canonical": "/microsites/ca-adde-allergen-menu-completeness-pack-engine", "og_title": "AllergenPack — CA ADDE Act (SB 68) Menu Allergen Completeness Pack Engine", "og_description": "AllergenPack for culinary and operations leaders at multi-unit restaurant brands. Release-ready Cal. Health & Safety Code §114093.5 Completeness Packs from your contract…", "schema_type": "FAQPage", "schema_status": "pending-owner-facts", "sitemap_include": false, "noindex": true }, "vertical_style": { "accent": "herb-green", "signature": "Pack kitchen clipboard tabs with Big-9 status chip", "layout": "Pack binder index", "anti": "Snowflake/allergy-icon clip-art and alarm-red penalty banners" }, "canva": { "slug": "ca-adde-allergen-menu-completeness-pack-engine", "territory": "Pack Kitchen", "family": { "id": "legal-compliance", "name": "Legal / Compliance", "motion": "calm" }, "tokens": { "brand": "9 59% 45%", "brand-fg": "23 100% 95%", "surface": "37 62% 96%", "ink": "20 22% 14%", "muted": "22 13% 37%", "accent": "156 44% 33%" }, "type": { "display": "system-ui, -apple-system, sans-serif", "body": "system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif", "fonts_url": "none -- system font stack only (performance budget)" }, "scale": { "h1": "clamp(2.5rem, 5.5vw, 4.25rem)", "h2": "clamp(1.75rem, 3vw, 2.5rem)", "h3": "clamp(1.25rem, 2vw, 1.5rem)", "body": "clamp(1rem, 1.1vw, 1.125rem)", "small": "0.8125rem", "tracking_display": "-0.02em", "tracking_body": "-0.005em", "weight_display": 700, "weight_body": 450 }, "spacing": { "card_padding": "1.75rem", "card_radius": "0.25rem", "card_shadow": "0 0 0 1px hsl(var(--ink) / 0.08)", "section_gap": "clamp(3.5rem, 8vw, 6.5rem)", "hero_gap": "clamp(1.25rem, 2vw, 2rem)" }, "layout": { "hero": "split-primary", "card": "elevated-soft", "cta": "solid-brand", "archetype": "magazine", "card_silhouette": "flat-outline", "button_geometry": "sharp" }, "background": { "hero_gradient": "radial-gradient(1200px 600px at 10% -10%, hsl(17 61% 33% / 0.18), transparent 60%), radial-gradient(900px 500px at 90% 10%, hsl(226 49% 19% / 0.12), transparent 55%)", "cta_gradient": "linear-gradient(135deg, hsl(226 49% 19%), hsl(17 61% 33%))", "section_wash": "linear-gradient(180deg, hsl(40 25% 97%) 0%, hsl(226 49% 19% / 0.04) 100%)" }, "motif": "Pack cover + register row" }, "capabilities": { "marketing": true, "portal": false, "ops": true, "chatbot": false, "payments": false }, "generated_at": "2026-07-13T00:00:00Z", "checksum": "9598a4a6e2bdf2dd" }