TN

TrueNorth AI

POC10 Upgrade Spec

Technical Brief & Verification Roadmap · Baseline: React 19

Target: Production Pilot MVP
Verification Checklist ↓
PROJECT SCOPE & VERIFICATION SPECIFICATION

Transitioning POC10 to a Scalable, Safe, Production-Grade Learning Platform

This roadmap defines the transition of TrueNorth AI from a browser-only single-file prototype into a secure, production-ready system backed by our existing React 19 platform, Cloudflare Pages Functions, and Supabase persistence. Every phase details concrete deliverables and client-testable acceptance criteria.

Current Baseline
POC8 in React 19
51 passing unit tests
Target Capabilities
6 Active Engines
Full exercise library
Backend Architecture
Server-Side Claude
Zero browser keys exposed
Child Safeguards
3 Security Pillars
Age gate, AI badge, Moderation
01

Phase 1: POC10 Engine & Feature Parity in React 19

Core Engine

Closing the gap from POC8 to POC10 within the existing modular, typed React repository.

Prerequisite: None (First Step)

Engineering Breakdown Tasks

  • Generalize Targeting Engine: Expand targeting.ts to support all six capabilities with taskLibraryFor(capability) and the 3-independent-correct tier progression rule.
  • Port 5 Interactive Exercise Views: Implement Cognitive Flexibility (Rule Changed), Creative Thinking, Emotional Intelligence (Stuck on Purpose), Self-Expression, and Systems Thinking using existing Card and ChoiceButton components.
  • Port Teacher Portal CRUD: Add child, soft-remove, restore, hard-delete with confirmation, grouping by capability strength/gap, and Sonia demo-only flag.
  • Family & School Context Form: Port 16 parent/teacher questions tagged to capabilities (cap:logical, etc.).
  • Automated Test Expansion: Extend the 51 unit tests to cover deterministic scoring and tier transitions across all 6 capabilities.

What the Client Can Test & Verify

Full Exercise Workflow

Navigate to the curriculum and complete all 6 exercises. Verify that the Cognitive Flexibility sort-rule change triggers at item 2, and Emotional Intelligence retry logs properly.

Teacher Portal CRUD

Add a new student, soft-delete them, restore them, and execute a permanent delete with name confirmation. Verify Sonia remains pinned as demo data.

Tagged Context Collection

Submit parent and teacher questionnaires and confirm answers save cleanly per role with correct capability tags.

02

Phase 2: Production Infrastructure, Database & Edge Gate

Brief Priority 1 & 3

Moving from browser localStorage to Supabase persistence, server-side Claude API, and edge password protection.

Prerequisite: Phase 1

Engineering Breakdown Tasks

  • Supabase Database Schema: Provision tables for students, evidence_instances, context_answers, and delete_audit_logs with foreign keys and Row Level Security (RLS).
  • Implement SupabaseEvidenceStore: Seamless swap from in-browser localStorage to the persistent Supabase backend without altering UI layer code.
  • Cloudflare Edge Password Gate (/api/gate): Single shared password protection with an encrypted HTTP-only cookie. Changeable in the Cloudflare dashboard without redeploying code.
  • Secure Claude Proxy Function (/api/report): Browser never prompts for or touches an API key. Requests proxy through Cloudflare Pages Functions holding the secret key server-side.
  • Student Identity Migration: Transition from fragile typed-name matching to persistent stu_xxxx UUID sessions.

What the Client Can Test & Verify

Zero API Keys in Browser

Open browser DevTools Network tab during report generation. Verify no Claude API key or secret token appears anywhere in request headers or HTML source.

Cross-Device Data Persistence

Complete an exercise on Desktop Chrome, then open the student record on Mobile Safari. Real evidence and tier status sync immediately via Supabase.

Shared Password Gate Walkthrough

Open an incognito window. You must enter the shared password before accessing any onboarding or student page. Rotate the password in dashboard to test lock-out.

03

Phase 3: Milestone & Reporting Engine + Hypothesis Logic

Brief Priority 2 & 4

Connecting real exercise evidence to update the student profile report and testing parent/teacher hypotheses.

Prerequisite: Phase 2 (Database)

Engineering Breakdown Tasks

  • Milestone Evidence Aggregator: Query service to collect raw evidence instances logged since previous report checkpoint, grouping by capability and filtering flagged attempts.
  • Dynamic Milestone Report Generation: Structured prompt service passing empirical tier achievements + observed behaviors to Claude to regenerate an accurate, evidence-backed report.
  • Hypothesis Comparison Engine (Pure TS): Evaluate parent/teacher answers against real exercise observations to calculate Consistent, Not Yet Testable, or Contradicted.
  • Diplomatic Copy Integration: Inject agreed diplomatic phrasing in Contradicted cases so feedback remains constructive and encouraging.
  • Report History & Versioning: Store versioned historical reports in Supabase to track progression over time.

What the Client Can Test & Verify

Dynamic Report Update from Evidence

Complete 3 Cognitive Flexibility exercises to reach Provisional tier. Trigger the Milestone Report and verify that the report updates to quote the real exercise evidence rather than questionnaire guesses.

Hypothesis Verdict Testing

Fill out the parent form rating Logical Reasoning as high. Intentionally fail or skip the Logical Reasoning exercise, then verify the comparison displays the approved diplomatic Contradicted phrasing.

04

Phase 4: Child Safety, AI Disclosure & Content Moderation

Brief Priority 5 (Non-Negotiable)

Mandatory child safeguards before any real pilot student accesses the application.

Runs in Parallel with Phase 2 & 3

Engineering Breakdown Tasks

  • Age Verification Gate: Pre-onboarding screen requiring age confirmation before a child enters the questionnaire.
  • Transparent AI Disclosure: Unambiguous, child-friendly visual indicator informing the child they are interacting with AI.
  • Server-Side Content Moderation: Automated moderation pass on all AI-generated text shown directly to the child (specifically the personal encouragement note).
  • Review Flagging System: Auto-flagging for human educator review if attempt duration is under 2s (guesswork) or on 4th+ consecutive attempt.

What the Client Can Test & Verify

Age Barrier Enforcement

Attempt to proceed through onboarding with an unverified or invalid age; verify that the platform cleanly prevents access.

AI Disclosure Check

Review onboarding and exercise headers to verify the clear child-friendly AI badge is visible across all interactive views.

Safety Filter Inspection

Trigger report generation; inspect the server response to confirm all child-facing notes pass automated safety validation before rendering.

05

Phase 5: Content Scaling & AI Rubric Judgement

Brief Priority 6 (Post-Rubric)

Replacing placeholder word counts with Claude LLM-as-a-judge and expanding task variants per capability.

Pending: Dr. Chew Lee's Rubric

Engineering Breakdown Tasks

  • Server-Side Rubric Judge (/api/judge): Implement Claude prompt judging Creative Thinking & Self-Expression based on Dr. Chew Lee's formal rubric criteria.
  • Replace Word-Count Placeholders: Remove the temporary 12-word and 20-word limits with qualitative rubric scoring.
  • Task Variant Expansion: Structure task libraries in JSON to support 3+ variants per difficulty tier across all capabilities.

What the Client Can Test & Verify

Qualitative AI Assessment

Submit high-effort creative responses vs generic gibberish; verify the rubric judge evaluates genuine conceptual novelty rather than sentence length.

Multi-Session Task Variety

Run repeated exercise sessions with a student; verify they receive fresh task variants across consecutive attempts.

Client Review Matrix

End-to-End Verification Checklist

Interactive checklist to track acceptance criteria as each phase is deployed to staging.

Staging: truenorth-ai-a5j.pages.dev
Phase / Area Testable Deliverable Expected Client Verification Outcome Status
Phase 1 6 Interactive Capabilities All 6 exercises accessible in curriculum view; deterministic scoring operates without errors. Ready to Build
Phase 1 Teacher Portal CRUD Add, soft-delete, restore, and permanently delete students with name confirmation. Ready to Build
Phase 2 Edge Password Gate Unauthenticated visitors blocked by shared password wall; cookie session persists. Queued
Phase 2 Zero-Key Claude Proxy DevTools reveals no API keys; report generation executed via Cloudflare serverless function. Queued
Phase 3 Milestone Evidence Engine Real completed exercises advance tier from Emerging to Provisional; report reflects real data. Queued
Phase 3 Hypothesis Comparison Outputs Consistent / Not Yet Testable / Contradicted with agreed diplomatic phrasing. Queued
Phase 4 Child Safety Guardrails Age check barrier, plain-language AI disclosure banner, server-side content filter. Queued
Phase 5 AI Rubric Judge (CT & SE) Qualitative rubric evaluation replaces word count placeholder once Dr. Chew Lee submits rubric. Post-Rubric

Technical Conventions & Quality Standards

Clean Typographic Policy

All strings, descriptions, and copy will strictly follow the zero-em-dash policy, using clear, plain punctuation across the entire application.

Automated Test Regimen

Every scoring rule, tier computation, and comparison outcome is tested via pure unit tests before deployment, expanding beyond the 51 baseline tests.

Instant Dashboard Gate Rotation

The shared password is bound to Cloudflare Pages environment variables, allowing the team to revoke or change the password in seconds without triggering a code rebuild.