Eve library

Oshun V1 — Implementation TODOs

Tracker

Revision 1

On this page

Historical task source. The Eve task board holds current task state.

Brand & release scope (2026-08-05). The consumer product is named Lilith (see V1/BRAND.md); company is Oshun Synthetics LTD; app at lilith.oshunsynthetics.com.

The V1 line ships in three releases, and this backlog spans all three:

  • V1.0 — web + PWA, four rooms: Tara, Nyx, Arete, Nisaba.
  • V1.1 — native iOS/Android apps and watch companions.
  • V1.2 — restores the Veritas and Metis rooms.

Two whole classes of task in this backlog are therefore not V1.0 launch blockers, and an unchecked box in either class must not be read as one:

  1. Native mobile-app tasks are V1.1 scope. Do not add store links to any V1.0 surface (LILITH_NATIVE_APPS_AVAILABLE gates this in code).
  2. Veritas and Metis tasks are V1.2 scope. Their code stays in the tree and stays worth finishing — governance still stocks those rooms before they open — but no V1.0 console may advertise, link to, count, or compose them. The cut is declared once in libs/oshun/navigation/src/release-scope.ts and read everywhere.

Everything else in this backlog is V1.0 scope.

Source: derived from V1/features.md cross-referenced against the current state of apps/ and libs/ as of 2026-05-06 (features.md has since grown; line-count provenance removed 2026-06-12).

Purpose#

This file is the source of truth for V1 completion state. Each unchecked [ ] is a coding-agent-actionable task. A task is complete only when its implementation, tests, and required wiring all exist in code — not merely when a file or type stub is present. Per CLAUDE.md "Zero Tolerance for Stubs", partial implementations remain unchecked.

⚠️ Completion-state audit (2026-06-12): the [x] marks below are not authoritative on their own. The 1,639 [x] marks in this file (count at audit time) predate the root-level audit chain and must not be treated as completion truth without consulting it. The operative residual truth is:

A task checked [x] here with an open residual finding against it is not done. Consult those documents before relying on, or building on top of, any [x] in this file.

Audit snapshot from current codebase#

This checklist was re-audited against V1/features.md and the current workspace on 2026-05-06. Important repo-shape findings that affect how agents should execute the work:

  • apps/oshun/{web,mobile,admin,admin-mobile,bff} exist; apps/oshun/studio and apps/oshun/public-web do not. Studio tasks should first check whether the intended surface belongs under apps/oshun/web/src/app/studio/ before creating a new app.
  • apps/metis/{web,admin,api-gateway,worker,mobile} exist. apps/metis/mobile must be audited for actionable learner-surface behavior, not merely app/file presence.
  • libs/oshun/domain-*, libs/oshun/memory-iris, libs/oshun/embodiment-psyche, libs/oshun/persona-policy-lilith, and libs/oshun/generation-control-isis contain partial V1-oriented code and tests. File presence is not completion; each task must verify contract, persistence, BFF wiring, surface behavior, and release-gate coverage before marking complete.
  • libs/contracts/src/common/ already contains many common contracts, but the domain-specific canonical contract set in Section 1.2 remains unchecked until every object class is exported, fixture-tested, and drift-tested against persistence and OpenAPI/codegen.
  • Admin web and mobile have substantial unit/E2E coverage. Tasks remain unchecked where V1 requires cross-workspace operation, tenant isolation, audit completeness, launch gates, or code paths beyond mocked UI fixtures.

How to use this file#

  • Process tasks sequentially. Do not batch-mark or skip ahead.
  • For each task:
    1. Read the referenced files / contracts.
    2. Implement the feature with real, domain-specific logic (no stubs, no placeholders, no Math.random() for deterministic outputs).
    3. Write tests that assert domain correctness (specific values against known-correct answers, not just truthiness).
    4. Run the adversarial stub scan from CLAUDE.md against the changed code before marking complete.
    5. Mark [x] and commit.
  • A task that no coding agent can do (e.g., "Penetration test by external vendor") keeps its [ ] and gets a `blocked:<reason>` tag with a one-line note, per .claude/rules/task-checkbox-verification.md; it then appears in TODOS/PARKED.md. (Until 2026-09-18 this file used a third mark, [~], which the task board could not see; its eleven items were converted that day.) Install what a task needs before calling it blocked. Everything else must be implemented.
  • File-path hints reference the most likely existing location, but agents should grep before assuming and prefer extending an existing module to creating a new one.

V1 Exit Criteria (high level)#

V1 is feature-complete only when every section below is fully checked AND the adversarial scan turns up zero actionable hits AND launch-readiness drills have run. See "## Launch Readiness" near the end for the gating checklist.


Table of Contents#

  1. Foundations: Contracts, Adapters, Persistence
  2. Customer Surfaces: Web, Mobile, Shared Shell
  3. Domain — Tara
  4. Domain — Arete
  5. Domain — Veritas
  6. Domain — Nyx
  7. Domain — Nisaba
  8. Domain — Metis
  9. Sophia — Grounding
  10. Iris — Memory and Identity
  11. Psyche — Real-Time Runtime
  12. Lilith — Persona Policy and Safety
  13. Isis — Generation Control
  14. Persona, Avatar, and Voice Packs
  15. Search, Discovery, Recommendations, Knowledge Graph
  16. Oshun Studio — Authoring, Editorial, Assets, Taxonomy, Localization, Versioning
  17. Customer Curation — Notebooks, Collections, Annotations
  18. Agentic AI Studio
  19. Admin Web and Admin Mobile
  20. Tenant Console and Operator Toolkit
  21. Trust and Safety
  22. Privacy, Consent, Residency, DSAR
  23. Support, Entitlements, Billing
  24. Civitai, ComfyUI, RunPod, Voice Providers
  25. Living Scenes
  26. Messaging Channels and Conversational Surfaces
  27. Architecture and Platform Foundations
  28. Security, Access Control, Operational Hardening
  29. Design System and Experience Quality
  30. Analytics, Observability, Experimentation, Evaluation
  31. Testing, QA, Accessibility, Performance
  32. Content, Localization, Documentation
  33. Launch Readiness
  34. Studio Substrate Bridges (Bellona, Hathor, Neith)
  35. Dependency Gap Closure (from DEPENDENCIES self-flagged launch gaps)
  36. Mentor Presence — Meditating with a Master

1. Foundations: Contracts, Adapters, Persistence#

The contracts layer underpins every other section. Get this right first; a schema gap here cascades into every domain.

1.1 Canonical domain registry#

  • Implement libs/oshun/domain-registry/src/registry.ts exporting a single source of truth for domains: Tara, Arete, Veritas, Nyx, Nisaba, Metis. Each entry: id, displayName, route, auth, analytics-id, notification-channel, assistant-context-key, bff-base-path, deep-link-prefix, admin-taxonomy.
  • Implement runtime guards in libs/oshun/domain-registry/src/guards.ts so cross-domain references can be validated at boundary entry.
  • Add libs/oshun/domain-registry/src/__tests__/registry.spec.ts verifying every domain has every required field and IDs are unique.
  • Publish ownership matrix doc at docs/oshun/ownership-matrix.md mapping each feature surface to the owning subsystem and the "when to call which subsystem" guidance.

1.2 Canonical Zod contracts (one source per object class)#

For each contract below, write the Zod schema in libs/contracts/src/<name>/, export from libs/contracts/src/index.ts, and add a contract test that round-trips a fixture.

Tara contracts

  • RitualTemplate, RitualStep, RitualSession, SessionState, ContinuationState, MoodTaxonomy, ThemeTaxonomy, ModalityTaxonomy, LineageTaxonomy, DurationBucket, ContextTag.

Arete contracts

  • Habit, Goal, Routine, CheckIn (status: done/partial/skip/decline/miss), JournalEntry, WeeklyReview, StreakRecord, FrictionSignal, Intervention, CoachingSummary.

Veritas contracts

  • Story, Claim, Source (with SourceKind ⊇ peer-review/primary/ secondary/press-release/opinion/social/government/NGO), EvidencePack, ClaimConfidenceBand (well-supported/supported/ emerging/contested/unsupported/retracted), Counterclaim, TopicHub, Timeline, StoryUpdate (new-evidence/retracted-source/ contested-claim/new-counterclaim/corrected-claim), CorrectionNote, RetractionCascade.

Nyx contracts

  • SkyEvent (with full event taxonomy: meteor showers, eclipses, conjunctions, occultations, transits, comets, aurora, ISS passes, supermoons, equinoxes, solstices, cross-quarter, deep-sky peak), ObservationWindow, ObservationQualityBand, PredictionSourceRef (NASA JPL / IMO / IERS / NOAA SWPC / weather / Bortle / etc.), CalendarSyncEntry.

Nisaba contracts

  • Passage, Manuscript, Edition, Translation, LexiconEntry, MorphologyEntry, Annotation, ConceptGraphNode, ConceptGraphEdge, Notebook, StudyPlan, Citation, ScholarProfile.

Metis contracts

  • LearningSourceBundle — files, URLs, feeds, LMS imports, source bundles with extraction state and source-quality band.
  • GroundingPack — versioned, scoped to notebook/workspace/course/tenant.
  • CourseBuild — outline → lessons → assessments with grounded sources.
  • LessonAssetBundle — slides, narration, captions, transcripts, diagrams.
  • PublicationPackage — release-ready bundle with provenance.
  • TutorPersonaProfile — selection policy, coaching style, questioning technique, policy rules, lineage, locale coverage, entitlement.
  • TutorSessionMemory — continuity, runtime state, recovery, governance, mastery snapshot, review priority.
  • LearningObjectiveMap — per-course objective hierarchy with prerequisite chain and assessment binding.
  • AssessmentEvidencePack — integrity signals, observations, artifacts, severity, item-level data.
  • LearningTelemetryStatement — xAPI/cmi5-compatible standalone record.
  • AcademicIntegrityVerdict — class (clear/inconclusive/violation/severe), detection signals, classifier output, model versions, evidence excerpts, decision rationale, appeal path.

Cross-cutting contracts

  • Persona, VoiceProfile, AvatarPack with consent/lineage/lifecycle.
  • ConsentRecord — per-category, per-scope, with timestamp, actor, prior state, new state, reason code.
  • MemoryScope — profile/session/notebook/operator-copilot/tenant.
  • EvidencePack, CitationTrail, GroundedAnswerEnvelope.
  • WorkflowTemplate, ModelCard, ModelVersion, ProvenanceBundle (consent ID, prompt, model, watermark hash, timestamp, invoking user, tenant).
  • ReviewPackage (stage-graph + decision lifecycle), Incident, PolicyBundle, SupportCase.
  • Tenant, TenantHierarchyEdge, TenantPolicyInheritance.
  • AgentRun (inputs/plan/tool-calls/intermediate-artifacts/evidence/ cost-ledger/decision-rationale/output-bundles/status/provenance).

1.3 Canonical adapters#

  • Adapter libs/oshun/domain-tara/src/adapter.ts exposing typed read APIs for shell/admin/assistant; wire through BFF.
  • Adapter libs/oshun/domain-arete/src/adapter.ts (same).
  • Adapter libs/oshun/domain-veritas/src/adapter.ts (same).
  • Adapter libs/oshun/domain-nyx/src/adapter.ts (same).
  • Adapter libs/oshun/domain-nisaba/src/adapter.ts (same).
  • Adapter libs/metis/api-client/src/adapter.ts consolidated under the Oshun convention (rename if needed to libs/oshun/domain-metis/).
  • Adapter libs/oshun/evidence-sophia/src/adapter.ts for grounding state.
  • Adapter libs/oshun/memory-iris/src/adapter.ts for memory state.
  • Adapter libs/oshun/embodiment-psyche/src/adapter.ts for runtime state.
  • Adapter libs/oshun/persona-policy-lilith/src/adapter.ts for tone/safety.
  • Adapter libs/oshun/generation-control-isis/src/adapter.ts for jobs.
  • Adapter libs/oshun/embodiment-aja/src/adapter.ts for embodied instruction (Metis hook).

1.4 Persistence and migrations#

  • Define Prisma (or equivalent) models matching every contract above; add a contract-to-persistence drift test in tests/contract-persistence-alignment.spec.ts that fails on field divergence between Zod and the persistence layer.
  • Migration plan + backfill plan per domain (idempotent, dry-runnable).
  • Tombstone semantics on every user-data table (deletion is a soft tombstone that propagates and is audit-logged; no silent re-creation).
  • Add per-table required indexes for the documented query patterns; validate via EXPLAIN checks in CI.

1.5 OpenAPI and codegen#

  • Generate OpenAPI specs for every BFF route and domain service under libs/openapi/src/specs/ from the Zod contracts (single source of truth — schemas drive specs, not the other way around).
  • Generate typed clients per domain into libs/<domain>/api-client/.
  • Add CI gate: spec drift against runtime fails build.

1.6 Idempotency, partial-failure semantics, response normalization#

  • Implement idempotency-key middleware in libs/shared/http-client/ with request deduplication + replay-safe semantics.
  • Standardize partial-failure response envelope (results[], errors[], partial: true) across BFF and domain services.
  • Add contract tests for retry/dedup/replay/dead-letter on every job submitter.

1.7 Multi-tenant routing#

  • Tenant-aware request middleware reading X-Tenant-ID (or token claim) and propagating through every downstream call.
  • Residency-aware traffic shaping: route requests to the user's primary data plane unless explicit cross-region consent is present.
  • Tenant-aware caching keys (no cross-tenant cache pollution).
  • Tenant-aware feature flags + experiment scoping.
  • Cross-tenant leakage test suite under tests/security/tenant-isolation/.

1.8 Background-job substrate#

  • Durable queue with priority classes, replay, deduplication, dead-letter, observability hooks. Single shared substrate consumed by editorial, asset, agentic AI, notification, billing, and integration jobs.
  • Per-job-class SLA monitor + alert hooks.

1.9 Webhook and event-bus plumbing#

  • Topic registry with schema versioning under libs/shared/event-bus/.
  • Outbound signing keys + retry/backoff + dead-letter inspection + replay tooling + per-event audit.
  • Webhook simulator usable by tenant integrations dev sandbox.

1.10 Inbound integration plumbing#

  • LMS connector framework (LTI 1.3, LTI Advantage, SCORM where required).
  • OneRoster connector framework with periodic + on-demand sync.
  • Identity connector framework (SAML 2.0, OIDC, SCIM 2.0).
  • Calendar connector framework (Google, Apple, Outlook).
  • Payment connector framework.
  • Telemetry sink connector framework.
  • BYOM ingestion connector framework.
  • Slack/Teams notification sink framework.
  • Connector health probes + circuit breakers + version pinning + upgrade pathways.

2. Customer Surfaces: Web, Mobile, Shared Shell#

2.1 Customer Web (apps/oshun/web)#

  • Implement V1 dashboard at apps/oshun/web/src/app/page.tsx reflecting Tara-centered home model with mixed-domain recommendations and reason labels (suppression rules, "because you saved X" reason taxonomy).
  • Implement multi-panel desktop workspace (continuity, search, reading, evidence inspection, study, notes, assistant) at apps/oshun/web/src/app/(workspace)/.
  • Implement collapsible assistant dock with persistent context handoff from the current screen at apps/oshun/web/src/components/assistant-dock/.
  • Implement mixed-domain recommendations component with reason labels + suppression rules at apps/oshun/web/src/components/recommendations/.
  • Implement domain modules (Tara ritual continuation, Arete weekly review, Veritas grounded briefing, Nyx events, Nisaba passages, Metis study continuation) on the home dashboard.
  • Implement universal search at apps/oshun/web/src/app/search/page.tsx across rituals/practices/concepts/passages/claims/sources/notebooks/ collections/programs/sky-events/courses/lessons/learning-artifacts.
  • Implement advanced filters, result grouping, saved searches, recent searches, assistant-assisted query refinement.
  • Implement split-view reading + compare + source inspection + evidence panels + citation trails + notebook entry points.
  • Implement global command palette (Cmd-K) at apps/oshun/web/src/components/command-palette/: navigation, assistant, search, recent items, creation, agent invocation, jump-to-anything.
  • Implement multi-window/tab support with per-tab continuity, draggable side panels, persistent reading/study tabs, stable deep-link state.
  • Implement hand-off to/from mobile (resumable reading, study, voice sessions, assistant transcripts, notebook sync) using a continuation state shared via Iris memory.
  • Implement multi-format export (PDF/Markdown/JSON), print, share-card, embed flows for stories/claims/passages/lessons/transcripts/ritual scripts/notebook entries — gated on rights metadata.
  • Implement PWA install/update/relaunch, offline shell, recent-content fallback, service-worker caching.
  • Set Lighthouse budgets at apps/oshun/web/lighthouse-budget.json for LCP ≤ 2.5s, INP ≤ 200ms, CLS ≤ 0.1; gate CI on budget breach.
  • Add Playwright coverage for keyboard-only flows, accessibility, visual regression, and resilience for every critical web journey.

2.2 Customer Mobile (apps/oshun/mobile)#

  • Implement phone-first IA: home, domain switching, library, assistant, profile reachable with one-handed use.
  • Implement deep-link routing into all top-level domains and high-value object types.
  • Implement start-of-day and return-session home behaviors with quick actions for meditation, check-in, briefing, tonight, study, assistant follow-up.
  • Implement contextual assistant invocation from primary screens.
  • Implement haptic + motion + transition behavior for major flows.
  • Implement push routing + per-domain/per-persona/per-quiet-hours/ per-sensitivity notification controls.
  • Implement offline + retry support for recent meditations, audio assets, passages, notes, allowed Veritas briefings, shell continuity.
  • Implement mobile continuation cards for Tara/Arete/Veritas/Nyx/Nisaba/ Metis.
  • Implement recovery-after-drift logic for habits, study, routines, interrupted sessions.
  • Implement mobile command surface (search/sheet/quick-action).
  • Implement device hand-off to/from desktop for reading, study, voice, journaling, assistant transcripts.
  • Implement two-way calendar sync (Google/Apple/Outlook) for Tara rituals, Arete reminders, Nyx events, Metis study sessions.
  • Implement camera/microphone/photo-library capture with explicit permissions and per-domain redaction policies.
  • Implement share-extension targets for ingesting URLs/articles/media.
  • Implement lock-screen widgets, watch surface, Live Activity-style controls for active rituals/study/voice tutoring.
  • Add mobile accessibility, crash reporting, performance, battery, memory, caching, device-matrix, mobile E2E coverage.

2.3 Shared Consumer Shell (libs/oshun/shell-*)#

  • Implement shared shell entry points: home, explore, activity, library, notifications, profile, settings, assistant.
  • Implement domain-aware navigation for Tara/Arete/Veritas/Nyx/Nisaba/Metis.
  • Implement current-domain persistence + deep links + route-level analytics + feature flags + experiments + onboarding education.
  • Implement Tara-led home ordering, blended exploration, cross-domain quick actions, mixed-domain recommendations.
  • Implement cross-domain activity timelines with assistant highlights, study/notebook continuation, provenance state, grounding state.
  • Implement library aggregator across meditations/claims/sources/ passages/notebooks/collections/programs/rituals/sky-events/courses/ generated-artifacts.
  • Implement notification center for mixed-domain, admin, support, study, grounding, privacy, safety events.
  • Implement profile/settings: account, billing entry, memory controls, disclosure, privacy, notifications, data export, data deletion, sessions, devices, locale, timezone, personalization.
  • Implement unified command surface in the shared shell (web palette, mobile sheet) for navigation, search, assistant, agent invocation, creation, recent items, and shortcuts, with one source of command registration truth.
  • Implement universal sharing, invite, and referral flows with deep-linkable invitations, per-link permissions, attribution, expiry, revocation, and abuse/rate-limit controls.
  • Implement calendar entry points and two-way sync in the shared shell for Tara rituals, Arete reminders, Nyx events, and Metis study sessions across Google, Apple, and Outlook providers.
  • Implement multi-account switcher with explicit identity indicator and isolation guarantees.
  • Implement in-app changelog, "what's new" feed, contextual help, walkthrough overlays, keyboard shortcut reference, feature education.
  • Implement in-app help center with contextual articles, search, video walkthroughs, feedback capture.
  • Implement in-app feedback/bug-report/feature-request capture with screenshot and trace-id attachment.
  • Implement bookmarks/reading-list/saved-for-later/tasks/queue surface with cross-domain aggregation, smart sorting, due/snooze, resume.
  • Implement unified message center with filters, history, delivery receipts, deep links, snooze, unsubscribe.
  • Implement loading/empty/offline/partial-outage/degraded/retry/ traceable-BFF-partial-response states for every shell surface.
  • Implement banner system for tenant-/region-/feature-scoped status messages with severity, audience scoping, locale, dismissal, accessibility.
  • Implement auth, onboarding, session refresh, re-auth, account recovery, profile sync, cold-start personalization, public-web-to-app conversion.
  • Implement public profiles for opted-in customers/creators/scholars/ teachers with curated artifacts, audience-appropriate disclosure, follow controls, synthetic-content indicators preserved.

2.4 Public Web and Distribution#

  • Build public marketing site at apps/oshun/public-web/ (or extend apps/oshun/legal/ if that is the existing surface) with product positioning, conversion paths, semantic SEO.
  • Implement Open Graph + social sharing metadata + preview assets + public-to-auth funnel tracking.
  • Prepare Apple App Store + Google Play Store submission assets, listing content, screenshots, privacy labels, review prep.
  • Configure Universal Links + Android App Links + TestFlight + Play Store internal/beta + minimum-version + forced-update + external deep-link E2E coverage.

2.5 Assistant Experience (cross-surface)#

  • Implement universal assistant invocation points across customer web, customer mobile, admin web, and Studio surfaces with consistent entitlement, policy, and context guards.
  • Implement screen-to-assistant context handoff: current domain, artifact, selection, evidence state, memory scope, persona identity, disclosure state, and permitted tool grants travel in a typed envelope.
  • Implement assistant transcript and turn-history surfaces with memory-state indicators, grounding-state indicators, persona identity indicators, and disclosure state.
  • Implement text-first, voice-first, streaming, interruption-aware, proactive follow-up, persona-switching, and cross-domain carry-over modes with explicit mode state and fallback state.
  • Implement persona handoffs among teacher, coach, scholar, explainer, moderator, reviewer, and support assistant personas with audit and memory scope boundaries.
  • Implement safe fallback when grounding, memory, persona, real-time, avatar, or downstream subsystem capabilities are unavailable; UI must preserve transcript continuity and expose what degraded.
  • Implement avatar assistant mode where supported with mode switching, fallback, entitlement gating, synchronized disclosure, provenance, and memory-state preservation.
  • Add routing, memory, grounding, persona-state, invocation, source-inspection, voice/text, avatar entry/exit, disclosure, and accessibility tests across customer web, mobile, admin, and Studio.

3. Domain — Tara#

Tara is the experiential center of V1. Audit found ~35% coverage; ritual model and trigger engine are largely missing.

3.1 Canonical models#

  • Implement RitualTemplate model in libs/tara/features/src/ritual-template.ts with steps, triggers, scheduling rules, completion contract.
  • Implement canonical Tara Practice, BreathingSession, Meditation, and TeacherProfile models with lineage, modality, duration, rights, accessibility, and content-taxonomy bindings; export them through the Tara domain adapter and shared contracts.
  • Implement RitualSession aggregate with first-class events: edit, skip, recover, reschedule, pause, resume, complete (each captures timestamp, prior state, new state, reason, consequence).
  • Implement ContinuationState model: per-program multi-session arc, per-teacher continuity, per-theme continuity, prerequisite-respecting next-recommendation.
  • Implement SessionState enum + state machine: not-started → started → paused → drifted (idle ≥ N seconds) → resumed → abandoned → completed → partially-completed (≥ 80% audio counts).

3.2 Taxonomies#

  • Implement Mood taxonomy: anxious, scattered, restless, heavy, low, neutral, curious, joyful, agitated, grieving, fearful, peaceful — each with per-mood recommendation slate + crisis handoff for high-distress.
  • Implement Theme taxonomy: presence, breath, body-scan, lovingkindness, equanimity, gratitude, sleep, focus, awe, perspective, grounding, release, devotion, surrender, courage.
  • Implement Modality taxonomy: silent, guided, breathwork (box, 4-7-8, coherent, alternate-nostril), sound (singing-bowl, drone, mantra), movement, posture, visualization, prayer, devotional reading.
  • Implement Lineage taxonomy with named teachers + scriptural references; cross-lineage syncretism gated to comparative personas only.
  • Implement Duration buckets: micro (≤2 min), short (3–10), standard (11–25), long (26–60), retreat (>60); cadence-tuned recommendations.
  • Implement Context tags: morning, midday, evening, night, pre-meeting, post-stress, transition, sleep-onset, after-conflict, awe-inspired.

3.3 Triggers, scheduling, humane recovery#

  • Implement Trigger engine (libs/tara/features/src/triggers/) with time-of-day, post-event, location-aware (where permitted), calendar- event-derived trigger types.
  • Implement scheduling rules: respect declared quiet hours, respect Lilith crisis frame (no scheduled invitations during crisis), respect cross-domain cadence (no Tara push immediately after a heavy Veritas read), respect user-declared cadence ceiling.
  • Implement humane skip + recovery: missed sessions never accumulate guilt-inducing UI; recovery prompts framed as "today's invitation"; UI never says "you broke your streak."
  • Implement completion event emitter: emits on completion with duration, modality, mood-after, journal capture, continuation-state update.

3.4 Audio, accessibility, save/share#

  • Implement quality-preserving variable-speed playback (0.85×–1.25×) in libs/meditation/player/src/playback-rate.ts.
  • Implement sleep-fade in libs/meditation/player/src/mixer.ts.
  • Implement full transcripts + captions for every guided session.
  • Implement screen-reader-friendly controls + reduced-motion variants + large-text variants.
  • Implement vibration-based pacing alternative for hearing-impaired users where the device supports it.
  • Implement save-to-collection / send-to-friend (with permissions) / download (rights-checked, watermark-preserving) / export-to-journal with reflection capture.
  • Implement resume-from-any-point and resume-across-devices using Iris session memory and Psyche envelope.

3.5 Cross-domain Tara companions#

  • Wire Nisaba passage companion suggestions into ritual completion view.
  • Wire Arete next-step suggestions into ritual completion view.
  • Wire Nyx perspective prompts into ritual completion view.
  • Wire Veritas/Sophia explanatory notes for high-context rituals.
  • Wire assistant follow-ups via Iris memory.

3.6 Tara web and mobile surfaces#

  • Implement Tara web landing, dashboard, immersive session pages, teacher pages, transcript controls, audio controls, save/share/export rules, and recovery states under apps/tara/web and/or the Oshun domain route.
  • Implement Tara mobile quick-start rituals, domain home, journaling, reflection capture, sleep/downshift flows, quick resets, offline recent audio, and mobile completion under apps/tara/mobile and apps/oshun/mobile.
  • Add UI integration tests proving Tara domain surfaces use the canonical session state, audio accessibility, save/resume, rights, and companion wiring rather than local mock state.

3.7 Safety and tone#

  • Wire Lilith contemplative-tone-rubric review on every authored ritual script, gating publish.
  • Wire Lilith crisis handoff for high-distress mood inputs (anxious + grieving + fearful patterns + crisis classifier signal).
  • Add session-state, save/resume, audio-accessibility, web E2E, mobile E2E test suites under apps/tara/{web,mobile}/e2e/.

4. Domain — Arete#

Audit found ~70% coverage; schema and habit-loop logic strong, but humane-streak UI, friction interventions, and cross-domain wiring are missing.

4.1 Schema completeness#

  • Verify and extend libs/arete/core/src/db-schema.ts so Habit, Goal, Routine, CheckIn, Journal, Plan, CoachingSummary, Streak, MissedDay, Friction, Intervention, Recovery records align exactly with the Zod contracts in libs/contracts/src/arete/.
  • Implement CheckIn.status semantics enforcement (done/partial/skip/ decline/miss) at the API layer; route handlers must validate and route accordingly.

4.2 Humane streak and recovery#

  • Implement no-shame streak floor: UI never displays "you broke your streak." Replace any such copy with empathy-framed alternatives.
  • Implement grace windows: 24 h on daily, 72 h on weekly cadence — no visual change until grace expires.
  • Implement recovery prompt ladder: 1 missed → gentle invitation; 3 → recovery content (Tara recovery practice + Arete plan re-scope); 7 → deep re-engagement flow with goal re-evaluation.
  • Implement plan re-scoping assistant: after pattern of missed days, offer to lower difficulty or shrink scope; user always in control.
  • Implement drift detection: pattern of missed days flagged to user with empathy framing and into coaching summary; never to leaderboards/social.

4.3 Friction signals and interventions#

  • Implement friction signals: time-of-day mismatch, mood-incompatible cadence, external-event collision (Nyx event, calendar collision), cognitive-load proxy (recent Veritas/Metis intensity), declared sensitivities.
  • Implement intervention dispatcher: notification re-timing, plan re-scoping, alternative-habit suggestion, accountability check-in, breakwork insert, Tara ritual surfacing, weekly review prompt.
  • Implement pattern analysis dimensions: time-of-day, day-of-week, mood correlation, habit-interaction, seasonality, location, post-event.

4.4 Coaching summary and weekly review#

  • Implement weekly-review structure: celebrate / notice / choose / invite.
  • Implement coaching-summary card: weekly synthesis with celebrated wins, observed patterns, suggested adjustments, invitation (not prescription).
  • Implement weekly-review cadence (Sunday evening default); skipping is itself logged but never penalized.
  • Implement continuity card and next-practice recommendations rendered from the weekly review output.
  • Wire Tara recovery rituals to surface on missed days.
  • Wire Nisaba reflection passages to surface on stuck patterns.
  • Wire Veritas habit-science explainers to surface on declared interest.
  • Wire assistant accountability with explicit consent.
  • Wire shared concept-graph theme alignment.

4.6 Web, mobile, and export surfaces#

  • Implement Arete mobile daily check-in, goals, routines, recovery, accountability, and progress surfaces with humane-streak copy enforced in rendered UI.
  • Implement Arete web plan/review workspace with journaling, reflection, progress maps, pattern analysis, weekly review, and continuity cards.
  • Implement coaching summary cards, save/share/export behavior, and next-practice recommendations with rights and privacy gating.
  • Add Playwright/mobile E2E tests for daily check-in, recovery prompt ladder, weekly review, export, and cross-domain recommendation flows.

4.7 Tests#

  • Add tests for streaks, recovery, plan state, persistence, charts, accessibility, weekly-review, daily-check-in, recovery flows under apps/arete/{web,mobile,api}/e2e/ and libs/arete/*/__tests__/.

5. Domain — Veritas#

Audit found ~50% coverage. Confidence-band, counterclaim, retraction cascade, and trust display are largely missing.

5.1 Trust, confidence, and counterclaim model#

  • Implement source quality model: per-source bands (high/mixed/low/ contested) with composite scoring (peer-review status, primary-vs-secondary, editorial standards, retraction history, expertise match, recency, rights/license clarity); per-source reviewer attestation captured.
  • Implement claim-confidence composite: source quality × source count × source diversity × extraction confidence × contradiction presence, surfaced as bands well-supported / supported / emerging / contested / unsupported / retracted.
  • Implement counterclaim representation: per-claim list of counterclaims with source quality and counterclaim confidence; rendered as inspectable side-by-side; never silently hidden.
  • Implement trust/confidence display labels with hover/tap-to-inspect, consistent visual language across web, mobile, and assistant; no raw numerical scores presented without context.

5.2 Story, topic, timeline schema#

  • Extend Story schema with editorial-state and persona-binding (explainer voice).
  • Implement TopicHub: declared scope, story list, claim aggregate, key sources, timeline, counterclaim aggregate, lineage of coverage.
  • Implement Timeline: ordered events with source attribution, contested events flagged, retroactive corrections marked.

5.3 Update, correction, retraction#

  • Implement update events: new-evidence, retracted-source, contested-claim, new-counterclaim, corrected-claim — each with timestamp, rationale, reviewer.
  • Implement user-visible correction notes: when a prior public claim is updated, surface the change to readers who saw the prior version.
  • Implement story-update notifications: per-user, per-tenant, per-followed-topic; respect notification preferences.
  • Implement re-grounding cascade: when a source retracts, every dependent story, claim, and explainer is re-grounded; downstream Metis lessons re-validated; user-facing retraction notice surfaced.

5.4 Surfaces#

  • Implement web story page with evidence sidebar, claim detail page, source inspection, counterclaims, topic hub, timeline at apps/oshun/web/src/app/domains/veritas/story/[id]/page.tsx (verify and extend the existing story route).
  • Implement mobile explainers + follow-up flows under apps/oshun/mobile/src/screens/veritas/.
  • Implement save/follow controls for stories, claims, topics.
  • Implement inspect-source / inspect-evidence interactions backed by Sophia evidence bundles.
  • Wire Nisaba source-lineage links from Veritas sources.
  • Wire Tara "metabolize this information" practice suggestions.
  • Wire Arete next-action suggestions.
  • Wire assistant explainers that expose source inspection.

5.6 Tests#

  • Eval coverage: grounded explainer correctness, unsupported claims, citation integrity, trust/confidence display, story-to-source nav, web/mobile evidence inspection.

5.7 Source-quality scoring algorithm#

  • Implement composite source-quality scorer at libs/oshun/domain-veritas/src/source-quality/composite.ts taking peer_review_status, primacy, editorial_standards, retraction_history, expertise_match, recency, rights_clarity, independence, cross_corroboration → weighted geometric mean per features.md.
  • Implement per-claim-domain weight tables (e.g., medical claims weight peer_review_status + cross_corroboration higher than recency); weights are versioned and rollback-safe.
  • Implement deterministic banding thresholds on the composite + hard-overrides (recent retraction drops band; unattributed capped at low).
  • Persist the full score vector with every Source revision so band assignments are reconstructable.
  • Implement cadence-driven re-scoring (default weekly + on-demand on correction / retraction / cross-corroboration update).
  • Implement per-tenant tighten-only floor (institutional tenants can raise the composite floor; never lower it below platform minimum).
  • Tests: same vector → same composite + band; per-domain weight tables honored; hard-overrides fire; cadence + on-demand re-scoring; tenant tighten-only enforcement.

5.8 Expert attestation workflow#

  • Define ExpertAttestor Zod contract at libs/contracts/src/veritas/attestor.ts with {id, displayName, credentialsBundle, declaredExpertiseDomains, conflicts, institutionalAffiliation, attestationHistory, suspensionState}.
  • Implement credential verification at registration: degree verification, professional license number lookup, institutional email round-trip, peer-attestation chain. Operator review mandatory.
  • Implement probation window for new attestors before consequential attestations are admissible.
  • Implement attestation scopes (Source / Claim / Counterclaim) with declared validity windows; expired attestations soft-degrade the source band.
  • Implement conflict auto-flag: incompatible conflicts route to reviewer-board approval before the attestation counts.
  • Implement disagreement surfacing: attestor disagreement auto-bands the claim as contested and emits the disagreement-detected editorial event.
  • Implement revocation: attestor-initiated revocation fires re-banding and a retraction-cascade pass.
  • Audit every attestation event (issued / renewed / withdrawn / expired / overridden) with rationale.
  • Tests: credential-verification gating, conflict auto-route, disagreement → contested banding, revocation cascade, probation enforcement.

5.9 Counterclaim-balance rules#

  • Implement counterclaim-surfacing classifier at libs/oshun/domain-veritas/src/counterclaim/surface.ts evaluating the four surfacing conditions per features.md (own evidence pack at band floor; independence from primary; substantive disagreement; contemporary).
  • Implement false-balance brake: when primary is high and counterclaim composite is low plus consensus exceeds the configurable threshold, suppress co-equal surfacing and offer a "minority view exists" affordance.
  • Implement mandatory-surface override list (direct retraction-class disagreement; public-safety relevance; pluralism-declared editorial categories).
  • Implement per-reader controls (always show counterclaims, suppress minority-view expands); honor reader preferences.
  • Audit every surfacing decision with the rule applied + composite scores at decision time.
  • Tests: substantive surfacing fires; false-balance brake suppresses; mandatory overrides fire; per-reader preferences honored.

5.10 Topic-hub composition#

  • Implement topic-hub composer at libs/oshun/domain-veritas/src/topic-hub/composer.ts producing ranked candidates for the six layout sections (latest, key facts, under dispute, corrections, background, timeline).
  • Implement editorial gating: every algorithmic candidate enters the editorial state machine before surfacing.
  • Implement event-triggered refresh (new story, retraction, attestation expiry, new cross-corroboration) + cadence-floor refresh.
  • Implement per-locale hub variants with shared topic anchor and locale-specific ordering.
  • Tests: candidate ranking determinism; editorial gating enforcement; refresh trigger coverage; localization parity.

5.11 Retraction-cascade UX#

  • Implement story-page retraction banner with rationale, corrected-source link, and "remove from library" affordance.
  • Implement saved-claim banner + notebook-level notice with per-citation drill-down.
  • Implement kept Veritas Living Offering banner with re-render offer.
  • Implement severity-gated notification (silent / banner-only / notification-included) using the same Lilith quiet-hours + sensitivity rules.
  • Implement reader recourse ("appeal / correct us") routing to support; editorial triage UX.
  • Implement tenant variant: institutional tenants can require notification-including cascade for any retraction touching tenant-published content.
  • Tests: each dependent surface receives the correct banner severity; appeals route correctly; tenant variants applied.

5.12 Contradiction-detection loop with Sophia#

  • Implement contradiction probe trigger on new claim, source update, attestor disagreement, operator flag.
  • Implement Sophia probe call via @oshun/evidence-sophia returning ranked supporting / contradicting / neutral pairs with confidence.
  • Implement reviewer routing for above-threshold contradictions: merge / split / surface-as-contested / dismiss decision tree.
  • Implement continuous monitoring (cadence + on-refresh); new contradictions surface to the queue without silent mutation of reader surfaces.
  • Implement per-tenant time-box (research labs require same-day triage on contradicting peer-reviewed sources).
  • Tests: probe accuracy; reviewer routing fires above threshold; tenant time-box enforcement.

5.13 Veritas editorial state machine#

  • Implement the editorial state machine at libs/oshun/domain-veritas/src/editorial/state-machine.ts with Veritas-specific states (verifying_sources, awaiting_attestation, contradicts_existing, counterclaim_pending) layered on the generic editorial lifecycle.
  • Implement transition gates: every gate enforced; blocking branches must resolve before publication.
  • Implement audit append on every transition with reviewer, rationale, source references, attestation references, and (for retracted / corrected) cascade scope.
  • Tests: every gate enforced; awaiting_attestation, contradicts_existing, counterclaim_pending block publication until resolved; replay reconstructs every decision.

6. Domain — Nyx#

6.1 Event taxonomy completeness#

  • Implement meteor-shower events with peak windows in libs/nyx/events/.
  • Implement eclipse events: solar partial/total/annular, lunar partial/ total/penumbral.
  • Implement conjunction events: planet-planet, planet-moon, planet-star.
  • Implement occultation events.
  • Implement transit events.
  • Implement comet apparition events.
  • Implement aurora forecast events backed by NOAA SWPC integration.
  • Implement ISS and bright-satellite pass events.
  • Implement supermoons, equinoxes, solstices, cross-quarter days.
  • Implement peak-visibility windows for deep-sky objects.

6.2 Observation window quality#

  • Implement quality-band scoring (excellent/good/fair/poor/not-visible) from latitude/longitude/elevation × Bortle band × astronomical twilight × cloud cover forecast × weather forecast.
  • Wire NASA JPL ephemerides + IMO meteor predictions + IERS time data + NOAA SWPC + weather provider + light-pollution dataset; persist version, license, attribution, freshness per source.

6.3 Calendar and reminders#

  • Implement per-event calendar entry with location-aware peak time; reminder cadence per user preference.
  • Implement two-way calendar sync (Google/Apple/Outlook).
  • Implement save / follow-event-class / set-reminder-cadence (peak only, evening-of, week-before, none) with per-channel routing.
  • Persist user save/follow/remind state.

6.4 Cross-domain companions#

  • Wire Tara perspective recommendations (awe practices, perspective meditations, night-sky-themed reflections) to Nyx events.
  • Wire Nisaba cosmology overlays (cultural cosmology references, cross-tradition mappings).
  • Wire Veritas grounded explainers with source-set citations and retracted-source handling.
  • Wire assistant evening-narration voice mode with location-aware visibility framing.
  • Wire concept-graph linking (phenomena ↔ named events ↔ teacher references ↔ practice prescriptions).

6.5 Web, mobile, and assistant surfaces#

  • Implement Nyx web event pages, sky chart or event-detail integrations, save/follow/remind actions, and event calendar entry points.
  • Implement Nyx mobile nightly highlights and compact observation companion surfaces with location-aware visibility, offline/degraded states, and accessibility audio descriptions.
  • Implement assistant explainers for sky events and concepts with location-aware framing, source citations, and retracted-source handling.

6.6 Tests#

  • Tests for event formatting, time logic, save/follow/remind flows, web event details, mobile nightly highlights, reminders.

7. Domain — Nisaba#

7.1 Web reading workspace#

  • Verify libs/nisaba/workspace/ covers: web landing, dashboard, reading workspace, edition comparison, translation comparison, manuscript viewing, annotations, highlights, concept-graph exploration, lexicon panels, morphology panels, timelines, influence networks.
  • Implement notebooks, collections, study plans, citations, exports.
  • Implement scholar/expert mode at libs/nisaba/workspace/src/scholar-mode/.

7.2 Mobile reading and study#

  • Implement domain home, reading queue, daily-passage, compact highlight flow, annotation flow, quick compare, glossary lookup, morphology lookup, saved manuscripts/editions, study reminders.
  • Implement assistant-assisted explanation with inspectable citations.

7.3 Study plans and scholar mode#

  • Create libs/nisaba/study-plans/ library with creation, sequencing, and learner tracking.
  • Create scholar profile + credentials system with attribution preferences and disclosure controls.
  • Wire passage companions for Tara.
  • Wire study plans into Arete.
  • Wire source depth into Veritas.
  • Wire cosmology overlays into Nyx.
  • Wire shared concept-graph linking.
  • Wire domain-to-domain recommendations.

7.5 Tests#

  • Tests for adapter mapping, filters, passage save, annotate, notebooks, reading, compare, annotation, daily passage, highlight, accessibility, large-text performance.

8. Domain — Metis#

Metis is launch-blocking V1 scope. Earlier audit found extensive gaps: standards integrations, mobile learner-surface behavior, BYOM pipeline, IRT/DIF, prerecorded lecture, live voice tutoring, and avatar teacher operation all need implementation-level verification rather than file-presence checks.

Subject-matter scope: Metis lessons concentrate heavily on philosophy, religion, psychology, neuroscience, anthropology, and astronomy — the disciplines that converge on the human mind, meaning, belief, behavior, culture, and our place in the cosmos. STEM and other domains (mathematics, physics, the natural sciences, computing, history, the arts, languages) are first-class supporting subjects, taught where they illuminate or interlock with the core six. Tasks below MUST honor this positioning: discipline-specific safety, reviewer-pool, gold-set, and curriculum-coverage work in §8.13 applies to the core six; supporting subjects appear as scaffolding rather than as headline curriculum.

8.1 BYOM ingestion#

  • Implement BYOM ingestion pipeline at libs/metis/integrations/src/byom/ handling files, URLs, feeds, LMS imports, source bundles.
  • Implement extraction: text, structure, citations, metadata, licenses, parser/OCR confidence, errors, source quality.
  • Implement source scoping at notebook / workspace / course / institution level.
  • Implement source approval workflow before high-stakes course generation, tutoring, or publication.
  • Implement source refresh, version diffs, downstream invalidation, provenance retention.
  • Implement LMS importers, hybrid retrieval, graph-aware retrieval, notebooks, source-to-course workspace flows.

8.2 Tutor runtime#

  • Verify Socratic mode in libs/metis/agents/src/agents/tutor-agent.ts conforms to spec (open-ended scaffolding, ladder, learner-led pace, rubric-aligned probing, no direct-answer delivery).
  • Implement direct-explanation mode (worked example, required citations, glossary terminology links).
  • Implement scaffolded-hints mode (graduated hint ladder with per-hint cost tracked against assessment evidence).
  • Implement worked-example mode (stepwise solved problem, learner pause/ rewind, alternative approaches surfaced, common errors anticipated).
  • Implement practice mode (item delivery aligned to mastery, calibrated item bank, time tracking, formative-vs-summative gates).
  • Implement review mode (re-presentation of missed items, spaced retrieval, prerequisite recovery, mastery re-check).
  • Implement mode-switching policy (learner-initiated, teacher-policy- initiated, performance-triggered) with switch logged in tutor session memory.

8.3 Academic integrity#

  • Implement mode declarations (assessed / formative / practice / exam / collaborative) per assignment, per institution policy.
  • Implement mode enforcement (allowed actions surfaced; prohibited actions blocked with messaging; off-mode requests refused with redirect).
  • Implement detection signals: paste from external source, off-platform search, response patterns inconsistent with prior work, classifier- based generated-text detection, tutor-output presence in submission, abnormal pace.
  • Implement verdict classes (clear / inconclusive / policy-violation / severe-violation).
  • Implement adjudication routing to Themis via the AcademicIntegrityVerdict contract; institutional policy binding; appeals workflow; teacher override with rationale.
  • Implement audit capturing detection signals, classifier output, model versions, evidence excerpts, decision rationale, appeal path.

8.4 Misconception graph#

  • Verify graph construction from item-response data, learner errors, expert annotation, curriculum-sourced known misconceptions.
  • Implement misconception node schema (text, prerequisite-skill links, diagnostic-item links, remediation-resource links, prevalence, age-band).
  • Wire misconception graph into tutor (anticipate likely errors, target diagnostic items, select remediation).
  • Implement drift management: per-cohort and per-locale prevalence tracking; outdated misconceptions retired; new ones promoted via expert review.
  • Tests: graph integrity, diagnostic-item coverage, remediation coverage, prevalence freshness, locale parity.

8.5 Mastery and item calibration#

  • Implement per-skill, per-learner mastery state with confidence interval, evidence count, recency, prerequisite state.
  • Implement IRT calibration (1PL/2PL/3PL configurable per domain) with held-out re-calibration cadence.
  • Implement differential item functioning (DIF) monitoring per demographic slice; flag and re-calibrate or retire.
  • Implement adaptive sequencing: next-item selection optimizing mastery- information gain, prerequisite chain, fatigue/motivation signals.
  • Implement evidence aggregation per skill → learning objective → course → standards alignment.
  • Implement learner-facing mastery cards, teacher-facing cohort heatmap, institutional-facing standards-alignment dashboard.

8.6 Standards and institutional delivery#

  • Implement LTI 1.3 / LTI Advantage: tool launch, deep linking, names-and-roles service, assignment-and-grade service, with secure-token exchange. Launch-blocking.
  • Implement OneRoster rostering with conflict reporting and dry-run.
  • Implement xAPI / cmi5 per-statement learner activity logs with stable object identity, replayable, queryable.
  • Implement SCORM legacy fallback for institutional LMS without LTI/xAPI.
  • Implement QTI 3 assessment item exchange with item-bank import/export.
  • Implement Caliper standardized analytics events for institutional consumers.
  • Implement CLR / Open Badges credential issuance with verifier endpoints.
  • Add per-LMS interop matrix tests with drift monitoring.

8.7 Knowledge graph promotion#

  • Implement entity resolution + relation extraction in libs/metis/knowledge-graph/.
  • Implement validation, cycle detection, orphan detection.
  • Implement prerequisite visualization and graph-backed recommendations.
  • Implement course sequencing from KG.
  • Implement credibility scoring + source diversity + retrieval inspection + freshness + invalidation.
  • Implement GraphRAG-style benchmarking suite.
  • Implement rights filters and algorithm-docs surface.

8.8 Multimedia learning surfaces#

  • Implement prerecorded lecture generation (TTS, slide assembly, captions, transcripts) at libs/metis/multimedia/src/lecture-generation/.
  • Bring live voice tutoring runtime online (currently marked unavailable in libs/metis/integrations/src/psyche-canonical-wiring.ts).
  • Implement avatar teacher synthesis pipeline (consent-bound, lip-synced, expression-coherent) wired to Lilith policy + Isis release gates.
  • Implement multilingual narration + dubbing + captions + transcript generation with locale fallback.
  • Implement fallback chain: avatar → voice → text with user-visible disclosure at each stage.

8.9 Surfaces#

  • Implement Metis mobile app at apps/metis/mobile/ (currently missing).
  • Implement learner web/mobile surfaces: browse, course detail, course play, study, tutor, assessments, authoring (where in scope), saved courses, study queues, recent sessions, resume state, learner profile, goals, pace, preferences, reminders, exports, downloads, sharing.
  • Implement loading/empty/offline/degraded/partial-failure states.
  • Implement grounded source inspection anywhere Metis renders educational claims or generated content.

8.10 Cross-domain flows#

  • Wire Tara reflection-to-course flows.
  • Wire Arete goal-to-Metis-study flow.
  • Wire Veritas story-to-Metis-explainer flow.
  • Wire Nyx event-to-Metis-mini-course flow.
  • Wire Nisaba passage-to-Metis-study flow.
  • Wire Aja embodied-instruction hooks for movement/practice-based pedagogy.
  • Wire Sophia grounding everywhere educational claims render.
  • Wire Isis prompt/model/workflow control for course generation.
  • Wire Lilith pedagogical tone enforcement.
  • Wire Iris continuity for resumable study.
  • Wire Psyche real-time tutoring runtime.
  • Wire Yemaya rendering for media surfaces.
  • Wire Themis for academic-integrity adjudication.

8.11 Agent runtime#

  • Implement discoverable agent registry, versioned capabilities, orchestration DAGs or event bus, durable build IDs, replayable evidence (see Section 18 — share infra).
  • Implement synthetic/fabricated research blocking, claim extraction, query decomposition, verifier orchestration, adjudication, rollback, kill switches, safe degradation.
  • Implement threat screening, trust zoning, tool isolation, adversarial evaluation.
  • Implement versioned gold sets, annotation rubrics, privacy-preserving data handling.
  • Implement shadow/canary/champion-challenger rollout.
  • Implement graph indexing + community summaries.
  • Implement symbolic/code/numeric verification where applicable.

8.12 Tests#

  • Playwright, mobile/responsive, Python backend, contract, permissions, integration, load, latency, failure-mode, grounding, citation, pedagogy, source-ingestion, adversarial, drift, interoperability, release-gate coverage.

8.13 Subject-matter focus and curriculum scope#

  • Define LearningSubjectTaxonomy v1 marking the core six disciplines (philosophy, religion, psychology, neuroscience, anthropology, astronomy) as headline subjects, and the supporting subjects (mathematics, physics, biology, chemistry, computing, history, the arts, languages, social studies) as scaffolding-only by default.
  • Implement subject-matter routing in the tutor and course-generation pipelines: core-six requests get headline treatment (long-form curriculum, full prerequisite graph, advanced rubrics); supporting-subject requests get scaffolding treatment (referenced from core lessons or offered as foundational primers, never headline programs).
  • Build per-discipline curriculum seed packs for each core discipline, each containing subfield ontology, prerequisite graph, canonical concept set, canonical-text reading list, common-misconception bank, worked- example library, and reference scope-and-sequence at three depth tiers (introductory, intermediate, advanced).
  • Build per-discipline standards mappings: philosophy (IB Theory of Knowledge, university curriculum reference frames), religion (AAR religious-studies standards, AP World comparative-religion), psychology (APA Undergraduate Major Guidelines, AP/IB Psychology), neuroscience (SfN core concepts, MCAT foundations), anthropology (AAA core competencies), astronomy (IAU education framework, AP Physics 2 / Astronomy, NGSS Earth-and-Space).
  • Implement religion safety policy: comparative-not-dogmatic stance, equal treatment across traditions, no proselytizing or denigration, sacred-name and sacred-text handling conventions, abstention on contested metaphysical-truth claims.
  • Implement neuroscience safety policy: no medical diagnosis or treatment recommendations, neuromyth detection and correction, clear labeling of established findings vs replication-pending findings vs speculation.
  • Implement psychology safety policy: no clinical diagnosis or therapy delivery, crisis-handoff into the safety system, clear separation of clinical / social / cognitive / developmental / personality subfields, replication-pending labels surfaced to learners.
  • Implement anthropology safety policy: cultural-respect framing, insider/outsider perspectives labeled, avoidance of evolutionary-progress framings, living-tradition consent considerations.
  • Implement philosophy safety policy: argument-not-authority framing, charitable interpretation, clear separation of descriptive and normative claims, explicit treatment of contested positions without false neutrality.
  • Implement astronomy safety policy: rejection of fringe cosmology and astrology-as-science, clear separation of established physics from current research and speculation, scale and uncertainty surfaced explicitly.
  • Build per-discipline expert reviewer pools wired into the Metis content- review workflow: minimum two reviewers per discipline at launch, named credential requirements per discipline, conflict-of-interest disclosures, rotation and quorum rules.
  • Build per-discipline gold sets for grounded-answer evaluation, tutor- pedagogy evaluation, and assessment-item calibration: minimum coverage targets per discipline tracked in a release-gate dashboard; gold-set authorship credited to the reviewer pool.
  • Implement per-discipline DIF and fairness slicing in the assessment pipeline: locale, language, age band, and (where consented) demographic slices; flag items for re-calibration or retirement when DIF crosses thresholds.
  • Define release-gate coverage minimums per core discipline before V1 launch: minimum approved courses, minimum approved assessment items, minimum reviewer-pool size, minimum gold-set coverage, minimum supporting-subject scaffolding hooks. Block the Metis V1 launch gate until each of the core six clears its minimums.
  • Build a cross-core interlock catalog describing canonical cross- discipline pairings the platform actively curates: philosophy ↔ neuroscience (philosophy of mind, free will, consciousness), religion ↔ anthropology (comparative religion, ritual studies), psychology ↔ neuroscience (cognitive science, behavioral neuroscience), astronomy ↔ philosophy (philosophy of cosmology, scale and meaning), anthropology ↔ psychology (cultural psychology), religion ↔ psychology (psychology of religion). Each interlock gets its own gold-set sample and review.
  • Implement onboarding and discovery copy in the Metis shell that reflects the sweetspot: home, browse, course detail, and empty states surface the core six prominently and frame supporting subjects as scaffolding for them, not as standalone destinations.
  • Implement discipline-specific glossaries and concept graphs wired into Sophia grounding and Metis tutor: each core discipline owns a seeded concept graph referenced by retrieval, citation, and misconception detection.
  • Tests for taxonomy enforcement, core-vs-supporting routing, discipline-specific safety policies, reviewer-pool quorum, gold-set coverage thresholds, DIF slicing, release-gate enforcement, interlock catalog rendering, onboarding copy, glossary integration, drift in discipline-specific gold sets, and adversarial probes (neuroscience → medical-claim leakage, psychology → clinical-diagnosis leakage, religion → proselytization leakage, astronomy → astrology-as-science leakage, anthropology → ethnocentric-framing leakage, philosophy → false- neutrality leakage).

8.14 Mastery transition model#

  • Implement banded mastery state at libs/metis/learning/src/mastery/bands.ts with the ordered bands unintroduced · introduced · developing · approaching · mastered · maintaining per features.md.
  • Implement per-band evidence-vector requirements (item_count, difficulty distribution, distinct_contexts, recency_window, prerequisite_band_floor); partial fit surfaces as developing rather than silent advancement.
  • Implement half-life decay for mastered → approaching with per-objective half-lives declared in objective metadata; slower decay in maintaining.
  • Implement recovery-path sequencing on demotion: tutor prioritizes prior-band items before re-attempting advancement.
  • Implement per-tenant override (tighten only); platform minimum preserved.
  • Implement MasteryTransition record persistence with evidence vector, items consumed, time elapsed, actor.
  • Tests: deterministic transitions across synthetic evidence timelines; decay correctness; recovery-path sequencing; override tightening only; transition records complete.

8.15 Personalization manifold#

  • Define LearnerPersonalizationState Zod contract per (learner, course) with axes pace, modality, prerequisite_path, scaffold_density, framing_register, cultural_and_lineage_frame.
  • Implement axis-update cadences per features.md (item-level for pace + scaffold_density, session-level for modality + framing, arc-level for prerequisite_path + cultural frame) and the cadence-precedence rules (slow gates fast).
  • Implement signal-to-axis mapping (response correctness pattern, time-on-item, hint usage, dropout points, consented mood-after, declared preferences, mastery band changes, Arete friction).
  • Implement versioned LearnerPersonalizationState with rollback to any prior version.
  • Implement "how we're teaching you" learner-profile surface with per-axis rationale and pin/loosen/reset controls.
  • Tests: signals at the right cadence; cadence precedence enforced; rollback determinism; profile-surface accuracy.

8.16 Adaptive loop sequencing and latency#

  • Implement the per-item adaptive loop at libs/metis/tutoring/src/loop/: present → collect → evidence-build → mastery-update → personalization-update → integrity-scan → next-item-select → emit-telemetry.
  • Enforce P95 response-to-next-item ≤ 600 ms; backpressure degrades to "loading next item" UX.
  • Implement replayability: each item turn reconstructible from AssessmentEvidencePack + prior mastery state + personalization vector.
  • Implement cross-domain hooks: Tara recovery rituals on documented frustration; Arete plan re-scope on documented drift; Sophia grounding for educational claims in tutor utterances.
  • Tests: latency budget enforcement; replay determinism; cross-domain hook triggers; failure-mode logging without loop block.

8.17 Themis adjudication mechanics#

  • Implement signal taxonomy at libs/themis/src/signals/ with paste_external · offplatform_search · response_pattern_anomaly · generated_text_classifier · tutor_output_in_submission · pace_anomaly · device_fingerprint_change · proctor_observation · peer_collaboration_breach · teacher_flag; each carries confidence, evidence excerpt, detector version, timestamp.
  • Implement calibrated classifier policy per assessment mode (assessed, formative, practice, exam, collaborative) outputting verdict class + severity score.
  • Implement severity → action map per features.md per-mode and per-tenant policy; affirm soft-flag → human re-review → consequence chain.
  • Implement appeals workflow: contest path, different-operator re-review, verdict outcome affirmed | revised | overturned with rationale.
  • Implement bias/fairness monitor: per-slice differential outcomes where tenant policy permits; flagged disparities pause classifier and route to operator review.
  • Persist verdicts to AcademicIntegrityVerdict (TODOS § 1.2) with full audit chain.
  • Tests: per-mode severity-action correctness; appeals round-trip; bias-monitor pause behavior; tenant tighten-only policy; audit completeness.

8.18 BYOM safety surface#

  • Implement BYOM onboarding flow at libs/shared/inbound-integrations/src/byom.ts requiring platform- operator approval with declared metadata (provider, capability, rate-limit, residency, audit hook, abuse-reporting contact).
  • Implement per-tenant sandbox: no shared keys, no shared context, no cross-tenant routing, hard timeout, per-call audit, full request/response logging per tenant retention.
  • Implement policy interlock: BYOM calls pass through Lilith tone policy, Isis governance, Sophia grounding; tenants can tighten only.
  • Implement per-tenant abuse-pattern monitors (rates, content categories, targeting); flip endpoint to quarantined on detection and route to tenant + platform operators.
  • Implement kill-switch (platform + tenant) with fail-closed semantics; fallback only with explicit tenant policy opt-in.
  • Implement onboarding + cadence safety-eval set; tenant-maintained regression fixture set required.
  • Tests: sandbox isolation (cross-tenant non-leakage); kill-switch ≤ 5 s; quarantined endpoints fail closed; tighten-only enforcement; abuse monitor coverage.

8.19 Institutional gradebook contract#

  • Define GradebookEntry Zod contract at libs/contracts/src/metis/gradebook.ts with score, score_scale, score_basis, mastery_band_at_emission, assessment_mode, integrity_verdict, evidence_pack_ref, timestamp, tenant_binding.
  • Implement emission triggers: assignment completion, mastery transition (when gradable), integrity verdict change.
  • Implement LMS integration via LTI Advantage AGS where wired; xAPI / cmi5 / Caliper / file export fallbacks.
  • Implement idempotent versioning + gradebook.correction event emission on late revisions; LMS receives latest version, audit preserves all.
  • Implement per-tenant visibility rules (learner / teacher / guardian / institutional admin); evidence packs linkable only by authorized scope.
  • Tests: per-LMS interop matrix; emission idempotency; correction cascade; late-grade replay; visibility-rule enforcement.

9. Sophia — Grounding#

Completion audit verified the grounding contracts, retrieval stack, fact-checking and contradiction loops, unsupported-claim handling, publication gates, customer/admin surfaces, evaluation gates, and ingestion lifecycle paths are implemented with targeted automated coverage.

9.1 Evidence and citation contracts#

  • Implement SourceSet (versioned, scoped, rights-aware bundle of approved sources per notebook/workspace/course/tenant/global) with hash, version, last-checked, freshness window, rights metadata, license, retraction state.
  • Implement EvidencePack (ordered list of source references with locator granularity — chapter/paragraph/sentence/page/timecode — plus claim attribution, retrieval-vs-synthesis label, confidence score, reviewer attestation).
  • Implement CitationTrail (per-output ordered citation list with stable IDs, click-through, visible diff if source updated since citation).
  • Implement GroundedAnswerEnvelope (prompt + retrieved passages + retrieval method + tool calls + generated answer + claim list + citation map + abstention flag + confidence signal).
  • Implement explicit per-answer GroundingState (grounded / partial / ungrounded / abstained / retracted-source) and surface to UI.
  • Implement fallback contract for ungrounded responses (text-only with disclaimer, deferred answer, abstention).

9.2 Retrieval methods#

  • Implement BM25 lexical retrieval at libs/sophia/semantic-search/src/bm25/.
  • Implement embedding (dense) retrieval (verify in libs/sophia/embeddings/).
  • Implement hybrid retrieval orchestrator combining BM25 + dense.
  • Implement graph-aware retrieval (concept-graph traversal).
  • Implement structured retrieval (SQL/KG).
  • Implement tool-mediated retrieval (web fetch, source-store fetch).
  • Implement hierarchical retrieval (summary → detail).
  • Label every retrieval by method, query decomposition step, source-set scope, provenance.
  • Label every claim retrieved-vs-synthesized-vs-model-only.
  • Enforce source-set scoping: cross-set leakage is a hard fail; tenant scopes enforced.
  • Implement freshness windows + retraction feed + automatic invalidation cascade to derived artifacts.

9.3 Fact-check loop#

  • Implement claim-extraction → claim-normalization → independent retrieval (different method than initial) → claim-to-source matching → confidence scoring → unsupported flag → resolution (cite/hedge/ refuse/escalate) at libs/sophia/verification/src/fact-check-loop/.
  • Implement termination states: pass, partial (cite with hedge), unsupported, contradicted (route to contradiction loop).
  • Implement latency budgets: assistant interactive ≤ 6 s P95, deep-research ≤ 90 s P95, batch publication run ≤ N min.

9.4 Contradiction loop#

  • Implement contradiction detection → claim alignment → source-quality scoring → counterclaim record creation → resolution (prefer-source / surface-both / hedge / refuse / escalate-to-expert).
  • Render counterclaims as inspectable side-by-side in the customer UI.
  • Audit every contradiction event with retrieved sources, resolution, reviewer if any, downstream invalidation.

9.5 Unsupported-claim loop#

  • Implement detection (no source above support threshold; claim contradicts source set; policy-restricted; references non-existent source).
  • Implement resolution (rewrite-to-remove / replace-with-hedged / abstain / surface-as-missing-evidence / route-to-operator).
  • Implement synthetic-citation prevention: hard block on citing a source whose ID is not in the source set; hard block on citing a passage that does not exist; per-citation hash check against source store.

9.6 Orchestration, checkpoints, publication gates#

  • Implement job envelope (input prompt, mode, source set, persona/tone, grounding strictness, mandatory checkpoints, evidence-pack target).
  • Implement mandatory human checkpoints by surface: Veritas story publication, Nisaba edition release, Metis course publication, Tara teacher script release, Sophia grounded report publication, large blast media release.
  • Implement operator workbench at apps/sophia/admin/ showing live job state, plan/DAG, sources, claims, fact-check status, contradictions, unsupported claims, evaluation scores, ready-to-publish gate.
  • Implement publication-gate enforcement: claim density above threshold, citation integrity 100%, contradiction backlog zero, unsupported-claim backlog zero, evaluation thresholds met, reviewer signoff captured.
  • Implement override (operator only) with rationale capture and audit.

9.7 Customer and admin surfaces#

  • Implement evidence sidebar (always available where grounded answers are rendered) in apps/oshun/web/src/components/evidence-sidebar/.
  • Implement source drill-down + citation inspection (with source content excerpt and link) + notebook-creation-from-answer + Nisaba source-trail integration + non-noisy grounding state indicator (color-and-label, not flashing).
  • Implement admin evidence queue, source-set inspection, retrieval-set inspection, citation validation, unsupported-claim queue, contradiction queue, grounded-report promotion to publication.

9.8 Evaluation suites#

  • Evidence-pack assembly evals (completeness, locator granularity, attribution accuracy).
  • Claim-to-source integrity evals (every claim ↔ source mapping verified on a held-out gold set).
  • Passage-to-source integrity evals (cited passages exist at cited locator).
  • Grounded-correctness evals (against gold answers per domain).
  • Citation-integrity evals (stable IDs, no fabricated IDs, no broken trails).
  • Unsupported-claim eval (synthetic prompts that should produce abstention or hedging).
  • Hallucination-risk red-team suite of fabrication-prone prompts.
  • Trace-completeness evals (every output has full envelope; missing trace blocks release).
  • Interruption-recovery evals (pause/resume preserves orchestration state).
  • Wire all evals into release gates.

9.9 Ingestion pipeline#

  • Implement six-stage ingestion pipeline at libs/sophia/ingestion/src/pipeline/: parse → chunk → enrich → embed → index → ingestion-quality eval. Each stage emits a typed event with input/output refs, model versions, time, confidence.
  • Implement idempotency keyed on (uri, content-hash, tenant_scope); changed sources create linked revisions; unchanged sources are no-ops.
  • Implement provenance propagation: every chunk carries (source, revision, page/section/timestamp); citations resolve through the chunk's ancestor, never the chunk ID.
  • Enforce tenant isolation: ingestion routes through @oshun/data-residency; per-tenant sources never co-mingle in any index; cross-tenant retrieval impossible by design.
  • Tests: idempotency on unchanged source; revision linkage on change; per-stage audit event completeness; cross-tenant non-leakage.

9.10 Per-source-type adapters#

  • Define SourceAdapter interface at libs/sophia/ingestion/src/adapters/types.ts with parse, chunk, enrich, freshnessSignal, changeFingerprint, rightsResolver, attributionRenderer.
  • Implement V1 adapters: peer-reviewed PDF, news article (HTML), RSS / Atom feed, YouTube / video transcript, audio transcript (Whisper-class), institutional LMS export (SCORM / xAPI), IIIF manuscript, structured API (NASA JPL / NOAA SWPC / IERS / IMO), tenant BYO bundle.
  • Implement adapter versioning + per-adapter regression fixture sets; adapter changes go through Isis-style release-gate review.
  • Tests: per-adapter parsing accuracy on gold-set; parser- confidence calibration; adapter version conformance.

9.11 Chunking, enrichment, and embedding stages#

  • Implement chunker strategies (semantic, hierarchical, fixed-size with overlap, table-aware, code-aware, time-aligned) at libs/sophia/ingestion/src/chunking/; strategy chosen from source type via policy table; choice logged per chunk.
  • Implement enrichment classifiers at libs/sophia/ingestion/src/enrichment/ for metadata, entities, claims, citations, tone signals; outputs carry confidence + classifier version.
  • Implement embedder at libs/sophia/indexing/embeddings/ with per-modality models (text / multimodal / audio), dense + sparse pairs, versioned and parallel-indexable.
  • Implement embedding version cutover: parallel-index correctness; retired-version fallback during cutover; no recall regression.
  • Tests: chunker boundary determinism; enrichment precision / recall / hallucinated-entity rate; embedding version cutover correctness.

9.12 Ingestion-quality eval and remediation queue#

  • Implement per-stage quality eval at libs/sophia/evaluation/src/ingestion-quality/ producing the IngestionQualityReport per source revision.
  • Implement publish-floor threshold: below-floor sources route to remediation queue; above-floor sources advance to live retrieval surface.
  • Implement operator remediation flow: queue UX, re-parse trigger, manual override with rationale + audit.
  • Tests: per-stage thresholds enforced; remediation queue triage flow; manual override audited.

9.13 Source lifecycle (refresh, diff, retraction)#

  • Implement per-source-type refresh cadence with per-source override; pinned revisions preserved for kept artifacts.
  • Implement changeFingerprint short-circuit on unchanged refresh.
  • Implement claim-level version diff at libs/sophia/ingestion/src/lifecycle/diff/; paraphrase edits do not trigger material invalidation; substantive claim changes do.
  • Implement downstream invalidation event: emit to Veritas retraction cascade, Metis lesson-validity check + tutor re-grounding, Nisaba edition update notice, Tara explainer re-check, Living Scenes kept-artifact banner.
  • Implement retraction event handling (publisher retraction + reviewer revocation) with severity = retraction cascades.
  • Implement retirement + replacement: retired sources excluded from new retrieval but reconstructible from audit; successor chain visible to readers on kept artifacts.
  • Tests: refresh-cadence honored + throttled; paraphrase vs claim-change distinction; cascade fan-out coverage; retirement + replacement preserves kept-artifact correctness.

10. Iris — Memory and Identity#

Completion audit: §10 memory scope hierarchy, retention/decay/compaction, conflict resolution, privacy suppression, customer controls, operator inspection, evaluation suites, persistence contracts, recall resolution, inference confirmation, customer UX, multi-actor handling, continuity, and admin state-machine coverage are implemented with targeted regression gates.

10.1 Memory scope hierarchy enforcement#

  • Enforce profile memory: durable, user-controlled, opt-in. Stored only with consent record. Retained until user-initiated or account deletion.
  • Enforce session memory window: 30 days raw, 90 days summarized, auto-summarized into profile only on explicit promotion or repeated occurrence above threshold.
  • Enforce notebook-linked memory: visible only when in that context; survives across sessions but does not bleed into unrelated contexts.
  • Enforce crisis-frame suppression: during a Lilith crisis frame, no new memory writes; existing memory suppressed from recall except for safety-critical context.
  • Enforce operator-copilot memory: separate scope with approval workflow, narrower retention, tighter audit.
  • Enforce tenant-scoped memory: institutional Metis tenants own bounded memory of learner study state; never blends into consumer profile memory.

10.2 Retention, decay, compaction#

  • Implement decay function: usage-weighted; unreferenced facts decay faster; user-confirmed facts decay slower.
  • Implement rolling summarization compaction with traceable provenance back to original turns.
  • Implement tombstone semantics on deletion: tombstoned + propagated; no silent re-creation; audit log records every forget event.

10.3 Conflict resolution#

  • Implement conflict detection on new statement vs stored memory.
  • Implement resolution policy: most-recent wins by default; user- confirmed trumps model-inferred; explicit user statement trumps inferred; admin-copilot inference never trumps consumer-stated.
  • Implement surface: ask the user ("you mentioned X earlier — should I update?") rather than silently overwriting.
  • Audit each conflict event with prior state, new state, rule applied, user response.

10.4 Privacy-aware suppression#

  • Implement sensitive-category list: health (physical, mental), substance use, sexuality, gender identity, religion (where user-redacted), abuse history, immigration, financial distress, relationship violence, legal jeopardy.
  • Implement per-category opt-in storage; recall gated to relevant contexts only.
  • Implement consent-revocation cascade: revoking deletes associated memory and downstream summaries; audit retained.
  • Implement PII redaction in summaries and logs; tokenization for cross-system reference.

10.5 User-facing memory controls#

  • Implement "what we remember" surface listing every memory fact, scope, source-conversation, last-used time at apps/oshun/web/src/app/profile/memory/page.tsx.
  • Implement edit / clear / opt-out per fact, per category, per scope.
  • Implement full memory bundle JSON export with audit chain.
  • Implement hard-delete with propagation to summaries and downstream uses; irreversible; step-up confirmation.
  • Implement pause-memory ("off-the-record" mode).

10.6 Operator inspection#

  • Implement authorization model: admin-copilot cannot read consumer sensitive-category memory; privacy-operator only via DSAR workflow; safety-operator only on active crisis or P0/P1; all reads audited.
  • Implement audit events: actor, role, scope accessed, reason code, target user, time.
  • Implement user notification post-hoc on first sensitive-category access (within compliance window).
  • Enforce tenant isolation in operator inspection.

10.7 Evaluation suites#

  • Memory-leakage suite (sensitive-category surfacing in non-relevant contexts; cross-scope leakage; cross-tenant leakage; cross-user).
  • Forget-completeness suite (deletion verified on storage, summaries, downstream uses, retrievals, audit references).
  • Conflict-resolution evals.
  • Decay-accuracy evals (synthetic timeline tests).
  • Crisis-suppression evals.
  • Drift detection (memory-recall accuracy, false-recall rate, sensitive-category leakage rate).

10.8 MemoryEntry contract and persistence#

  • Define MemoryEntry Zod contract at libs/contracts/src/iris/entry.ts with all fields specified in features.md § "MemoryEntry contract" (id, userId, tenantId, scope, category, body, confidence, origin, lifecycle, consent, provenanceChain, expiresAt, lastReferencedAt, referenceCount, suppression, multiActor, auditChain). Contract test round-trips every origin × lifecycle × sensitive-category combination.
  • Implement immutable-revision persistence: every mutation writes a new revision and supersedes the predecessor; tombstones are the only terminal lifecycle.
  • Implement provenanceChain propagation so summarization preserves traceability back to source turns / sessions / earlier summaries.
  • Contract-persistence drift test for MemoryEntry.

10.9 Recall-resolution pipeline#

  • Implement scope filter, suppression gate, sensitive-category gate, tenant boundary, relevance ranker (recency · semantic · referenceCount · origin weights), and conflict/freshness check at libs/oshun/memory-iris/src/recall/.
  • Implement per-surface budgets (assistant ≤ 12 entries, shell ≤ 3, notebook full set) and per-surface rationale-visibility settings.
  • Implement surfaceRationale generation and provenanceChain surfacing on every returned entry.
  • Audit every recall with scope, returned IDs, and suppression counts (never content) to @oshun/audit-platform.
  • Tests: same context + same memory state → same ranked output; per-surface budget enforcement; rationale-visibility correctness; audit completeness.

10.10 Inference vs confirmation policy#

  • Implement N-occurrence inference threshold and inline confirmation prompt path at libs/oshun/memory-iris/src/inference/.
  • Implement promotion from model-inferred to user-confirmed on user reference.
  • Block automatic persistence of sensitive-category inferences; require explicit consent + per-category opt-in.
  • Implement inference rationale ("from what you mentioned") with inline correction affordance.
  • Tests: threshold accuracy on synthetic timelines; promotion correctness; sensitive-category block coverage.

10.11 Customer memory UX#

  • Implement "What we remember" index at apps/oshun/web/src/app/profile/memory/ and mobile equivalent with paginated MemoryEntry rows grouped by scope, category badges, last-referenced timestamp, origin badges, per-row actions.
  • Implement detail view with full body, expandable provenance chain, recent-recalls list, suppression state, audit-chain link.
  • Implement edit flow with conflict-detection preview; new revision per edit; predecessor visible in history.
  • Implement forget flow (per-entry, per-category, full memory) with step-up auth and 7-day grace on full memory clear.
  • Implement pause flow (session-scoped off-the-record toggle) with banner.
  • Implement scope-change flow with per-scope rules (no tenant → consumer promotion).
  • Implement export flow (signed JSON bundle with audit chain) via DSAR fulfillment.
  • Tests: keyboard-only navigation; AA contrast; step-up enforcement on forget flows; reverse-promote rejection (tenant→consumer); pause-banner persistence across reconnect.

10.12 Multi-actor memory#

  • Implement masked actor handle namespace per user.
  • Enforce no-third-party-profile invariant: only relationship context retained; no profile of the mentioned person.
  • Implement forget-all-mentions-of: tombstone every entry tagged with the actor handle; remove handle from namespace.
  • Implement sensitive-interaction inheritance: actor mentions with sensitive context inherit category gating.
  • Tests: actor-handle isolation across users; forget-all-mentions completeness; cross-user/cross-tenant non-leakage of actor handles.

10.13 Cross-device continuity protocol#

  • Define ContinuationToken Zod contract at libs/contracts/src/iris/continuation.ts (userId, scopeKey, surfaceContext, anchorRef, posture, lastUpdatedAt).
  • Implement write path: every supporting surface emits tokens at natural checkpoints through BFF with idempotency-key semantics.
  • Implement read path: shell asks Iris for the user's most recent N tokens on launch / device hand-off; renders continuation cards.
  • Implement most-recent-wins conflict resolution with cross-device notice on losing-write devices.
  • Implement reconnect-and-resume across Tara, Psyche, Living Scenes, Nisaba, Metis surfaces via durable anchorRef.
  • Enforce content-free invariant: tokens carry references and posture only; sensitive-category emission requires cross-device consent.
  • Tests: cross-device hand-off correctness; conflict-resolution notice; reconnect mid-segment per surface; sensitive-category consent gate.

10.14 Admin inspection state machine#

  • Implement the inspection state machine at libs/oshun/memory-iris/src/admin-inspection/state-machine.ts with states requested · dsar-fulfillment · incident-escalation · routine-review · granted · denied · closed and the allowed transitions specified in features.md.
  • Implement policy gate at requested → granted checking role, scope-of-request, target tenant, target sensitivity, current consent, signed incident reference (when applicable).
  • Implement user-notice queue: every closed sensitive-category read fires a user notice within the compliance window, subject to ongoing-investigation legal carveouts.
  • Implement audit append on every state transition with actor, role, scope, target user, reason code, and (for granted) the MemoryEntry ID set.
  • Implement snapshot-at-granted replay so any inspection can be reconstructed with the same entries the operator saw.
  • Tests: every illegitimate transition rejected; granted reads stream to audit; user-notice firing on close; cross-tenant inspection rejected; replay determinism.

11. Psyche — Real-Time Runtime#

Audit found ~65% coverage. Session event types not fully enumerated; interruption/replay-buffer state machine missing; continuity tests absent.

11.1 Session envelope and event model#

  • Verify session envelope schema in libs/oshun/embodiment-psyche/src/session-envelope.ts matches spec: session ID, mode, persona binding, locale, region, capabilities, entitlement class, Lilith policy version, Iris memory scope.
  • Enumerate event types in code: text-token-stream, asr-partial, asr-final, tts-chunk, avatar-frame, viseme-stream, expression-update, turn-complete, interruption, reconnect, transcript-sync, error, kill-switch, fallback-engaged, policy-intervention.
  • Implement server-mediated turn semantics (turn-start, turn-end, interruption, system-initiated barge-in) with configurable partial- TTS fade-out ms.

11.2 Reconnect and replay#

  • Implement durable session ID + last-acked-event + replay buffer + interrupt-tolerant reconnect with session-state restoration.
  • Implement partial-TTS replay rule + transcript reconciliation.
  • Implement multimodal sync: per-token timing, viseme alignment, expression alignment to semantic content, screen-context awareness.

11.3 Latency budgets and quality#

  • Enforce voice-latency targets: P50 ≤ 500 ms, P95 ≤ 900 ms, P99 ≤ 1500 ms (first audio chunk after end of speech).
  • Enforce first-token latency: P50 ≤ 350 ms, P95 ≤ 700 ms.
  • Enforce avatar-frame latency: P50 ≤ 80 ms.
  • Enforce ASR final-text latency: P50 ≤ 150 ms after end of speech.
  • Implement backpressure: provider degrades → ASR throttle, model- streaming throttle, "thinking" indicator within 200 ms, fallback to text after configurable threshold.
  • Enforce quality thresholds: lip-sync alignment, expression coherence, voice naturalness floors per locale; below-threshold triggers re-render or fallback.
  • Build latency dashboards (P50/P95/P99 per region/provider/persona) with SLO breach alerts and user-impact mapping.

11.4 Fallback chain#

  • Implement avatar+voice → voice → text fallback with per-stage user-visible disclosure and per-step decline option.
  • Implement triggers: provider failure, quality-threshold breach, latency-budget breach, kill-switch, policy intervention, accessibility request.
  • Preserve persona memory + grounding state across mode transitions; maintain transcript continuity.
  • Implement automatic upgrade attempt after stable interval + user-controlled re-engagement.

11.5 Diagnostics and replay#

  • Tag every event with per-session trace ID for end-to-end correlation.
  • Capture per-event timing (ingress/egress, provider attribution, retry attempts).
  • Implement operator replay tooling (replay session against fixtures with full event reconstruction).
  • Audit every persona break, Lilith intervention, kill-switch firing, fallback engagement, reconnect.

11.6 Continuity tests#

  • Reconnect under network loss: session resumes mid-turn with acceptable replay window.
  • Device handoff mid-turn: session transferred with state preservation.
  • Persona switch mid-session: graceful transition with conversation context and Iris memory scope preserved.
  • Crisis-frame entry mid-session: instant Lilith policy enforcement (persona break, synthesis halt, memory-write suspension).
  • Provider failover mid-turn: seamless degradation with disclosure, transcript continuity, audit trace.

12. Lilith — Persona Policy and Safety#

Audit found ~70% coverage. Generation-time enforcement, no-bypass guarantees, override governance, classifier wiring incomplete.

12.1 Contemplative tone rubric#

  • Wire gentleness floor enforcement into chat/voice generation pipelines.
  • Block prohibited language patterns at generation: commanding imperatives, urgency amplifiers, fear-inducing framing.
  • Require uncertainty markers ("in this lineage," "some teachers describe," "you might notice") for interpretive statements; block absolute claims ("you will," "this means," "the truth is").
  • Require persona-bound lineage attribution; prohibit cross-lineage syncretism without explicit disclosure; require source attribution when invoking specific traditions, named teachers, or scripture.
  • Block self-positioning as guru/prophet/healer/sole-authority; require deference to user's own discernment.
  • Require descriptive ("you may notice the breath at the nostrils") rather than prescriptive ("breathe deeply") framings in meditation scripts.

12.2 Teacher persona safety#

  • Block prohibited promises (enlightenment, healing of medical conditions, prophetic foreknowledge, romantic outcomes, financial outcomes, guaranteed transformation timelines).
  • Require disclaimers (consult-physician/therapist/financial-advisor for medical, psychiatric, financial framings; synthetic-content disclosure on every voiced or avatar persona).
  • Block impersonation of named living individuals without consent; block named historical/religious figures without explicit reviewed lineage frame; block composite personas marketed as a real teacher.
  • Enforce lineage rules: persona-bound attribution required; cross-lineage gated to explicit comparative personas; no off-lineage prescriptions.
  • Enforce therapeutic boundary: no diagnostic statements, no treatment plans, no claims of trauma resolution; require hand-off patterns.

12.3 Crisis-aware behavior#

  • Implement signal taxonomy detection: suicidal ideation (active/ passive/planned), self-harm (active/ideation), violence-toward-others, abuse disclosure (current/historical), domestic-violence indicators, eating-disorder indicators, substance-crisis indicators, panic, dissociation, psychotic-symptom indicators, child-protection signals.
  • Implement per-signal response: break persona to plain operator voice, surface region-aware crisis resources (hotlines/text/emergency), halt synthesis, suspend persona memory writes for the session, open parallel safety-incident record routed to crisis-trained reviewers.
  • During crisis frame: no recall of prior contemplative scripts that would re-enter the crisis state, no generative summarization, no practice recommendations, no admin-copilot inspection without elevated authorization.
  • Implement post-crisis follow-up: opt-in check-in, resource re-surface, consent-gated event memory, audit retention.
  • Implement no-bypass guarantees: crisis policy supersedes persona, lineage, pedagogy, grounding policies; cannot be overridden by user prompt or admin copilot.

12.4 Voice quality and abuse#

  • Enforce naturalness floor per voice profile and language; below floor forces fallback to text.
  • Block prohibited prosody patterns (manic cadence, deceptive warmth, fake-confidant intimacy, simulated breathing inconsistent with content).
  • Enforce per-domain pace bands and silence-density floors.
  • Implement re-render limits per turn; on exhaustion fall back to text + recorded-voice library + apology.
  • Enforce required watermark + loudness normalization; block subliminal pattern artifacts; validate TTS-vs-recorded labeling.
  • Enforce cloned-voice gating: signed consent record per identity, mandatory watermark, identity-protection denylist, per-tenant allowlist, consent-revocation cascade across all generated assets.
  • Implement abuse-detection signals (impersonation prompts, manipulative scripts, restricted-target identity, voice-cloning attempts on uploaded samples).
  • Implement automated quarantine on threshold abuse score; notify operator; suspend entitlement; open review.
  • Maintain immutable per-cloned-voice provenance record.

12.5 Spiritual-domain boundary#

  • Block prohibited claim classes (prophecy, soteriological guarantees, diagnostic spiritual claims about user's "level," karmic pronouncements, deterministic cosmological-as-fact statements).
  • Require explicit comparative frame when invoking multiple traditions; block syncretic prescriptions presented as a unified path.
  • Require tradition attribution; "in [tradition]" hedging where not user-declared.
  • Respect declared lineage in personalized recommendations; do not push outside declared frame without explicit cross-tradition opt-in.
  • Enforce ritual-content rules: no claims of guaranteed altered states; no efficacy claims beyond published lineage sources; required safety guidance for breathwork and intense practices.

12.6 Unsafe-claim handling#

  • Implement claim-class taxonomy (medical / psychiatric / financial / legal / prophetic / conspiratorial / defamatory / retaliatory / electoral-influence).
  • Implement per-class default response (refuse / refuse-with-resources / hedge with redirect / allow-with-citation-mandatory / allow-with- disclaimer / allow-only-from-approved-source-set / expert-handoff).
  • Implement trigger thresholds: claim-classifier confidence × topic sensitivity → refuse / hedge / cite.
  • Implement citation-mandatory triggers (treatment efficacy, contemplative contraindications, contested historical events, attributed teachings).
  • Audit every claim-handling decision (classifier output, response chosen, source set used, user-feedback receipt).

12.7 Wiring, versioning, evaluation#

  • Wire Lilith into: Tara teacher personas, contemplative assistant personas, ritual-script generation, meditation-script narration, voice rendering, avatar rendering, Veritas explainer generation, Sophia grounded answers, Metis tutor responses, support copilot.
  • Implement policy versioning: every policy is a versioned artifact with changelog, evaluation evidence, rollout cohort, rollback plan.
  • Implement evaluation suites: tone-rubric, crisis-handling, cloned-voice abuse, spiritual-boundary, unsafe-claim (per claim class); regression suite blocks release on safety degradation.
  • Implement override governance: any operator override of a Lilith decision requires elevated authorization, rationale capture, time-bound scope, audit; recurring overrides trigger policy review.
  • Enforce tenant constraints: operator baseline; tenant cannot loosen, can tighten.

12.8 Persona taxonomy#

  • Define typed persona roles at libs/oshun/persona-registry/src/roles/: teacher · coach · explainer · steward · comparative · narrator · assistant. Each role declares capability ceiling, default tone band, and hard-bans per features.md § "Persona taxonomy".
  • Implement role inheritance enforcement: a Persona record cannot widen its inherited capability set; tenant policy can narrow only.
  • Implement persona-construction validation that rejects widening and surfaces a clear error.
  • Tests: every role's hard-bans enforced; capability widening rejected; tenant narrow-only enforcement.

12.9 Tone band catalog and capability caps#

  • Define tone band catalog at libs/oshun/persona-policy-lilith/src/tone-bands/ with the ordered bands contemplative-strict · contemplative · reflective · neutral · briefing · instructional · celebratory · urgent-safe.
  • Implement per-band capability caps table (max motion, max audacity, share allowed, generation tier) and enforce in Isis generation dispatch, Living Scenes Conductor, and share-control surfaces.
  • Implement audacity 0–5 scale in Isis; band ceiling + tenant narrowing + user-preference narrowing.
  • Implement per-surface tone-band transition graph; forbidden transitions rendered as section breaks; allowed transitions emit no break.
  • Tests: every band cap enforced in every consuming surface; transition-graph forbidden-paths rendered as breaks; tenant + user narrowing applies correctly.

12.10 Cultural and lineage sensitivity policy#

  • Implement lineage tag enforcement on Tara rituals, Nisaba passages, Veritas stories, and Living Scenes templates; missing tags block publication.
  • Implement sacred-symbol register at libs/oshun/persona-policy-lilith/src/sacred-symbols/ with lineage-rights-holder catalog and operator-tier approval gate for first-time use.
  • Implement comparative-only mixing rule: teacher and coach personas hold a single declared lineage per arc; cross-lineage content rejected unless served by a comparative persona that names each lineage explicitly.
  • Implement user-declared frame respect: recommendations from outside the declared frame surface as comparative with soft notice.
  • Emit LineageBinding attestation per session; capture in audit trail and Living Scenes Render Envelope.
  • Tests: missing-tag publication blocked; sacred-symbol gate fires on first-time use; comparative-only mixing rule enforced; user-declared frame respected; LineageBinding round-trip.

12.11 Persona lifecycle#

  • Implement persona lifecycle state machine at libs/oshun/persona-registry/src/lifecycle/ with states proposed · in-review · approved · deployed · maintained · deprecated · retired and the allowed transitions in features.md.
  • Implement multi-operator review queue with quorum per persona class; review covers consent integrity, lineage rights, voice-quality eval pass, tone-band conformance, abuse-resilience, Lilith policy interlock.
  • Implement provenance bundle generation at approved transition; release-gate metadata recorded.
  • Implement champion-challenger rollout on deployed.
  • Implement re-eval cadence on maintained; drift-detection trigger → re-review.
  • Implement revocation cascade on voice/avatar consent revoke: drop from deployed → deprecated for new uses; sessions complete; kept artifacts → retirement-recovery flow.
  • Implement retirement-recovery flow for kept artifacts pinned to a retired persona (re-render under successor persona with consent-aware migration).
  • Emit PersonaLifecycleEvent per state transition.
  • Tests: every transition writes an event; revocation cascade fires per policy; retirement-recovery preserves kept artifacts; quorum-review enforcement.

12.12 Crisis recovery user journey#

  • Implement stillness window enforcement at libs/oshun/persona-policy-lilith/src/crisis-recovery/ with configurable minimum (default 10 min, never less than 3); non-safety surfaces remain disabled during window.
  • Implement re-entry prompt UI on web + mobile; decline routes to idle-safe surface; accept routes to re-entry home.
  • Implement re-entry home with conservative defaults (contemplative-strict band, no scheduled invitations, sensitive categories disabled).
  • Implement "what happened" surface at apps/oshun/web/src/app/profile/safety/ and mobile equivalent showing the audit-platform-visible record of the frame.
  • Implement 24h + 7d soft check-ins (default opt-in, user can disable) via assistant only; never via push or notification.
  • Implement re-frame protection: new crisis indicator within stillness window or 24h extends the frame; no re-firing.
  • Implement localization parity: support-resource sets and operator- voice strings localized per V1 launch locale; regional safety advisor review required before new-locale launch.
  • Generate Incident record per crisis frame (TODOS § 1.2); operator review queued per tenant time-box.
  • Tests: stillness-window minimum honored; re-frame protection extends rather than re-fires; visible-audit reflects audit- platform record; check-in cadence respects opt-out; locale parity across V1 launch locales; Incident-record generation.

13. Isis — Generation Control#

Audit found ~50% coverage. Release gates, provenance bundles, regression test automation incomplete.

13.1 Workflow templates#

  • Verify workflow template registry in apps/isis/workflow-registry/ covers: workflow class, parameter guardrails, disallowed graph patterns, template versioning + diffing, portability checks.
  • Implement staging recipe schema (named, versioned, environment-bound).
  • Implement environment promotion (dev → staging → prod) state machine with promotion gates.

13.2 Model and provider registries#

  • Verify model registry in libs/isis/ai-providers/ covers per-model lineage, license, version, deprecation.
  • Implement provider endpoint registration, health checks, region-aware routing, concurrency controls, cost controls, retry/backoff, dead-letter, secret rotation, failover.
  • Add queue metrics + execution health + release checks + outage tests + performance tests + audit tests.

13.3 Provenance bundles#

  • Implement ProvenanceBundle schema (consent ID, prompt, model, watermark hash, timestamp, invoking user, tenant) and persist for every generation.
  • Implement immutable generation-event ledger.
  • Surface provenance in admin UI; expose to customer where it adds trust value.

13.4 Release gates#

  • Implement release gates with regression test automation: any safety/ quality eval drop > MDE blocks promotion.
  • Implement staged rollout percentage controls + canary gating.
  • Implement rollback workflow with bound evaluation evidence.
  • Implement failover and fallback policy specifications.

13.5 Tests#

  • Validation, promotion, rollback, provenance, load, audit, release-gate regression tests.

14. Persona, Avatar, and Voice Packs#

Audit found ~65% coverage. Release gates not enforced; rehearsal coverage incomplete; cloned-voice red-team evals missing.

14.1 Persona registry#

  • Verify persona record fields in libs/oshun/persona-registry/ (stable ID, family, lineage, scope, tone profile, mandatory disclosure copy, language coverage, market coverage, entitlement).
  • Implement lifecycle states: drafted → in-review → rehearsal → approved-for-test → approved-for-release → released → deprecated → retired.
  • Implement multi-party signoff captured immutably with rationale + rollback plan.
  • Enforce per-persona disallowed-phrasing at token generation time.
  • Maintain scorecards (tone, gentleness, citation hygiene, grounding fidelity, audience-appropriate language, regression baselines).

14.2 Avatar pack contracts#

  • Implement modality combinations (text-only / voice / voice+avatar) with per-platform availability and per-entitlement gating.
  • Enforce synthetic markers (per-frame visible disclosure badge, embedded watermark, audio watermark, metadata watermark, display caption).
  • Implement likeness controls (synthetic-only / consented individual / consented composite); enforce identity-protection denylist.
  • Enforce lip-sync alignment + expression-coherence floor + animation- smoothness threshold; below-threshold blocks release.
  • Enforce visual brand binding rules.

14.3 Voice profile contracts#

  • Implement profile schema (voice ID, vendor, model, source identity, consent reference, language coverage, prosody profile, naturalness baseline).
  • Enforce cloned-voice rules: consent record, watermark, denylist, per-tenant allowlist, abuse-risk scorecard, revocation cascade.
  • Implement quality scoring (naturalness, prosody coherence, pace adherence, silence-density, emotional-modulation appropriateness) per-language baseline.
  • Implement provider fallback per voice ID with acceptable degradation rules.

14.4 Trust gates#

  • Cap avatar realism band per persona class; persona explicitly synthetic by default unless consented identity.
  • Enforce disclosure visibility (badge present, not obscured, time-on- screen ≥ N).
  • Implement non-impersonation guards (denylist + prompt-time impersonation- attempt detection).
  • Enforce brand-binding metadata; block off-brand renderings.
  • Enforce per-locale lip-sync alignment minimum vs ground-truth pairs.
  • Build composite impersonation-risk + deceptive-realism scorecard gating release.

14.5 Lifecycle, rehearsal, release#

  • Implement rehearsal workflow against fixtures (tone, lineage, crisis, unsafe-claim, voice quality, avatar realism, lip sync, expression).
  • Implement QA workflow with multi-role human review (Lilith reviewer, persona ops, voice ops, avatar ops, brand reviewer, accessibility reviewer).
  • Implement customer persona selection per entitlement class / language / market with disclosure copy at selection.
    • 2026-06-25 progress: /profile/persona now reads the same real registry-derived /v1/persona/voice projection as the picker state, exposes provider/engine/profile/locale/provenance metadata, reflects active voice after a real /v1/personas/select write, and Playwright covers no-consent empty, consent unlock, active readback, anonymous gate, mobile 44px controls, and axe. Preview media remains explicitly unshipped (previewUrl: null) rather than fabricated.
  • Implement admin release management (browse, scorecard inspection, rehearsal replay, release toggle, freeze, rollback, retirement).
  • Enforce per-persona memory boundary (shared with assistant umbrella vs separate scope).
  • Implement escalation/handoff rules per persona (when to break for crisis, hand off to human, refer to operator).

14.6 Evaluation suites#

  • Tone evals per persona × Lilith rubric.
  • Lineage evals per tradition.
  • Cloned-voice abuse evals (impersonation prompts, identity-protection breach).
  • Lip-sync alignment evals against ground-truth pairs.
  • Expression coherence evals per emotion-content pair.
  • Disclosure-visibility evals (synthetic identifier rendered, readable, persistent).
  • Drift detection (persona quality, voice naturalness, avatar realism, disclosure visibility).
  • Block release on any eval below baseline; require declared and tested rollback plan.

15. Search, Discovery, Recommendations, Knowledge Graph#

Audit found ~5–15% coverage on this section. Most candidate-generation, ranker, and KG features are absent or partial.

15.1 Searchable object catalog#

  • Define schema for every object class: rituals, practices, breath sessions, meditations, teachers (Tara); habits, goals, routines, journals (Arete); stories, claims, sources, topics, counterclaims (Veritas); sky events, observation windows, phenomena (Nyx); passages, sources, manuscripts, editions, translations, lexicon entries, concept-graph nodes (Nisaba); courses, lessons, items, assessments, study artifacts, notebooks (Metis); collections, programs, generated artifacts, saved searches.
  • Each object has: stable ID, title, summary, tags, taxonomy binding, language, locale, accessibility metadata, evidence/grounding state, license, freshness window, persona binding, entitlement, region availability.
  • Build per-class lexical, embedding, facet indices with per-class freshness pipeline; cross-class unified facet vocabulary.

15.2 Signals#

  • Capture implicit signals (impression, dwell ≥ N, completion, save, follow, skip, dismiss, hide, snooze, share, return-within-window, back-button, scroll depth, time-of-day, day-of-week).
  • Capture explicit signals (rate, more-like-this, not-interested, follow user/topic/teacher, regret-flag, evidence-inspect-then-save, domain-pin, persona-pin).
  • Capture memory-derived signals (declared lineage, pace, goals, sensitivities; recency of contemplative practice, current Arete focus, recent Veritas reading, recent Nisaba study).
  • Capture domain-specific signals (ritual completed, claim inspected, source drilled, passage annotated, sky event observed, lesson finished, course mastered, weekly review captured).
  • Capture negative signals with decay.
  • Apply privacy filtering per Iris suppression rules; enforce cross-tenant signal isolation.

15.3 Aggregation, decay, freshness#

  • Aggregate per user/cohort/tenant/domain/time-of-day/locale.
  • Apply per-signal-class decay rate.
  • Apply per-content-class freshness window.
  • Trigger cohort re-evaluation on long-absence return.

15.4 Candidate generation#

  • Implement collaborative-filtering candidates with cohort definitions (declared interests + observed behavior); cold-start backed by demographic-light defaults.
  • Implement content-similarity candidates (per-class embedding spaces).
  • Implement concept-graph candidates (traversal from current/recent context).
  • Implement editorial candidates (operator-seeded slates per locale, season, event).
  • Implement recency candidates (just-added, just-published, freshness-boosted).
  • Implement cross-domain bridge candidates (Tara→Nisaba passage companion; Veritas→Arete next action; Nyx→Tara perspective practice).
  • Implement tenant-scoped candidates for institutional Metis (never blends across tenants).

15.5 Ranker and coherence#

  • Implement feature classes: signal scores, content metadata, persona/ tone fit, language/locale match, evidence integrity, grounding state, entitlement, recommendation-reason fit.
  • Implement reason taxonomy strings ("because you saved X," "because it's evening," "because tomorrow is [event]," "because you set [goal]," "because you've been studying [topic]," "because new evidence in [story]," "Tara-centered continuity," "lineage-aligned," "fresh in your concept graph").
  • Implement coherence constraints: Tara-centered home ordering, max-N-from-same-source, max-N-of-same-domain where diversity matters, anti-monoculture, sensitive-content gating, rights/license gating, consent gating.
  • Implement suppression rules (hidden-by-user/policy/takedown/residency/ entitlement).
  • Implement cadence tuning (don't recommend a just-completed ritual, don't push the same Veritas briefing twice in 24 h, gently re-surface saved-but-unread content).

15.6 Online experimentation#

  • Build A/B framework: experiment registry, MDE calculation, ramp policy, holdout group, per-tenant allowlist, kill-switch.
  • Track primary metrics (engagement, retention, completion), secondary (diversity, serendipity, evidence-inspection rate, cross-domain navigation), guardrail (refusal, abandonment, regret-flag, fairness slices).
  • Pre-declare MDE, sample-size guard, sequential-test correction.
  • Implement ramp 1 / 5 / 25 / 50 / 100 % with rollback triggers and canary gating.

15.7 Cold-start#

  • Implement onboarding declarations (lineage, pace, goals, sensitivities, language, region).
  • Implement demographic-light defaults; never use protected-class for ranking.
  • Implement editorial seeds per locale/season.
  • Kick embedding-nearest engine after first save or completion.
  • Implement re-cold-start on long absence.

15.8 Concept graph substrate#

  • Implement node schema (stable ID, type, name, description, language, locale variants, provenance, evidence references).
  • Implement edge taxonomy (prerequisite, refers-to, contradicts, supports, is-a, part-of, lineage-of, observed-by, taught-by, derives-from, comparative-to).
  • Implement edge provenance (source-derived/expert-asserted/model- inferred/user-asserted with confidence and reviewer).
  • Implement enrichment with mandatory expert review for high-stakes edges (prerequisite, contradicts).
  • Compute quality metrics (cycle-freedom, orphan rate, prerequisite completeness, edge-provenance completeness, drift).
  • Expose consumer APIs per domain and admin APIs for curation.

15.9 Evaluation#

  • Offline evals (NDCG, MAP, recall@k, coverage, diversity, serendipity) per domain × per locale fairness slices.
  • Online experiment metrics + guardrails wired to release gates.
  • Per-class search-relevance evals.
  • Cold-start evals.
  • Cross-domain bridge evals.
  • Drift detection (ranker quality, candidate generation, signal pipeline).
  • Block release on any eval drop > MDE.

16. Oshun Studio — Authoring, Editorial, Assets, Taxonomy, Localization, Versioning#

Audit found 5–35% coverage across this section.

16.1 Creator and contributor roles#

  • Implement distinct creator/contributor roles separate from customer and operator: author, editor, curator, reviewer, SME, teacher, scholar, translator, illustrator, narrator/voice talent, producer, publisher.
  • Implement per-role workspaces, queues, permissions, scorecards, release pipelines.
  • Implement creator profiles with bio, lineage, credentials, attribution preferences, rights/consent records, provenance attestation, disclosure controls.
  • Implement invitation/onboarding/training/certification/sandbox/ graduation/suspension/revocation paths.
  • Implement cross-role hand-offs (author → reviewer → editor → publisher → translator) with visible queues, explicit assignment, escalation, SLA tracking.

16.2 Authoring workspace#

  • Implement rich-text + structured-block editor at apps/oshun/web/src/app/studio/authoring/ (slate or prosemirror foundation): headings, callouts, citations, evidence pins, source side-by-side panels, footnotes, glossary references, embeds, diagrams, code, math, accessibility metadata.
  • Implement domain-aware authoring templates (ritual scripts, breathwork, meditation, story drafts, claim cards, source briefs, passages, editions, translations, sky-event briefings, lesson plans, course outlines, assessments, rubrics, assistant explainer modules).
  • Implement inline AI-assist panels (research, drafting, rewriting, summarizing, citation lookup, fact checking, translation suggestion, illustration generation, narration generation, accessibility passes) governed by Sophia / Isis / Lilith.
  • Implement live source/evidence panel pulling from approved Sophia source sets (drag-to-cite, citation pinning, claim-to-source linking, density indicators).
  • Implement preview-as-customer modes per domain (web reading, mobile session, voice rendering, avatar rendering) with parity QA tooling.
  • Implement save/autosave/draft-locking/conflict-resolution/recovery/ named-checkpoints/branch-from-checkpoint/merge.
  • Implement authoring-time evaluation harness (citation integrity, unsupported claims, tone policy, accessibility, readability, locale readiness).

16.3 Editorial calendar and lifecycle#

  • Implement cross-domain editorial calendar with assignments, owners, deadlines, embargo dates, scheduled publish, scheduled unpublish, recurring publish (daily Veritas briefings, daily Tara passages, weekly Arete reflections, nightly Nyx highlights), dependency graphs.
  • Implement canonical content lifecycle states: idea → draft → in-review → changes-requested → approved → scheduled → published → updated → deprecated → sunset → archived → takedown.
  • Implement stage-aware checklists, blockers, gating questions, mandatory reviewers, required evaluations, required disclosures.
  • Implement publishing pipelines binding editorial decisions to Sophia evidence packs, Isis release gates, Lilith tone reviews, rights/provenance bundles, localization readiness.
  • Implement embargo/takedown/hotfix/emergency-correction flows with audit and user-visible correction notes.
  • Implement editorial assignment notifications, deadline reminders, calendar export, cross-team views.
  • Tests for stage transitions, gating enforcement, embargo respect, takedown cascade, calendar fidelity.

16.4 Asset and media library#

  • Implement unified asset library at libs/yemaya/asset-library/ (verify and extend) for uploaded + generated assets — images, audio, voiceovers, video clips, avatar renderings, diagrams, illustrations, manuscripts, scans, motion clips, ambient loops, ritual sound packs.
  • Implement asset metadata (rights, license, source, generator, model, prompt, hashes, version, lineage, watermark, provenance bundle, NSFW labels, language, accessibility text, captions, transcripts, usage scopes).
  • Implement search/filter/tag/dedupe (perceptual hash + embedding) + similar-asset discovery + reuse tracking.
  • Implement asset approval queues, takedown workflows, replacement with downstream artifact invalidation, broken-link surfacing, rights-expiry alerts.
  • Implement bulk upload, drag-and-drop, large-file resumable upload, EXIF stripping, re-encoding presets, per-domain delivery format gen.
  • Implement asset analytics (where used, how often, which renditions, accessibility coverage, license-window status, orphan detection).
  • Tests for metadata integrity, rights propagation, replacement cascade, watermark verification, provenance preservation through transforms.

16.5 Taxonomy, ontology, concept-graph curation#

  • Implement operator/curator tools to add, merge, split, deprecate, re-parent tags, themes, lineages, moods, modalities, topics, claim clusters, prerequisite chains, concept-graph nodes/edges.
  • Implement edge typing + edge-provenance attribution + evidence requirements per edge type + contested-edge review + conflict resolution.
  • Implement ontology change preview (which artifacts shift, recs re-rank, search results change), staged rollout, rollback.
  • Implement cross-domain mapping for shared concepts (Nisaba ↔ Veritas ↔ Nyx ↔ Metis).
  • Implement taxonomy stewardship roles, curation backlog, freshness indicators, drift detection, audit history.
  • Integrity tests: cycle, orphan, prerequisite consistency, edge- provenance completeness, cross-domain mapping validity.

16.6 Localization and translation#

  • Implement translator workspace with segment-level translate, side-by-side source, glossary, term consistency, translation memory, fuzzy match, MT-assist with human review, per-locale style guides.
  • Implement glossary editor with shared terminology, lineage-specific terms, do-not-translate lists, locale variants.
  • Implement localization queues per locale with priority, deadline, reviewer assignment, locale-specific QA.
  • Implement locale-specific QA checklists for RTL, text expansion, date/time/number/currency, honorifics, religious/contemplative sensitivity, accessibility.
  • Implement cross-locale diff + re-translate triggers when source changes, with stale-translation indicators surfaced in customer UX.
  • Implement locale launch readiness scorecards per domain and surface.
  • Tests for TM correctness, glossary enforcement, stale-translation detection, RTL rendering, locale parity QA.

16.7 Versioning, diff, rollback#

  • Implement per-artifact version history (author, timestamp, change summary, approval state, linked review package).
  • Implement visual diff for prose, structured blocks, citations, source bindings, assets, metadata, translations.
  • Implement branch / propose-change / request-review / request-changes / merge flows analogous to PR review.
  • Implement rollback to any prior version with cascade detection (linked artifacts, citations, derived courses, derived study plans) and operator-confirmed cascade scope.
  • Implement public-facing change notes ("updated on … because …") where transparency policy requires.
  • Tests for chain integrity, rollback cascade fidelity, diff correctness, audit linkage.

16.8 Collaboration, comments, review threads#

  • Implement real-time co-editing with presence, cursors, selection sharing, conflict-free merging, offline-tolerant local-first editing where applicable.
  • Implement inline comments, resolved/unresolved threads, mentions, assignment, per-thread notification routing.
  • Implement suggestion mode (track changes), accept/reject with attribution, reviewer-only comment channels.
  • Implement review checklists embedded in artifact with reviewer signoff blocks, required evaluations, gating questions.
  • Implement per-artifact activity feed (edits, comments, citations changed, assets swapped, reviewers assigned, approvals, publish-state transitions).
  • Tests for co-edit consistency, comment routing, signoff enforcement, presence/awareness behavior under reconnect.

16.9 Templates library#

  • Implement canonical browsable role-aware template gallery for ritual scripts, meditations, breathwork sessions, journaling prompts, weekly reviews, reflection cards, story briefs, claim cards, source notes, passages, edition comparisons, sky-event briefings, lesson plans, course outlines, assessments, rubrics, admin review templates.
  • Each template: required fields, validation, suggested grounding sources, recommended evaluations, pre-bound persona/tone policy, pre-bound agentic pipeline.
  • Implement template versioning, fixture-bound rehearsal, deprecation, replacement recommendation.
  • Implement per-tenant template extensions and overrides for institutional Metis delivery.
  • Tests for template validation, persona/policy binding, fixture rehearsal, override propagation.

17. Customer Curation — Notebooks, Collections, Annotations#

  • Implement customer-controlled notebooks, collections, study queues, ritual sets, reading lists, saved searches across all domains.
  • Implement drag-and-drop ordering, nested collections, smart collections (rule-based), templates, import-from-another.
  • Implement sharing controls (private / shared with named users / shared via link with permissions: view, comment, copy / public- profile surface where opted in).
  • Implement embeddable share cards for stories, claims, passages, sky events, meditations, lesson modules with provenance, grounding, synthetic indicators preserved.
  • Implement annotation system across reading surfaces (Nisaba editions, Veritas stories, Metis lessons, Tara transcripts) with highlights, threaded notes, citations, cross-artifact backlinks, export.
  • Implement bookmark + reading-list with progress, time-to-finish estimates, resume across devices.
  • Implement customer version awareness: "this passage was updated since you saved it — show diff."
  • Tests for sharing-permission isolation, public-profile gating, annotation durability, progress sync.

18. Agentic AI Studio#

Audit found ~15% coverage. This section is large because the spec is large.

18.1 Agent registry and catalog#

  • Implement canonical AgentRegistry with stable IDs, versioned capabilities, declared tool grants, declared data scopes, declared model + provider bindings, owner team, persona binding, tone policy, grounding policy, audit policy, cost class, lifecycle state.
  • Implement agent families: research, drafting, editing, fact-checking, citation verification, illustration, narration, translation, course generation, lesson scaffolding, assessment generation, study-plan synthesis, recommendation explanation, moderation triage, support triage, ritual scriptwriting, sky-event briefing, claim extraction, source ingestion, KG promotion.
  • Implement browsable agent catalog with capability cards, sample runs, evaluation scores, cost ranges, latency ranges, supported domains/ locales, required entitlements, disclosure requirements, reviewer comments.
  • Implement per-tenant catalog views, per-role visibility, feature- flagged experimental agents segregated from default.
  • Tests for registry integrity, capability declarations, scope enforcement, catalog visibility, version pin correctness.

18.2 Job orchestration and long-running runs#

  • Implement durable AgentRun envelope (inputs, plan, tool calls, intermediate artifacts, evidence trails, cost ledger, decision rationale, output bundles, status, provenance).
  • Implement long-running execution support (checkpoint, resume, re-execute, partial-output preservation) for multi-source course generation, weekly briefing batches, multi-language dubbing.
  • Implement streaming progress visibility for operator/creator/customer (outline drafted, sources gathered, claims verified, illustrations generated, narration rendered, review pending, publish scheduled).
  • Implement pause / branch / resume / cancel / fork / retry-with- changes / operator-step controls.
  • Implement replay and time-travel debugging on a saved run with full intermediate state and tool-call transcripts.
  • Tests for durability under restart, checkpoint correctness, partial-output preservation, replay fidelity.

18.3 Multi-agent plans, hand-offs, approval gates#

  • Implement visible plan/DAG of an agent run.
  • Implement per-stage hand-off contracts with input/output schemas, evidence requirements, mandatory checkpoints, quality gates.
  • Implement operator-defined approval gates (human-required-before- stage, before-publish, expert-required-on-claim-density-above- threshold, tenant-policy gates).
  • Implement branching plans for parallel exploration with explicit selection or merge.
  • Implement re-planning triggered by failed gates, new evidence, retracted sources, policy changes — with audit of re-plan reason.
  • Tests for plan execution correctness, hand-off contract validation, gate enforcement, branching merge decisions, and re-plan provenance.

18.4 Operator job dashboard, replay, audit#

  • Implement cross-tenant operator dashboard for active/queued/paused/ blocked/recently-completed runs with filters by agent family, owner, tenant, cost band, latency band, severity, approval state.
  • Implement per-run page with plan/DAG visualization, tool-call transcript, evidence trail, cost ledger, sampled outputs, evaluation scores, escalation history, bound review packages.
  • Implement bulk and per-run actions (pause, kill, escalate, override gate, mark reviewed, defer, reassign).
  • Implement immutable per-run audit events.
  • Implement cross-run search, saved investigations, exportable run bundles, run-replay handoff.
  • Tests for dashboard filtering, audit event completeness, tenant isolation, run replay handoff, and operator action authorization.

18.5 Customer- and creator-facing invocation#

  • Implement domain-aware agent surfaces in the assistant ("research counterclaims for this story," "draft a study plan from these readings," "generate tonight's sky briefing," etc.).
  • Implement creator-side agentic actions inside the authoring workspace ("outline this course from these twelve sources," "fact-check claim density," "generate six illustration candidates," "produce captions and dubbed narration in four locales," "summarize this manuscript edition into a study passage").
  • Implement pre-flight cost/latency estimates, declared evidence and source set, declared tone policy, declared persona, declared output type, consent confirmations.
  • Implement in-progress run cards with progress, ETA, intermediate preview, interrupt/redirect/refine.
  • Implement output review experience (side-by-side with sources, diffable, accept/reject/regenerate-with-direction, save to notebook, send to editorial pipeline).
  • Implement notification on completion, scheduled run reminders, run- history surface per user.
  • Tests for invocation entitlement gating, source-scope enforcement, in-progress controls, cost/latency disclosure, and output provenance preservation.

18.6 Budgets, quotas, throttles, kill switches#

  • Implement per-tenant/per-role/per-agent/per-run/per-tool budgets and quotas for cost, tokens, GPU minutes, voice seconds, avatar seconds, retrievals, external calls, storage.
  • Implement customer-facing usage meters with grace, warnings, graceful degradation.
  • Implement throttle and back-pressure controls.
  • Implement kill switches per agent / family / tenant / provider / region with operator audit, automatic safe degradation, user-visible status copy.
  • Implement anomaly detection on cost, latency, retry storms, retrieval volume, tool-call patterns, with automated quarantine and operator notification.
  • Tests for budget enforcement, quota reset, throttle accuracy, kill-switch behavior, anomaly-triggered quarantine, and user-visible degradation.

18.7 Memory, tool grants, capability audits#

  • Implement per-agent declared and enforced tool grants, data scope grants, retrieval scope grants, persona bindings, PII handling rules.
  • Implement inspectable agent memory (where enabled) with audit, export, redaction, scoped clear, tenant-isolated boundaries.
  • Implement capability audit reports per agent.
  • Implement tool isolation via sandboxes, egress allowlists, SSRF guards, secret scoping, per-call authorization checks.
  • Implement adversarial capability tests (prompt injection, tool-call exfiltration, scope escalation, sandbox escape, persona/policy bypass, source fabrication) with regression suites and release blockers.

18.8 Feedback, gold sets, champion-challenger#

  • Implement inline rate / critique / regenerate-with-direction controls on every agentic output, with structured tagging feeding evaluation pipelines.
  • Implement operator-decision (accept/reject/override/edit-then-accept) promotion to versioned gold sets after privacy review.
  • Implement champion-challenger and shadow rollouts with parallel evaluation, statistical readiness gates, operator scorecards.
  • Implement drift detection across agent quality, citation density, abstention rate, refusal rate, hallucination rate, persona/tone fidelity.
  • Implement promotion / freeze / rollback workflows with bound evaluation evidence and audit history.
  • Tests for evaluation harness correctness, gold-set versioning, champion-challenger readiness gates, shadow rollout isolation, and rollback effectiveness.

18.9 Cost-quality modes#

  • Implement customer- and creator-selectable modes (fast / balanced / deep / exhaustive / rehearsal-dry-run) with declared cost, latency, citation density, evaluation thresholds per mode.
  • Implement deep-research mode with multi-agent orchestration, expanded source budgets, expanded retrieval depth, expanded verification, expanded human checkpoints.
  • Implement rehearsal mode that runs a complete pipeline against fixtures with no external side effects.
  • Implement per-domain default modes and policy-controlled override rules for customer, creator, tenant, and operator surfaces.
  • Tests for mode declaration, threshold enforcement, rehearsal isolation, policy override denial, and mode-aware UI affordances.

18.10 Cross-domain pipelines#

  • Implement "Veritas weekly briefing pack" pipeline.
  • Implement "Tara seasonal ritual program" pipeline.
  • Implement "Nisaba edition study guide" pipeline.
  • Implement "Nyx event explainer set" pipeline.
  • Implement "Arete personalized weekly review" pipeline.
  • Implement "Metis course from BYOM bundle" pipeline.
  • Implement pipeline registry with versioning, fixture-bound rehearsal, evaluation harness, deprecation, per-tenant customization.
  • Implement pipeline observability (SLA per stage, evidence completeness per stage, human-touch points per stage, end-to-end provenance).
  • Implement tenant-scoped pipeline scheduling.
  • Tests for pipeline execution fidelity against fixtures, end-to-end provenance, scheduling correctness, tenant scoping, and deprecation/ replacement behavior.

18.11 Tool catalog (V1 enumerated set)#

  • Define AgentToolCatalog Zod contract at libs/contracts/src/agent/tools.ts with per-tool id, semver, capabilityModifiers schema, scope-requirements, audit-hooks, deprecation status.
  • Implement V1 catalog entries per features.md § "Tool catalog": web.fetch, source.fetch, sophia.ground, sophia.fact_check, memory.read, memory.write, persona.invoke, generate.image, generate.video, generate.audio, composition.suggest, themis.adjudicate, code.exec, file.read, file.write, calendar.read, calendar.write, notify.send, handoff, approval.request, agent.terminate.
  • Implement semver-bounded tool dependency resolution; deprecation surfacing to dependent agents at registry-review time.
  • Implement per-tool audit hook in @oshun/audit-platform capturing arguments, scope check result, latency, outcome.
  • Tests: catalog round-trip; semver dependency resolution; deprecation surfacing; per-tool audit-hook completeness.

18.12 Grant scope and revocation cascade#

  • Define AgentToolGrant Zod contract with (agentId, toolId, scope, scopeRef, capabilityModifiers, expiresAt, grantedBy, rationale) where scope ∈ {per-run, per-session, per-user, per-tenant, per-pipeline-instance}.
  • Implement grant resolver at libs/oshun/agent-pipelines/src/grants/resolver.ts evaluating effective grants per tool call (per-call authorization).
  • Implement revocation propagation: in-flight runs receive tool_revoked event at next tool-call boundary; queued runs re-check at dispatch; sub-agents inherit revocation transitively.
  • Implement time-bound expiry treated identically to revocation; renewal requires fresh rationale + re-audit.
  • Implement platform-wide and tenant-wide tool kill-switches with ≤ 5 s propagation to active runs.
  • Tests: per-scope revocation propagation latency; queued-run re-check; expiry handled as revocation; kill-switch propagation; revoked-run audit completeness.

18.13 Multi-agent hand-off protocol#

  • Implement budget envelope deduction at dispatch with denomination in cost-units (token-cost-equivalent across providers).
  • Implement budget enforcement on sub-agents: overshoot triggers sub-agent kill + subagent_budget_exceeded event back to parent; unused budget returns to parent on terminal state.
  • Implement authority envelope: dispatch widening rejected; narrowing honored; capabilityModifiers propagated.
  • Implement approval requirements (none | operator | teacher | guardian | user-confirm-before-proceed) pausing sub-agent in awaiting_approval until resolved.
  • Implement cycle prevention via parentTrace (ordered ancestor agentId list); re-entering an ancestor blocked unless allow_cycle=true declared at chain root; cycle attempts audited specially.
  • Implement depth cap (V1 default 5, override per pipeline); depth-cap reached fails dispatch.
  • Implement hand-off audit append on dispatch and on sub-agent terminal state with budget-used, authority-granted, artifacts.
  • Implement artifact attribution chain (rootAgent → ... → producingAgent) in every artifact provenance bundle.
  • Tests: budget inheritance correctness; widening rejected; cycle blocked unless declared; depth-cap enforced; sub-run audit completeness; attribution-chain integrity.

18.14 Cross-domain pipeline pattern reference#

  • Specify veritas.story_drafting pipeline as a versioned registry entry with declared stages (source enumeration → ingestion verification → claim extraction → fact-check → contradiction check → counterclaim generation → Lilith tone review → editorial inbox handoff) and operator-tier-only invocation.
  • Specify metis.course_from_byom pipeline with stages (BYOM safety scan → ingestion → objective extraction → KG anchor → prerequisite-chain → item-bank → calibration → Themis pre-screen → tenant teacher approval).
  • Specify tara.seasonal_program pipeline with lineage rights confirmation gate and operator-tier-only invocation.
  • Specify nyx.event_explainer_set pipeline ending in mid-tier Nyx-desk operator approval.
  • Specify arete.weekly_review_draft pipeline with user-confirm-before-publish gate; customer-tier invocation against user's own consented data only.
  • Specify nisaba.edition_study_guide pipeline with customer-tier draft + scholar-tier publication.
  • Implement pipeline-governance metadata: participating agents, expected hand-off depth, total budget cap, mandatory approval gates, expected outputs, provenance shape, evaluation fixture set. Deviations audited and routed to operator review.
  • Tests: per-pipeline output-shape conformance on declared fixtures; approval gates pause correctly; deviation audit coverage.

18.15 Autonomous creative direction plane (@oshun/creative-autonomy)#

The self-directed layer above the invocation-driven studio: it decides what to create, produces it, judges it, routes it past humans, and learns from their reactions. See V1/architecture/agentic-ai-studio.md § "The autonomous creative direction plane".

  • Implement evidence-bearing opportunity sensing (SignalSource seam + exponential freshness decay + kind/topic dedupe) with four deterministic sources: catalog-gap (demand × deficit/staleness blend), engagement-decay (historical-peak decline with residual-demand floor), calendar-event (triangular lead-time fit), audience-request (rater saturation × rating need over real FeedbackEvents). Zero sources = typed error.
  • Implement ideation: deterministic signal-kind → angle affinity derivation with per-angle brief templates, plus a fail-loud LLM IdeaSynthesizer seam whose proposals are admitted only against registered categories, unbanned topics, and actual sensed signals (typed rejections).
  • Implement the compellingness prior: steering-weighted blend of timeliness, token-Jaccard novelty, audience value, strategic fit (emphasize/avoid theme matching), and feasibility (generator coverage × budget fit), with an auditable per-component breakdown.
  • Implement Thompson-sampling portfolio selection: Beta posteriors per category (Marsaglia–Tsang gamma sampling, injected RNG, snapshot round-trip), priority-per-cost greedy packing under cycle budget + per-category caps + topic-cluster guard, typed skip reasons, and an editorial calendar honoring category gaps + daily caps.
  • Implement the variant tournament: round-robin pairwise judging fitted with ε-regularized Bradley–Terry MM iterations (closed-form two-player case verified in tests); single-variant and tie handling.
  • Implement the calibrated publish gate: 7-dimension rubric ensemble with cross-judge disagreement penalty, human-calibration offset, confidence floor (unconfident pass ≠ pass), and named failing dimensions.
  • Implement the concurrency governor (session-limit safety): bounded FIFO slots (default 2), token-bucket launch rate, AIMD backoff on classified rate/session-limit errors with cooldown and additive recovery; errors always propagate.
  • Implement the human review queue: per-category autonomy levels (manual / copilot / approval / review-window / full-auto), approve / reject-with-reason / veto-in-window / request-tweak / consume-tweak actions, window expiry auto-approval, gate-failure parking, full provenance chains, and immutable audit histories with typed invalid-transition errors.
  • Implement versioned human steering (CreativeDirection): tenets, theme emphasis/avoidance, banned topics, audience priorities, tighten-only autonomy overrides, quality-bar overrides, validated score weights.
  • Implement the preference learner: documented outcome→reward constants updating bandit posteriors, per-category calibration EMA versus machine scores, published-item feedback ingestion, and steering suggestions (losing category, overconfident gate, repeatedly-rejected topic) that never auto-apply to human-owned lists.
  • Implement the AutonomousCreativeDirector cycle loop (kill-switch preflight → window resolution + publication → outcome learning → tweak regeneration first → sense/ideate/select → produce K variants → tournament → gate → route per autonomy) with honest CycleReport accounting (skips, failures, real token usage, governor snapshot) and a pure quiet-hours-aware scheduler.
  • Mount the BFF surface (/v1/agentic/autonomy/*): operator-gated cycle trigger (fail-closed 503 without bound producer/publisher/judges), review-queue list/detail/actions, steering GET/PUT, learner suggestions, published-item feedback, status + cycle reports; launch categories per the §18.10 pipelines.
  • Tests: 100 library tests (known-value math for decay/gap/decline/lead models, Beta posterior + statistical sampling checks, exact knapsack fixtures, Bradley–Terry closed-form, AIMD sequences on a fake clock, review lifecycle, steering validation, learner EMAs, full director cycles over scripted seams) + 5 BFF route tests (fail-closed, auth/scope gates, end-to-end cycle → approve → publish → feedback over HTTP).
  • Implement specialist (partial-dimension) judge panels: judges score only their competent dimensions; per-dimension aggregation over scoring judges; IncompleteJudgePanelError when the panel leaves a dimension uncovered (never gap-filled with invented scores).
  • Implement bounded gate-failure self-correction: up to gateRetries fresh produce→tournament→gate passes with failing dimensions + gate notes fed back into the brief before parking; gateAttempts reported.
  • Implement publish-failure isolation: a failed publish keeps the item approved, lands in publishFailures (or a publish-failed disposition), and retries next cycle — one broken sink never aborts a cycle.
  • Ship fail-loud LLM defaults on @oshun/ai/agent-loop: createStructuredIdeaSynthesizer, createLlmRubricJudge, createLlmPairwiseJudge (both-orderings position-bias mitigation), plus deterministic variantText/extractCitations extraction.
  • Bind the plane to the real monorepo systems (apps/oshun/bff/src/agentic/autonomy-bindings/): Nyx ephemeris calendar signals (credential-free); content-quality-judge craft + pairwise judges over the @oshun/ai→@iris/agents-core provider bridge; deterministic slop/Lilith-tone/Sophia-grounding judges; the studio-authoring editorial lifecycle as the publisher (Lilith gate enforced, EditorialGateRefusedError on blockers); the generation-job pipeline as media producers via the extracted processQueuedGenerationJobs drain (Isis release gate + catalog preserved); the LLM text generator with declared citations; the admin kill-switch store as the cycle abort signal; one-call createBoundCreativeAutonomyPlane wired in server.ts (BOUND vs fail-closed logged). Audit: CREATIVE_AUTONOMY_UNDERLYING_AUDIT_2026-07-02.md.
  • Deep implementation/prompt review vs. SOTA agentic-content practice, with every actionable finding fixed (audit doc § "Deep implementation review"): tweak directives survive production failures; dependency-context threads into text/media prompts; specialist-panel confidence = agreement × coverage (thin panels are honestly less confident, coverage exposed); judge prompts gain score anchors, opening-focused hook, verbosity guards, multi-sample option, and a deterministic head+tail judging clamp; synthesizer sees recent topics; planner constrained to live domains; discounted Thompson sampling (γ/cycle) + two-level (category, angle) arms learned from outcomes and blended into selection; trigram-augmented novelty; failed-topic cooldown with honest suppressedByCooldown accounting; governor honors provider Retry-After hints; topics sanitized at admission (injection defense).
  • Make the plane durably autonomous: snapshot/restore for the review queue, bandit arms, learner, steering, and cycle reports wired to the BFF DurableSnapshotStore (wireDurableAutonomyPlane — human-taught state survives deploys); an autonomous cycle driver fires scheduled cycles non-reentrantly (OSHUN_AUTONOMY_AUTOCYCLE=0 disables); a full-stack e2e test drives nyx sensing → planning → writing → the five-judge panel → tournament → gate → review queue with only the model scripted.
  • Set live provider credentials at deploy (OPENROUTER_API_KEY binds the director; media executors need Stability/ElevenLabs/fal/Suno keys), wire stance-verified grounding (sophia.fact_check over a retrieval corpus), feed the engagement/search demand sources from the analytics warehouse + query logs, layer embedding-based novelty and κ anchor calibration once creds/gold sets exist, and graduate categories beyond Approval after operator review of early cycles. Board tag 2026-09-18: the wiring halves are agent work behind seams that fail loud without a key; what keeps this open is the owner's provider keys (Stability, ElevenLabs, fal, Suno) and gold sets for the κ calibration, neither of which an agent can obtain. blocked:external blocked:corpus

19. Admin Web and Admin Mobile#

19.1 Admin Web (apps/oshun/admin)#

  • Implement admin shell, auth, RBAC, dashboard, inbox, trust/safety, review, research-integrity, support, privacy, policy, model, persona, rights, incident, readiness navigation.
  • Implement saved views, filters, universal admin search, cross- workspace links, collaboration comments, annotations, keyboard-first triage, notification center, assignment signals, exportable investigation bundles.
  • Implement review package lists/details with stage graphs, status history, approve/reject/request-changes, rationale capture, delegation, escalation, SLA timers, review templates, blockers, immutable history, audit linkage.
  • Implement trust-and-safety queues for moderation, user reports, crisis escalation, cloned-voice, avatar deception, image moderation, repeat offenders, appeals, rule-hit explanations, metrics.
  • Implement content calendar, publishing states, content QA, curriculum publishing, teacher publishing, research integrity, citation validation, support cases, subscriptions, entitlements, refunds, privacy requests, DSAR exports, deletion, retention exceptions, legal holds, policy attestations, compliance reviews.
  • Implement persona registry, voice-profile review, avatar-pack review, model registry, workflow templates, rights/provenance inspection, watermark verification, incidents, policy/config center, executive dashboards, readiness dashboards.
  • Implement editorial calendar, content scheduling, embargo, takedown, hotfix, emergency-correction surfaces with cross-domain visibility and assignment.
  • Implement agentic AI operations dashboards (cross-tenant run inventory, plan/DAG inspection, evidence-trail review, cost ledger, kill-switch activation, gold-set promotion, champion-challenger rollout, rollback).
  • Implement audit log explorer with filters, saved investigations, exportable bundles, cross-event correlation, tenant-scoped views.
  • Implement bulk-operation console for users, rosters, content, taxonomy, persona assignments, entitlements with dry-run, validation, staged commit.
  • Implement integrations registry: API keys, webhooks, LMS/calendar/ identity/payment connectors, OpenAPI/SDK docs, sandbox tenants, webhook simulators.
  • Implement notification/email/SMS/in-app message template authoring with localized variants, variable validation, accessibility lint, A/B testing, approval workflow.
  • Implement help center and changelog authoring under same lifecycle/ review/localization/versioning machinery as content domains.
  • Implement public status page authoring, banner targeting, incident communications, postmortem catalog management.
  • Implement admin copilots for review, moderation, research integrity, model ops, compliance, support — with explicit distinction between suggestions, evidence, human decisions.
  • Implement mandatory human approval for high-risk decisions, feedback capture, override logging, audit tests, bypass prevention.
  • Implement one canonical inbox/queue model across review, moderation, support, privacy, incident, model, persona, policy, research integrity.
  • Implement safe bulk triage workflows with rationale, selection limits, previews, audit trails.
  • Implement policy-pack/disclosure-state/tone-style/prompt-policy/ retrieval-policy/grounding-policy/moderation-thresholds/appeals/ voice-avatar-policy/experiment-guardrails/model-lineage/provider- health/sampled-output-review/incident-blast-radius/customer-impact/ runbook-launch/postmortems/release-scorecards/go-no-go decisions.
  • Apply dense-data redesign principles: calmer surfaces, evidence comparison, diff inspection, severity visuals, escalation visuals, reduced modal overuse, extended-session ergonomics.
  • Add Playwright/accessibility/visual-regression/audit/copilot/admin- queue/policy/incident/export/rights/privacy/research-integrity coverage.

19.2 Admin Mobile (apps/oshun/admin-mobile)#

  • Implement secure mobile admin shell, login, step-up auth, urgent queue home, assignment overview, push-driven escalation, low-connectivity-safe queue behavior.
  • Implement compact review cards with severity and SLA state.
  • Implement approve, reject, request-changes, escalate, reassign, acknowledge-incident, handle-high-priority-support actions, plus processing of creator/reviewer notifications where mobile action is safe.
  • Implement compact evidence previews, incident summaries, degraded-connectivity states, retry, handoff, haptics, motion, confirmation behavior.
  • Add mobile E2E, accessibility, telemetry, device-specific visual QA, urgent-queue signoff coverage.

20. Tenant Console and Operator Toolkit#

Audit found ~5% coverage. Tenant model itself is missing.

20.1 Tenant and organization admin#

  • Implement canonical Tenant model spanning institutions, schools, labs, partner orgs, managed cohorts with stable identity, hierarchy (district → school → class → cohort), policy inheritance, provenance.
  • Implement tenant admin shell distinct from operator admin, scoped strictly to the tenant's data, members, content, agents, integrations, audit.
  • Implement tenant onboarding, contract metadata, billing entity, region/data-residency selection, default policy bundle, default persona/voice/avatar policy, default agentic-pipeline catalog, default Metis institutional configuration.
  • Implement tenant member directory, role assignment, group membership, license allocation, seat management, per-member status.
  • Implement tenant content scopes (which sources, courses, programs, rituals, briefings, personas are visible/usable inside the tenant) with override and inheritance rules.
  • Implement tenant-scoped agentic pipeline configuration, budgets, approval gates.
  • Tests for tenant isolation, hierarchy correctness, policy inheritance, scope enforcement, seat-allocation accuracy.

20.2 Identity, SSO, SCIM, provisioning#

  • Implement SAML 2.0 SSO with claim mapping, JIT, IdP- and SP-initiated flows, configurable session lifetimes.
  • Implement OIDC SSO with the same options.
  • Implement SCIM 2.0 user/group provisioning (create, update, deactivate, suspend, group sync, conflict-resolution).
  • Implement OneRoster-grade rostering for Metis with periodic and on-demand sync, dry-run preview, conflict reporting, audit.
  • Implement federation between tenants (district ↔ school ↔ class) with explicit policy and audit.
  • Implement per-tenant authentication policy: MFA requirement, step-up triggers, IP allowlists, device posture signals, session refresh.
  • Tests for SSO claim mapping, SCIM lifecycle, OneRoster fidelity, federation isolation, step-up enforcement.

20.3 Custom roles and permission templates#

  • Implement operator-editable role templates layered on the canonical role model with capability flags, scope restrictions, inheritance.
  • Implement per-tenant role customization within operator-approved bounds.
  • Implement permission diffs against the canonical baseline with risk scoring, reviewer signoff for elevated permissions, audit history.
  • Implement role assignment workflows with approval, expiration, recertification.
  • Implement test harness for role configurations (dry-run with assertion of allowed/denied actions).
  • Tests for role-permission isolation, recertification expiry, scope-restriction enforcement, elevated-permission review, and tenant customization bounds.

20.4 Audit log explorer#

  • Implement operator and tenant-admin audit log explorer with filters by actor, role, tenant, action, severity, time window, target object class, policy binding.
  • Implement saved investigations, shareable links, exportable bundles with chain-of-custody metadata, retention-aware export.
  • Implement cross-event correlation views for support investigations, security investigations, privacy DSARs, compliance reviews.
  • Implement tamper-evident storage with verification tooling, integrity attestation, policy-controlled redaction for privacy-sensitive fields.
  • Implement tenant-scoped audit access with strict isolation.
  • Tests for filter correctness, export integrity, redaction enforcement, chain-of-custody metadata, and tenant isolation of audit data.

20.5 Bulk operations and data import/export#

  • Implement bulk import (users, rosters, classes, courses, content, sources, taxonomy, persona assignments, entitlements) with dry-run, validation preview, conflict report, staged commit.
  • Implement bulk export of tenant-owned content/data/audit/rights/Metis records in JSON/CSV/OneRoster/xAPI/Caliper with integrity manifests.
  • Implement bulk action workflows on selected sets with safety limits, rationale capture, preview, audit.
  • Implement data-residency-aware export and import with region routing and explicit cross-region transfer approval.
  • Tests for dry-run accuracy, validation errors, partial-failure recovery, staged commit, bulk-action rollback, and residency enforcement.

20.6 API keys, webhooks, outbound integrations#

  • Implement tenant- and operator-managed API keys with scopes, rotation, expiration, rate limits, IP allowlists, last-used metadata, revocation.
  • Implement outbound webhook management with topic subscriptions, signing keys, retry/backoff, dead-letter inspection, replay tooling, per-event audit.
  • Implement inbound integrations registry (LMS / calendar / identity / payment / telemetry / BYOM ingest / Slack-Teams notification sinks).
  • Implement connector health, error budgets, circuit breakers, version pinning, upgrade pathways.
  • Publish public developer documentation, OpenAPI specs, code examples, sandbox tenants, webhook simulators, integration certification flows.
  • Tests for key rotation, scope enforcement, webhook delivery semantics, signature verification, replay safety, connector health probes, and certification sandbox isolation.

20.7 Notifications, lifecycle communications#

  • Implement multi-channel notification fabric (in-app/push/email/SMS/ voice/webhook) with channel preferences per user, per-domain, per-persona, per-severity, per-quiet-hours.
  • Implement lifecycle and transactional email program (onboarding, milestones, re-engagement, billing, privacy, support, incidents, content updates) with per-locale templates and accessibility-compliant rendering.
  • Implement operator and tenant-admin template authoring with localized variants, variable validation, preview, accessibility lint, A/B testing, approval workflow.
  • Implement customer-visible message center (history, unread, deep links, delivery receipts, unsubscribe).
  • Implement digest and summary modes for notification opt-outs.
  • Implement unsubscribe / suppression / bounce / compliance handling (CAN-SPAM, CASL, GDPR) with audit.
  • Tests for channel preference enforcement, quiet-hours routing, locale fallback, accessibility lint, A/B assignment, digest behavior, and unsubscribe propagation.

20.8 Help center and knowledge base#

  • Implement in-product help surface with contextual articles, tooltips, walkthroughs, videos keyed to active surface, role, domain.
  • Implement operator and tenant-admin authoring for help articles, walkthroughs, FAQs, video scripts, changelog entries — same lifecycle/review/localization/versioning as content.
  • Implement help search across customer/admin/creator/partner with role-aware results.
  • Implement feedback loop on help content (was this helpful, what's missing) feeding the editorial backlog.
  • Implement "what's new" / changelog surface with subscription, locale, severity filters.
  • Tests for contextual targeting, role-aware visibility, help search relevance, feedback routing, subscription filtering, and localization fallback.

20.9 System status, maintenance, public communications#

  • Implement public-facing status page with component health, regional health, recent incidents, scheduled maintenance, RCA links, subscribe-by-channel.
  • Implement operator authoring for incident updates, maintenance windows, advisory notes, customer-visible messaging during degraded states.
  • Implement per-domain and per-substrate status surfaces for tenants with escalation contacts and breach-of-SLA notification.
  • Implement banner system for in-product status messaging (severity, audience scoping, locale, dismissal).
  • Implement postmortem catalog with searchable, filterable, public-or- private RCAs bound to internal incident records.
  • Tests for status fidelity against component health, banner targeting, subscriber delivery, maintenance-window visibility, and postmortem scoping.

21. Trust and Safety#

21.1 Policy taxonomy enforcement#

  • Enforce content-policy categories (hate, harassment, sexual content with NSFW classes, graphic violence, self-harm content, illegal content (CSAM/terrorism/weapons/drugs by jurisdiction), defamation, doxxing, electoral disinformation, health disinformation, scams, financial exploitation).
  • Enforce assistant-behavior categories (persona drift, jailbreak, prompt injection, deceptive role-play, off-policy advice, harmful instruction generation, political-influence, unauthorized memory access).
  • Enforce voice/avatar/synthetic-media categories (deceptive realism, identity impersonation, non-consented likeness, deepfake, voice-clone abuse, watermark removal).
  • Enforce educational-content categories (fabricated citations, retracted-source use, plagiarism, exam-integrity violation, answer- key leakage, misrepresentation of standards alignment).
  • Enforce support/customer-ops categories (operator harassment of customers, unauthorized data access, refund abuse, social engineering).

21.2 Severity classes and SLAs#

  • Implement P0 — imminent harm (CSAM, credible self-harm/suicide, credible violence-to-others, non-consensual sexual imagery, child- protection signals): triage < 5 min, action < 15 min by crisis-trained reviewer, parallel safety-incident record opened, post-incident review mandatory.
  • Implement P1 — high severity (hate, harassment campaigns, identity impersonation, voice-clone abuse, exam-integrity fraud, repeat- offender escalation): triage < 30 min, action < 2 h.
  • Implement P2 — moderate severity / low-confidence flag: triage < 8 h, action < 48 h.
  • Implement P3 — informational / pattern-only: weekly aggregate review.
  • Implement escalation rules: P2 → P1 on second occurrence within 30 days; P1 → P0 on credible threat extraction; auto-escalation triggers (named target, credible plan, geographic specificity).

21.3 Decision classes and appeals#

  • Implement appealable decisions list (content removal, account suspension < 30 days, persona suspension, comment hiding, recommendation suppression, voice/avatar entitlement suspension, billing-action reversal).
  • Implement non-appealable list (CSAM removal, credible-threat suspension, legal-hold actions, court-ordered) with operator runbook.
  • Implement appeal lifecycle: receive → triage (different reviewer) → second-reviewer review → decision (uphold/overturn/partial) → notify → audit. SLA per severity.
  • Implement two-reviewer signoff for P0, permanent ban, large-account suspension, public-figure decisions, cloned-voice/avatar decisions, decisions overriding Lilith policy.
  • Enforce reviewer rotation (appeals routed to a different reviewer with mandatory cooling-off).

21.4 Crisis handling#

  • Implement detection (model-classifier signal, user self-report, third-party report, pattern-match across sessions, escalation from support copilot).
  • Implement routing to crisis-trained reviewer queue with 24/7 coverage, bypass of normal severity, parallel customer-care follow-up where consented.
  • Implement region-aware crisis resource delivery (hotlines, text lines, emergency contacts), language-matched, accessibility-friendly.
  • Implement post-crisis opt-in check-in, audit-retained event record, no-recommendation cooldown.
  • Implement mandatory reporting per jurisdiction (CSAM, credible threats) with operator runbook and per-region legal contact.

21.5 Abuse-pattern detection#

  • Implement repeat-offender rules with per-user counters across policy classes, escalating consequences (warn → restrict → suspend → ban) and false-positive-rich exception classes.
  • Implement coordinated-abuse cluster signals across users (same prompt fingerprint, same target, same time window, same IP/device cluster).
  • Implement bot/scripted-abuse signals (rapid retry after refusal, prompt-permutation, tool-call exfiltration).
  • Implement drift-pattern detection (classifier drift, FP/FN rate drift, per-domain drift).
  • Implement tenant-aggregate signals (per-tenant abuse rate, anomalous spikes, cross-tenant outlier comparison).

21.6 Operator surfaces#

  • Implement appeal evidence pack generation (original content, policy hit, classifier output, prior incidents, prior appeals, account context, persona context, resolution rationale).
  • Implement repeat-offender summary timeline.
  • Implement safety dashboard (per-class volume, P0/P1 SLA attainment, appeal outcomes, classifier health, drift alerts, drift cohort breakdowns, crisis-event stats).
  • Implement trend dashboards (weekly/monthly, per-domain, per-tenant, cross-locale).

21.7 Evaluation and release blocking#

  • Implement per-class evals (content, contemplative, voice, avatar, exam, crisis).
  • Implement adversarial suites (prompt injection, jailbreak templates, cloned-voice abuse, deepfake generation, exam-cheat).
  • Implement calibration evals (classifier calibration, per-locale fairness, demographic-slice FP/FN parity).
  • Block release on any safety eval regression; require champion- challenger gate for classifier updates.
  • Implement live-evaluation production sampling with operator review and ongoing gold-set updates.

  • Implement memory consent per scope (profile/session/notebook) and per sensitive category; default off for sensitive, default on for non-sensitive with clear notice.
  • Implement voice consent (recording, cloning of own voice, cloned-voice use in personas, voice-data analytics).
  • Implement avatar consent (likeness capture, generated likeness, animation rights, tenant-scoped distribution).
  • Implement synthetic-media consent (AI generation on uploads, derivative works, tenant publication).
  • Implement notifications consent per channel/domain/severity/quiet-hours.
  • Implement privacy-sensitive surface consent (research data sharing, analytics granularity, third-party processor inclusion, training-data inclusion default off).
  • Implement support consent (agent-screen-share, agent-memory-access, session recording).
  • Implement research consent per study.
  • Implement educational-context consent (assignment data sharing with teacher/institution/standards reporting).

22.2 Granularity, default state, withdrawal#

  • Enforce per-feature opt-in: no bundled "accept all" covering sensitive.
  • Enforce default state (opt-out for sensitive/training-data/third-party/ cross-tenant; opt-in for non-sensitive baseline analytics).
  • Implement withdrawal cascade with effective-immediately on storage/ recall; propagation to derived artifacts as job state with ETA.
  • Audit every consent transition (timestamp, actor, reason code, prior, new).

22.3 Region, residency, routing#

  • Enumerate supported regions per release with primary plane and secondary failover.
  • Enforce primary residency: data created in a region remains in that region's primary plane unless cross-region consent.
  • Implement cross-region exception workflow (legal hold, security incident, operator-explicit-with-consent).
  • Publish subprocessor list with per-customer notification on changes.
  • Enforce residency in BFF / generation / provider call routing.
  • Enforce cache-warming residency boundaries.
  • Segregate logs by region.
  • Track cross-region propagation to completion.

22.4 Export, deletion, retention#

  • Implement export scopes (profile, conversation history, memory, notebooks, journals, ritual completions, claims/passages saved, generated artifacts, audit visible to user, support history, billing receipts).
  • Implement export formats (JSON canonical, CSV where structured, Markdown where prose) with integrity manifest and consent context.
  • Implement deletion scopes (per-scope and full account) with cascade to derived artifacts; tombstones to prevent re-creation; audit retained per legal-required minimums.
  • Implement 30-day soft-delete window (configurable per tenant 24 h – 90 d) with hard delete and cryptographic shred where feasible.
  • Implement per-data-class retention rules (raw chat 30 d, summarized profile durable, billing 7 y, audit per regulatory minimum, generated artifacts per artifact policy).
  • Implement legal hold suspending deletion with operator audit; user notified at end-of-hold per policy.

22.5 Customer-facing privacy surface#

  • Implement privacy center (single in-product surface listing every consent, memory state, export, deletion, residency choice, audit-of-operator-access) with one-click open from any prompt.
    • 2026-06-25 progress: /profile/data now reads consent/export/deletion state from real authenticated dev BFF routes end to end. The old /v1/data-rights/consent domain-stub fixture was replaced with a consent-store projection, and Playwright now covers consent transition reflection, empty export/deletion readback, seeded completed export + scheduled deletion snapshots, anonymous gate, 50-row export history cap, download aria labeling, mobile 44px controls, and axe.
  • Implement per-feature privacy reveal ("what this uses, where it goes, how to turn it off").
  • Implement disclosure copy at jurisdiction-required reading level, reviewed under Lilith tone policy.
  • Implement consent prompts at first relevant feature use (never buried in onboarding); remembered on dismissal until invoked again.

22.6 DSAR and operator-access workflow#

  • Implement DSAR intake (customer or authorized representative, identity verification, jurisdictional eligibility check).
  • Implement scope determination (full vs scoped, per-data-class breakdown).
  • Implement async execution with progress ETA, per-class completion verification, integrity manifest.
  • Implement restore (time-windowed, elevated approval, per-tenant policy may forbid).
  • Implement operator-access (non-DSAR) for support/safety/privacy/ research roles with reason code, time-bound scope, audit, and two-operator authorization for sensitive categories; user notification post-hoc within compliance window.

22.7 Compliance and audit#

  • Document per-region applicable regimes (GDPR, CCPA/CPRA, LGPD, PIPEDA, state US, education-data laws) at docs/oshun/privacy/regulatory-coverage.md.
  • Implement mandatory disclosures (synthetic-content per Lilith, AI use, third-party processor list, breach notice, retention policy).
  • Implement breach response runbook (detect → contain → assess → notify per regulatory clock → remediate → postmortem → disclosure).
  • Audit completeness: every consent transition, operator access, deletion, export, cross-region move logged immutably.
  • Tests: consent enforcement, withdrawal cascade, deletion completeness, restore authorization, residency routing, audit completeness, DSAR end-to-end, breach-runbook drills.

23. Support, Entitlements, Billing#

  • Implement entitlement classes, subscription models, trial behavior, upgrade/downgrade, renewal, cancellation, restore, premium persona access, billing history, invoices/receipts, plan details, feature gates, intro offers.
  • Implement web and mobile paywalls + upgrade surfaces + entitlement- aware gating for premium assistant/study/persona/voice/avatar/ generated experiences.
  • Implement trial-expiry behavior, conversion prompts, payment-method update reminders, payment-failure handling, dunning sequences, grace windows, graceful feature degradation on lapse.
  • Implement customer self-serve refund/credit/plan-change/pause-resume/ gift-codes/promo-codes; tenant-scoped invoicing for institutional contracts.
  • Implement tax/region/currency-aware billing, invoice formatting, VAT/GST collection, receipts, locale-correct billing communications.
  • Implement metered billing for agentic AI usage / voice seconds / avatar seconds / storage / consumption-class entitlements with per-user usage meters, alerts, budget caps.
  • Implement support case intake/routing/timeline/account context/ memory-privacy handling/refund/credit/exception grant-revoke/issue tags/root-cause reporting/escalation to safety-engineering-product.
  • Implement support copilots with grounded answers.
  • Implement omnichannel conversation history, cross-device troubleshoot, first-response SLAs, resolution SLAs, CSAT capture, reporting.
  • Tests: support / billing / entitlement / upgrade / cancellation / dunning / refund / metered-usage / support-case-handling.

23.1 Crypto Payments — Non-Custodial Settlement (V1 primary payment rail)#

Surface: the Aje domain (libs/aje/, Yoruba orisha of wealth and commerce — the existing library-only Web3 infrastructure) plus a new V1 bridge at libs/oshun/payments-bridge/. V1 contributes five new chain modules to Aje (Monero, Litecoin, TON, Ergo, Tron) and the Oshun-specific bridge that maps Aje's merchant invoices onto the V1 entitlement event bus.

Architecture in ARCHITECTURE.md § Crypto Payment Substrate and the Aje domain summary ARCHITECTURE.md § Aje. Feature spec in features.md § Crypto Payments — Non-Custodial Entitlement Settlement. Dependencies in DEPENDENCIES.md § 13 V1 primary — non-custodial crypto. Aje's own catalogue: DOMAINS/aje/features.md, DOMAINS/aje/architecture.md.

Operational invariants that every task below must preserve:

  • Application server holds view keys and watch-only xpubs only for every chain; spend keys never touch the hot path (Bitcoin/Litecoin BIP32 master private keys, Monero secret spend keys, EVM master private keys, Solana keypairs, TON wallet private keys, Cardano payment keys, Ergo spend keys, Tron private keys).
  • Per-invoice fresh derivation paths, Monero subaddresses, or per-invoice wallet contracts (TON); address reuse is a contract-layer rejection on every chain.
  • Telemetry stores only the hash of any per-invoice identifier (Monero subaddress, Solana reference pubkey, TON subwallet contract address). No on-chain customer identifiers anywhere: no OP_RETURN (Bitcoin / Litecoin), no Monero tx_extra payment IDs, no Solana memo-program customer IDs, no TON message-comment customer IDs.
  • Trust-tier disclosures are mandatory: every invoice on a Tier-B or Tier-C rail or in a centrally-issued asset (USDC, USDT) requires the customer's acknowledgement timestamp before address rendering.
  • The same libs/shared/event-bus topics serve both crypto and fiat rails so entitlement/audit/admin surfaces stay rail-agnostic.

23.1.1 Aje promotion + V1 bridge scaffolding#

  • Promote Aje (libs/aje/) into V1 critical-path scope: add Aje row to V1/DEPENDENCIES.md § 2 (already done in this commit) and verify that every libs/aje/* package builds, lints, and passes its existing tests cleanly from the V1 CI lane.
  • Scaffold libs/aje/chains/monero/, libs/aje/chains/litecoin/, libs/aje/chains/ton/, libs/aje/chains/ergo/, and libs/aje/chains/tron/ following the existing libs/aje/chains/<chain>/ pattern (project.json, package.json, tsconfig.json, src/index.ts exporting a <Chain>Provider). Each module preserves Aje's "TypeScript-only" rule by isolating non-TS cryptography to upstream node processes; the TypeScript module owns only the JSON-RPC client.
  • Scaffold libs/oshun/payments-bridge/ with project.json, package.json, tsconfig.json; add path mapping to tsconfig.base.json; build + lint clean. Depends on @aje/payments, @aje/chains, @aje/wallets, @aje/oracles, @oshun/event-bus, @oshun/audit-platform, @oshun/identity.
  • Extend the Aje merchant invoice contract in libs/aje/payments/src/merchant/types.ts with the V1-required fields if they are not already present: chain_tier (A | B | C), issuer_trust_class (native | decentralized-issuer | central-issuer-with-freeze), disclosure_acknowledged_at, entitlement_id, tenant_id, fiat_rate_lock, slippage_tolerance_bps. Backwards-compatible (V1 fields are optional on the Aje side, required on the bridge side).
  • Implement the asset enum in libs/oshun/payments-bridge/src/state-mapper.ts covering the full V1 accept-list — native: btc-onchain, btc-lightning, ltc, xmr, eth-mainnet, eth-base, eth-arbitrum, eth-optimism, matic-polygon, sol, ton, ada, erg; stablecoins: usdc-mainnet, usdc-base, usdc-arbitrum, usdc-optimism, usdc-polygon, usdc-solana, usdt-mainnet, usdt-base, usdt-arbitrum, usdt-optimism, usdt-polygon, usdt-tron, usdt-solana, usdt-ton, dai-mainnet, dai-base, dai-arbitrum, dai-optimism, dai-polygon.
  • Implement Aje → V1 state mapping in libs/oshun/payments-bridge/src/state-mapper.ts: Aje InvoiceStatus.paid + ConfirmationStatus.confirmed/.finalized (per tier) → V1 payment.invoice.settled + entitlement_granted; InvoiceStatus.partial → V1 payment.invoice.underpaid; InvoiceStatus.refunded → V1 payment.refund.broadcast; InvoiceStatus.expired/.cancelled → V1 payment.invoice.expired. Transitions append immutable audit-platform records.
  • Implement per-tier confirmation policy lookup in libs/oshun/payments-bridge/src/state-mapper.ts covering every supported chain — BTC: 0 / 1 / 3 by amount tier; LTC: 1 / 3 / 6; XMR: 10 / 20 unlocks; ETH L1: 12 / 30; EVM L2 rollups: rollup safe-head depth per chain (Base ~150, Arbitrum ~50, Optimism ~120); Polygon: 256 (heimdall checkpoint); Solana: confirmed / finalized; TON: 1 / 3 masterchain blocks; ADA: 15 / 30 blocks; ERG: 5 / 10 / 30; Tron: 19 blocks (≈1 min) for USDT-TRC20. The policy is supplied to the Aje MerchantInvoice.confirmationRequired field at creation time.
  • Implement the trust-tier registry in libs/oshun/payments-bridge/src/trust-tier-disclosure/ with per-rail decentralization tier (A / B / C) and per-asset issuer-trust class (native / decentralized-issuer / central-issuer-with-freeze). Includes the disclosure-copy strings reviewed by Lilith policy at each release.
  • Implement invoice-creation enforcement in the bridge: every invoice on a Tier-B or Tier-C rail or a centrally-issued asset (USDC, USDT) records the customer's disclosure acknowledgement timestamp before delegating to Aje's @aje/payments/merchant for address issuance. Missing acknowledgement → invoice creation fails with a structured error.
  • Tests: state-machine mapping (Aje ↔ V1 event equivalence); tier confirmation lookup per chain; contract drift against persistence + OpenAPI codegen; disclosure enforcement rejects un-acknowledged Tier-B/C/central-issuer invoices; build + lint clean for the bridge and every Aje chain module.

23.1.2 Bitcoin on-chain — add BTCPay Server adapter to @aje/bitcoin#

  • Implement libs/aje/bitcoin/src/btcpay/btcpay-server.ts with per-store API key, signed webhook verification, and BIP84 xpub-derived per-invoice address issuance (m/84'/0'/0'/0/*).
  • Implement RBF fee-bump detection: if an incoming tx is replaced before first confirmation, the new tx is observed and amount/destination re-validated against the invoice.
  • Wire watch-only-mode invariant test: attempt to call any spend-capable BTCPay API; assertion fails the build.
  • Tests: regtest end-to-end (bitcoind -regtest) — invoice creation → payment → 1 confirmation → entitlement event → induced 2-block reorg → state correctly rewinds to seen and re-confirms.

23.1.3 Bitcoin Lightning — wire @aje/bitcoin/lightning to the merchant invoice flow#

  • Implement libs/aje/bitcoin/src/btcpay/lightning.ts for BOLT11 invoice issuance through the BTCPay Lightning backend. Backend selection (LND / CLN / Phoenixd) is operator config; the lib must abstract over all three.
  • Implement hold-invoice support for refundable flows (preimage held until the entitlement is granted; refunded by simply not releasing).
  • Implement AMP / keysend streaming for metered usage top-ups.
  • Tests: hold-invoice settle-and-cancel paths on a Polar / lnd-regtest cluster; payment-hash uniqueness; keysend metered-credit accrual.

23.1.4 Monero — new chain module @aje/chains/monero (first-class XMR)#

  • Implement libs/aje/chains/monero/src/monerod-client.ts — JSON-RPC client against self-hosted monerod for get_info, get_block_count, get_block_header_by_height, mempool inspection.
  • Implement libs/aje/chains/monero/src/wallet-rpc.ts — monero-wallet-rpc client in view-only mode. Required RPCs: create_address (account 0, fresh subaddress_index), get_transfers (pool + in + pending + confirmed), get_tx_proof, get_height. Build asserts the wallet was opened from a view-only key file; refuses to start if a spend key is detected.
  • Implement libs/aje/chains/monero/src/subaddress-allocator/ with a Postgres advisory lock for concurrent invoice creation; persistent subaddress_index ↔ invoice_id mapping; refuses to return any previously-issued index even on retry/replay.
  • Implement 10-block unlock confirmation policy with high-value-tier override (20+ blocks configurable).
  • Implement payment-proof attachment: every receipt carries (txid, tx_key, address) tuple obtained via get_tx_proof; receipt payload includes the verification snippet a customer can run against a remote node.
  • Implement refund flow: customer-initiated refund requires destination address (no on-chain return path in Monero). Unsigned transfer is generated for cold-spend signing; signed broadcast attaches to the refund audit record.
  • Implement subaddress-hash telemetry: only the BLAKE2b-256 hash of a subaddress is ever written to logs, metrics, or analytics. Plaintext subaddresses are pinned to the invoice record and never aggregated.
  • Implement no-tx_extra-payment-id invariant: any code path attempting to attach a payment ID (long or short) to a Monero transaction fails the build. The subaddress is the only on-chain correlator.
  • Tests: stagenet end-to-end via monero-stagenet Docker image — invoice → subaddress issued → payment → 10-block unlock → entitlement event; concurrent invoice creation (100 parallel) issues 100 distinct subaddresses; underpayment within tolerance auto-credits; overpayment opens refund-or-credit; payment-proof verifies against a remote node with no Oshun trust; refund cold-spend flow with hardware-wallet co-signing fixture.

23.1.5 Litecoin — new chain module @aje/chains/litecoin#

  • Implement libs/aje/chains/litecoin/src/core-client.ts — JSON-RPC client against self-hosted Litecoin Core; BIP84 xpub-derived per-invoice addresses (m/84'/2'/0'/0/*); 1 / 3 / 6 confirmation tiers.
  • Implement RBF fee-bump detection paralleling the Bitcoin adapter.
  • Tests: litecoind -regtest end-to-end — invoice → payment → 1 conf → entitlement event → induced reorg correctly rewinds.

23.1.6 EVM — extend @aje/chains/abstraction chain registry (Ethereum L1, Base, Arbitrum, Optimism, Polygon)#

  • Implement libs/aje/chains/abstraction/src/chain-registry.ts — per-chain native asset (ETH on Ethereum/Base/Arbitrum/Optimism, MATIC on Polygon), canonical USDC / USDT / DAI contract addresses, chain ID, and decentralization tier (A for Ethereum L1; B for Base / Arbitrum / Optimism / Polygon).
  • Implement libs/aje/chains/abstraction/src/xpub-watcher.ts — BIP44 derivation (m/44'/60'/0'/0/*); per-invoice address; native-ETH/MATIC transfer indexing; ERC-20 Transfer log indexing for USDC, USDT, and DAI on every supported chain.
  • Implement libs/aje/chains/abstraction/src/multi-rpc-consensus.ts — N-of-M agreement across self-hosted Erigon (Ethereum L1) or self-hosted rollup node (op-geth / Nitro / bor) plus two public providers (Alchemy / Infura / Ankr). Default N=2, M=3; threshold auto-raises to 3-of-3 during regional failover.
  • Implement chain-aware reorg depth: Ethereum L1 12 / 30 blocks (justified / finalized); Base ~150; Arbitrum ~50; Optimism ~120; Polygon 256 (heimdall checkpoint).
  • Implement ENS resolution for refund destinations (ENS resolves only against Ethereum L1; refund delivery happens on the chain of the original invoice).
  • Implement issuer-trust disclosure rendering for USDC/USDT invoices: the paywall surface displays the Circle / Tether freeze-authority note plus the chain decentralization tier note before address rendering.
  • Tests: Anvil-forked devnet end-to-end per chain (Ethereum L1, Base, Arbitrum, Optimism, Polygon); induced reorg below safe-head depth correctly rewinds; multi-RPC quorum failure raises the threshold and surfaces an operator alert; native + USDC + USDT + DAI invoice happy paths on each chain; disclosure rendering parity test.

23.1.7 Solana — extend @aje/chains/solana for V1 merchant flow (SOL + USDC-SOL + USDT-SOL)#

  • Implement libs/aje/chains/solana/src/rpc-client.ts — self-hosted Solana RPC node client + multi-RPC consensus across Helius / QuickNode / Triton; rotation on rate limit.
  • Implement per-invoice ed25519 derivation (m/44'/501'/<i>'/0') from a watch-only seed; System Program (native SOL) and Token Program SPL Transfer indexing for USDC-SOL and USDT-SOL.
  • Implement Solana Pay URL scheme generation for the customer QR (solana:<recipient>?amount=…&spl-token=…&reference=…); reference is a per-invoice ed25519 pubkey, not a customer identifier.
  • Implement confirmed (default) vs finalized (high-value tier) commitment policy.
  • Implement issuer-trust disclosure for USDC-SOL / USDT-SOL and the Tier-B Solana validator-centralization + historical-outage note.
  • Tests: solana-test-validator end-to-end — invoice → SOL payment; invoice → USDC-SOL payment; invoice → USDT-SOL payment; commitment tier escalation; multi-RPC quorum failure; disclosure rendering.

23.1.8 TON — new chain module @aje/chains/ton (native TON + USDT-TON)#

  • Implement libs/aje/chains/ton/src/full-node-client.ts — self-hosted ton-http-api plus multi-RPC consensus across tonapi.io and toncenter.com; per-provider health tracking.
  • Implement per-invoice v4r2 wallet contract derivation from a watch-only walletId + per-invoice subwallet index.
  • Implement native-TON inbound message indexing and jetton (USDT-TON) Transfer indexing.
  • Implement Telegram @wallet deep-link generation for the customer QR and bot button.
  • Implement the Tier-C disclosure rendering ("TON network governed by the TON Foundation; validator set is more centralized than Bitcoin or Ethereum") plus the Tether issuer disclosure for USDT-TON.
  • Tests: TON sandbox (@ton/sandbox) end-to-end — native-TON invoice → payment → confirmation; USDT-TON jetton invoice; deep-link round-trip from @wallet; disclosure rendering.

23.1.9 Cardano — extend @aje/chains/cardano for V1 merchant flow (ADA only)#

  • Implement libs/aje/chains/cardano/src/node-client.ts — Ogmios or cardano-wallet HTTP client against self-hosted cardano-node; per-invoice CIP-1852 address derivation (m/1852'/1815'/0'/0/<i>) from a watch-only account xpub.
  • Implement UTXO-set polling for inbound payments matching the per-invoice address; 15 / 30 confirmation tiers (1 block ≈ 20 s).
  • Disable native multi-asset acceptance for V1 (only ADA is settled on this chain). Inbound tx with native tokens attached → invoice goes to unsupported_asset state with a refund proposal.
  • Tests: Cardano preview testnet end-to-end — invoice → payment → 15 confs → entitlement event; multi-asset rejection path; reorg handling.

23.1.10 Ergo — new chain module @aje/chains/ergo#

  • Implement libs/aje/chains/ergo/src/node-client.ts — ergo-wallet-api watch-only HTTP client against self-hosted ergo-node; per-invoice BIP44 P2PK derivation (m/44'/429'/0'/0/<i>).
  • Implement UTXO-set polling for inbound payments; 5 / 10 / 30 confirmation tiers.
  • Implement NIPoPoW-friendly receipt format that lets a light client verify the payment without trusting Oshun's API.
  • Tests: Ergo testnet end-to-end — invoice → payment → confirmation tier → entitlement event; NIPoPoW receipt verification against a remote node.

23.1.11 Tron — new chain module @aje/chains/tron (USDT-TRC20 only)#

  • Implement libs/aje/chains/tron/src/node-client.ts — self-hosted java-tron + multi-RPC consensus across TronGrid and GetBlock; per-invoice BIP44 m/44'/195'/0'/0/* address derivation.
  • Implement TRC-20 Transfer event indexing scoped to USDT-TRC20 (the only Tron asset accepted at V1).
  • Implement 19-block confirmation policy (≈1 min); native TRX is not accepted at V1 (volume there is not material for Oshun).
  • Implement the Tier-C disclosure rendering ("Tron uses DPoS with 27 Super Representatives; the network has substantial central influence") plus the Tether issuer disclosure. Invoice creation requires acknowledgement.
  • Tests: Tron Nile testnet end-to-end — invoice → USDT-TRC20 payment → 19 confs → entitlement event; native-TRX rejection; disclosure enforcement.

23.1.12 Fiat-rate oracle and price lock#

  • Implement libs/oshun/payments-bridge/src/oracle-aggregator/price-feed.ts — Kraken REST + CoinGecko REST + Uniswap v3 TWAP; median across sources; spread captured per invoice; rejection threshold for excessive spread.
  • Implement Tor egress for rate fetches via socks-proxy-agent against a self-hosted Tor instance; fall back to clearnet with telemetry flag if Tor is unavailable.
  • Implement per-invoice rate lock with configurable window (default 15 min L1, 30 min L2, 60 min Lightning) and slippage tolerance.
  • Tests: divergent-source rejection; rate-lock expiry transitions invoice to expired; Tor egress is exercised in the integration suite.

23.1.13 Cold-spend refund and sweep pipeline#

  • Implement libs/oshun/payments-bridge/src/cold-spend-queue/ queue with per-chain unsigned-transaction emitters: PSBT for Bitcoin and Litecoin; EIP-1559 tx for every EVM chain (L1, Base, Arbitrum, Optimism, Polygon); Monero unsigned transfer; Solana versioned transaction; TON external message; Cardano CBOR-encoded transaction; Ergo UnsignedTransaction; Tron raw transaction. Air-gapped signing station consumes the queue.
  • Implement sweep policy: receipts above the sweep threshold consolidate to the 2-of-3 multisig vault per chain family — Bitcoin / Litecoin native SegWit multisig; EVM Safe (covers L1, Base, Arbitrum, Optimism, Polygon); Monero MMS multisig; Solana SPL multisig; TON multisig contract; Cardano Plutus-script multisig; Ergo P2S multisig; Tron multisig contract. Hot wallet balance stays bounded per chain.
  • Implement hardware-wallet co-signing fixture covering every chain (Trezor / Ledger / Coldcard via PSBT for BTC + LTC; Safe transaction for every EVM chain; Monero MMS for XMR; Ledger Solana app for SOL; Ledger / Tonkeeper for TON; Ledger / Trezor Cardano app for ADA; Ergo Auth+Sign for ERG; Ledger Tron app for TRX) so the integration test can exercise the full signing flow offline.
  • Implement audit-platform attestation per signing event: signer identity, txid, asset, amount, destination, and a hash of the signing device firmware version.
  • Tests: refund-queue durability across restarts; signing-fixture end-to-end per chain family; sweep-threshold breach triggers consolidation per chain.

23.1.14 Receipt issuance and signing#

  • Implement libs/oshun/payments-bridge/src/receipt-signer/ — receipts carry txid, block hash, block height, asset, amount, fiat-equivalent at confirmation, and (for Monero) (txid, tx_key, address). Receipts are signed by an audit-platform key; the receipt payload includes the verification snippet so a customer holding only the receipt and the chain can verify without trusting Oshun.
  • Implement receipt locale + tax formatting reuse from the existing § 23 billing receipt formatter so crypto receipts are visually and legally consistent with fiat receipts.
  • Tests: offline receipt verification (signature + chain inspection) for every supported asset; tax/locale parity with fiat receipts.

23.1.15 Webhook → entitlement bus#

  • Wire crypto confirmation events to libs/shared/event-bus topics payment.invoice.confirmed, payment.invoice.settled, payment.refund.broadcast. Schema is identical to the fiat-adapter emissions in libs/shared/inbound-integrations/src/payment.ts.
  • Implement equivalence test asserting the entitlement service receives a structurally identical event payload regardless of rail.
  • Tests: end-to-end — invoice settled on BTC regtest, LTC regtest, Monero stagenet, Anvil devnet (per EVM chain), solana-test-validator, TON sandbox, Cardano preview, Ergo testnet, and Tron Nile each produce the same entitlement-event shape.

23.1.16 Customer surface (web + mobile + Telegram)#

  • Implement paywall surface at apps/oshun/web/src/app/billing/crypto/ that renders a per-invoice address / BOLT11 / subaddress / Solana Pay URL / TON deep link + QR code; chain picker lists every supported chain with its trust-tier badge; no redirect to a custodial processor.
  • Implement asset picker that filters chains by selected asset (BTC → on-chain + Lightning; LTC → on-chain; XMR → on-chain; ETH → 5 EVM chains; SOL → solana; TON → ton; ADA → cardano; ERG → ergo; USDC → 6 chains; USDT → 8 chains; DAI → 5 chains).
  • Implement disclosure-acknowledgement gate for Tier-B / Tier-C / central-issuer invoices: customer must click through the specific trust-note copy before the address is rendered.
  • Implement mobile invoice surface with QR rendering and clipboard copy under apps/oshun/mobile/src/screens/billing/CryptoInvoice.tsx, including Solana Pay and TON deep-link buttons.
  • Implement Telegram-bot surface that renders BOLT11 strings, Monero subaddresses, Solana Pay URLs, or TON @wallet deep links on request (/upgrade --crypto <asset>) with same crisis-state suppression as Telegram Payments.
  • Implement renewal-window invoice reminders (7 d / 24 h / 1 h before expiry) reusing the existing notification fan-out.
  • Tests: paywall rendering parity across web + mobile per chain; asset/chain filter correctness; disclosure-gate enforcement; Telegram bot command exercises every chain's invoice issuance path; reminder cadence verified.

23.1.17 Admin and support surfaces#

  • Extend admin billing surfaces to show crypto invoice state alongside fiat invoices: invoice list, state filters, per-invoice timeline (created → seen → confirmed → settled), per-chain tx links to a non-tracking block explorer (mempool.space for BTC, litecoinspace.org for LTC, the official Monero explorer for XMR, etherscan/basescan/arbiscan/ optimistic.etherscan/polygonscan for EVM, solscan/solana-fm for Solana, tonviewer for TON, cardanoscan for Cardano, sigmaspace.io for Ergo, tronscan for Tron — operator-configurable to any equivalent explorer).
  • Implement per-chain node-health panel: green/amber/red for each self-hosted node plus multi-RPC quorum status.
  • Implement admin refund initiation that emits an unsigned-tx queue entry with the chain-correct artifact; admin UI shows the cold-signing queue and pending hardware approvals per chain.
  • Implement admin invariant guards: any attempt from the admin surface to read a spend key, BIP32 master private key, Monero secret spend key, Solana keypair, TON wallet private key, Cardano payment key, Ergo spend key, or Tron private key returns 404; the application server has no path to load them.
  • Tests: admin invoice-list parity with fiat; refund queue UI exercises the cold-signing fixture per chain; node-health panel reflects induced node outages.

23.1.18 Security, audit, and launch gates#

  • Implement build-time invariant checks: monero-wallet-rpc startup flag asserts --wallet-file points at a view-only wallet; any OP_RETURN write (Bitcoin/Litecoin), Monero tx_extra payment-ID write, Solana memo program write with customer IDs, or TON message comment with customer IDs fails the build; per-chain key-loading is restricted to the cold-signing-station codepath only (build-time grep).
  • Implement chaos test per chain: kill the self-hosted node mid- confirmation; multi-RPC consensus must auto-raise threshold and continue, OR halt cleanly with an operator-actionable alert. Run for Bitcoin Core, Litecoin Core, monerod, Erigon, op-geth/Nitro/bor, Solana RPC, TON node, cardano-node, ergo-node, and java-tron.
  • Implement node-health probes for every self-hosted node (Bitcoin Core, Litecoin Core, monerod, Erigon, op-geth + op-node, Arbitrum Nitro, Polygon bor + heimdall, Lightning backend, Solana RPC, TON node, cardano-node, ergo-node, java-tron) feeding libs/shared/queue/src/sla-monitor.ts and the launch-readiness dashboard.
  • Implement per-rail trust-tier rendering audit: every Tier-B and Tier-C invoice path is exercised in a snapshot test that confirms the disclosure copy is present, accurate, and not visually suppressed.
  • Run a tabletop test for a cold-spend-station compromise scenario: validate the hot path cannot exfiltrate funds; validate the audit trail flags the unauthorized signing attempt.
  • Tests: adversarial scan from CLAUDE.md returns zero actionable hits against the V1-touched code in libs/aje/chains/{monero,litecoin,ton,ergo,tron}/, libs/aje/bitcoin/btcpay/, and libs/oshun/payments-bridge/; receipt offline verification passes for every supported asset; entitlement equivalence test passes against both rails.

23.2 Fiat Payments — Stripe Billing, Apple Pay, Google Pay (added 2026-07-04)#

Surface: libs/oshun/fiat-payments/ (@oshun/fiat-payments) + BFF routes at apps/oshun/bff/src/payments/fiat-routes.ts (/v1/payments/fiat/*). Architecture: architecture/fiat-payments-and-wallets.md.

  • Stripe Billing rail: Stripe-Signature webhook verification (raw-byte HMAC, ±300 s tolerance, secret rotation, constant-time compare; known-vector test), Stripe event → settlement/subscription-sync normalizer, subscription-lifecycle reconciliation onto the billing-support state machine (BFS over transitionSubscription as the legality oracle), price catalog with oshun_<class>_<interval> lookup keys + release-gate validation, typed form-encoding REST client (fail-loud without STRIPE_SECRET_KEY), idempotent settlement processor (Stripe event-id replay guard).
  • Crypto/fiat entitlement-event parity: FiatEntitlementEmitter emits the payments-bridge PaymentBusEvent topics on rail: 'fiat-stripe'; cross-rail structural-equivalence + key-set-equality test.
  • Apple Pay: EC_v1 ECIES decryption (SP 800-56A KDF, AES-256-GCM zero IV) with merchant-key selection by publicKeyHash; detached CMS (RFC 5652) signature verification with from-scratch DER/X.509 parsing, full chain walk to a pinned root (P-256/SHA-256 + P-384/SHA-384), Apple marker-OID enforcement, signing-time freshness; fixtures generated by OpenSSL + an independent node:crypto encryptor; merchant-validation SSRF allowlist + fail-closed mTLS seam; Stripe-tokenized server leg.
  • Google Pay: ECv2 signature-chain verification (root → intermediate → message, little-endian length-prefixed signed strings, key expirations) + ECIES decryption (HKDF-SHA256, AES-256-CTR, HMAC tag checked before decrypt, merchant key rotation); round-trip + adversarial tests against an independent in-test implementation; gateway (Stripe) config route.
  • BFF wiring: fail-closed checkout/webhook/wallet/status/events routes, member↔Stripe bindings, local subscription minting from real event periods (unattributable events surface support notes, never guesses), entitlement-plan sync on every subscription change (downgrades included).
  • Live-mode operational plane: real STRIPE_SECRET_KEY + STRIPE_WEBHOOK_SECRET in deploy env, Stripe price catalog seeded with the canonical lookup keys, Apple Pay merchant identity certificate bound to the mTLS seam + payment-processing key, Google Pay merchant id + production root-keys JSON, Apple Root CA - G3 pin. (Deployment credentials — not fabricatable in-repo; every route fails closed until bound.) Board tag 2026-09-18: merchant credentials and certificates are the owner's. blocked:external

24. Civitai, ComfyUI, RunPod, Voice Providers#

Audit found contracts and provider libs are substantive (libs/isis/ai-providers/, libs/yemaya/comfyui-integration/, libs/shared/runpod-client/) but the human-facing surfaces are missing or stubbed. Customer-Studio routes for generation tools (apps/oshun/web/src/app/studio/isis/*) currently render placeholder workspaces; admin operator surfaces for the generation factory (graph editor, intake review queue, RunPod endpoint dashboard, LoRA training queue, voice-cloning workflow, output gallery) do not exist. This section specifies the missing surfaces and the audience-tier boundary that determines which surfaces ship on the contemplative product vs. Yemaya AAA Studio.

24.1 Audience tiers and surface boundaries#

The same provider stack serves three distinct audiences with non-overlapping exposure profiles. Surfaces must be entitlement-gated; raw generation machinery must never appear on the contemplative product.

  • Document tier matrix at docs/oshun/generation-tiers.md mapping the three tiers (operator/admin, curated-creator, AAA-creator) × surface families (Civitai, ComfyUI, RunPod, voice, music, 3D, output gallery) to which route ships, which entitlement gates it, and which provenance/audit contract applies.
  • Implement tier resolver at libs/isis/entitlements/src/generation-tier.ts that takes (tenant, user, persona, entitlement) → resolved tier and surface allowlist; expose resolver to BFF, Admin, and Studio middleware.
  • Implement deny-by-default surface guard: any contemplative-product Studio route that resolves a non-curated surface (raw graph editor, Civitai LoRA hash picker, RunPod region selector, model-merging, LoRA-training, GPU-worker, multi-GPU orchestration, gaussian-splatting, auto-rigging, topaz/RIFE/animatediff, model-comparison) returns 404 + Yemaya signup disclosure for entitled users, hard-block for the rest.
  • Audit and reconcile placeholder routes in apps/oshun/web/src/app/studio/isis/ against the tier matrix; remove or redirect any route that does not belong on the contemplative product.
  • Tests asserting tier resolution: contemplative-product entitlements cannot resolve to graph editor, Civitai search, RunPod dashboard, LoRA trainer, or model merger; AAA-tier entitlements can; operator-tier entitlements can plus admin surfaces; missing entitlement denies even on direct URL.

24.2 Civitai — intake, registry, and operator surfaces#

Provider lib exists at libs/isis/ai-providers/src/providers/civitai/ (12 sub-providers including LoRA training, model merging, content safety). Intake policy and review surfaces are missing.

  • Implement intake policy at libs/isis/ai-providers/src/civitai-intake/.
  • Implement metadata ingestion (rights, license, creator attribution, content labels, preview assets, NSFW normalization, hashes, versions, lineage, recommended config, compatibility notes).
  • Implement review queues for intake / rights / license / compatibility / safety / preview / promotion / rejection / takedown / denylist / staging recipes.
  • Block unmanaged runtime use for unreviewed external assets.
  • Normalize external assets into Isis-owned model records and Oshun- controlled storage.
  • Implement operator review-queue UI at apps/oshun/admin/src/app/isis/civitai-intake/ with queue list, item detail (license inspector, preview gallery, NSFW flag, hash, lineage, compatibility report), license-decision actions (approve, reject, conditional, takedown, denylist), staging-recipe binding, audit trail.
  • Implement operator search-and-import surface that wraps Civitai search behind intake policy: search → preview → request import → review queue; no direct unmanaged download.
  • Implement managed-models browser at libs/isis/managed-models/src/browser/ exposing only post-intake approved models to creator surfaces; raw Civitai access is operator-only.
  • Tests for normalization, review-to-staging, license outcomes, compatibility notes, promotion decisions, bypass prevention, intake-bypass denial, license-decision audit, takedown cascade, creator-view filtering.

24.3 ComfyUI — workflow factory and operator surfaces#

Provider lib exists at libs/isis/ai-providers/src/providers/comfy/ and comfy-cloud/; node registry exists at libs/yemaya/comfyui-integration/src/node-registry/. Graph editor, template diff UI, and rehearsal harness UI are missing.

  • Implement approved workflow classes, parameter guardrails, disallowed graph patterns, template versioning + diffing + portability checks, no ad-hoc runtime dependencies.
  • Implement graph editor at apps/oshun/admin/src/app/isis/workflow-editor/ (operator-only): typed node palette bound to node-registry, parameter inspector, schema validation against approved-class contract, save-as-class flow, version-pin with semantic-version increments.
  • Implement template diff UI: per-node visual diff, parameter delta, portability-check report, breaking-change flagger blocking promotion when consumer pipelines reference removed nodes.
  • Implement workflow-class authoring screen: bind a graph to a class, lock parameter ranges, declare disallowed nodes, set cost class, attach Lilith persona-binding metadata, attach Sophia grounding requirement where applicable.
  • Implement portability check runner: declared-dependency report, missing-node diagnostic, model-version compatibility check, cost-class drift report.
  • Implement fixture-rehearsal harness UI: select fixture set, run candidate against baseline, side-by-side output compare per asset class (image, video, audio, 3D), regression flagger with eval-score deltas; mandatory before promotion.
  • Implement node-registry browser at apps/oshun/admin/src/app/isis/comfy-nodes/ with node card, schema inspector, deprecation flag, alternative-node suggestion, used-by report.
  • Tests for editor save/load, diff fidelity, rehearsal determinism per seed, class-binding enforcement, promotion-gate blocking on rehearsal regression.

24.4 RunPod and execution-provider operator surfaces#

Provider client exists at libs/shared/runpod-client/ (~1,400 lines). Endpoint dashboard, cost/region/health UI, and queue inspector are missing.

  • Implement provider endpoint registration, health checks, region-aware routing, concurrency, cost controls, retry/backoff, dead-letter, secret rotation, failover, queue metrics, execution health, release checks, outage tests, performance tests, audit tests.
  • Implement endpoint dashboard at apps/oshun/admin/src/app/isis/runpod-endpoints/: per-endpoint queue depth, latency P50/P95/P99, error rate, cost/hour, region, GPU class, health badge, last-failover, cold-start indicator.
  • Implement cost & quota panel: tenant cost ledger, projected burn, budget envelope vs. actual, kill-switch trigger UI, budget-breach alert routing.
  • Implement region-failover override UI with audited rationale and rollback timer.
  • Implement secret-rotation surface: rotate provider key, audit trail, downstream re-deploy / pod-recycle trigger, post-rotation health check.
  • Implement queue inspector: live queue, per-job ETA, kill / requeue / reprioritize actions (operator only, audit-bound), per-tenant fairness view.
  • Tests for dashboard data fidelity against synthetic queues, kill-switch audit, region-override audit, secret-rotation atomicity, queue inspector action authorization.

24.5 LoRA training, model merging, and tuning surfaces#

libs/isis/ai-providers/src/providers/civitai/lora-training-provider.ts and model-merging-provider.ts and model-quality-provider.ts exist; no operator UX exposes them. These are operator-tier and AAA-tier; never on the contemplative product.

  • Implement LoRA training queue UI at apps/oshun/admin/src/app/isis/lora-training/ (operator and AAA-tier): dataset upload with rights attestation, training-run config, progress timeline, sample previews per checkpoint, cost estimate, abort, promotion-to-managed-models gate with rehearsal evaluation.
  • Implement model-merging surface at apps/oshun/admin/src/app/isis/model-merging/: component selection, merge ratio, A/B preview against fixture set, save-as-managed-model with provenance bundle (parent hashes, ratios, ratifier).
  • Implement tuning rehearsal: mandatory fixture-set evaluation before promotion to production model registry; eval-score delta blocks promotion below baseline.
  • Implement model-quality scoring view backed by model-quality-provider (per-model eval scorecards, drift indicators, deprecation flag, alternative-model suggestion).
  • Implement training-run lineage tree: dataset → run → checkpoint → merge → managed-model edges with provenance, rights, and consent IDs.
  • Tests for training-run lineage integrity, merge provenance, eval-gating before promotion, dataset-rights attestation enforcement.

24.6 Curated creator generation surfaces (contemplative product)#

Contemplative-product creators (Tara/Veritas/Nyx/Nisaba/Metis authors) get a small set of curated cards that bind to approved workflow classes, approved voice profiles, and approved persona/policy bindings. No raw model picker, no LoRA hash selector, no scheduler choice, no graph editor. Cards live in apps/oshun/web/src/components/studio/generation/ and are surfaced inline in the §16.2 authoring workspace.

  • Implement illustration card bound to approved Sophia source set + Lilith persona + Isis workflow class; inputs limited to subject/style preset/ aspect/locale; provider chosen by tier resolver.
  • Implement narration card (TTS) bound to approved voice profiles + per-locale prosody + Lilith disclosure copy; only voice profiles in the creator-tier allowlist appear in the picker.
  • Implement ambient-audio card for ritual/meditation soundscapes bound to approved music workflow classes (mood, tempo, duration, loopability).
  • Implement explainer card (Veritas) for grounded illustrations of claims/sources, with mandatory Sophia evidence pin.
  • Implement caption + dub card for accessibility/locale parity bound to §16.6 localization queues.
  • Implement accessibility-pass card (alt text generation, contrast analysis, caption verification, transcript generation).
  • Each card surfaces: pre-flight cost/latency estimate, provenance preview, consent confirmation, regenerate-with-direction, side-by-side variant compare, send-to-editorial pipeline, takedown-on-revoke.
  • Per-card kill-switch and per-tenant entitlement gate; degrade gracefully to "feature unavailable" when the underlying workflow class is frozen.
  • Tests: workflow-class binding (no raw graph leaks via DOM, network, or URL), persona/policy enforcement, provenance-bundle attachment to every output, entitlement gating at component, route, and BFF layers, locale fallback.

24.7 Voice providers, voice cloning, and audio integrity#

Provider lib exists at libs/isis/ai-providers/src/providers/tts/ (ElevenLabs). Voice-cloning workflow UX, abuse-detection surface, and runtime watermark verifier are missing.

  • Implement voice-provider abstraction (ElevenLabs / Azure / Google / custom) at libs/iris/voice/providers/.
  • Implement voice profile registry, consent rules, rights rules, cloned-voice safeguards, disallowed behaviors, watermarking, quality scoring, provider fallback, failover, synthetic disclosure.
  • Implement admin review for voice profiles, watermark verification, abuse-risk scores, review outcomes.
  • Implement customer-facing voice provenance for premium voiced experiences.
  • Implement voice-clone authoring workflow at apps/oshun/admin/src/app/isis/voice-cloning/: consent-capture screen with identity verification, sample upload + read-aloud script, naturalness/prosody scoring view, watermark verification, abuse-risk scorecard, multi-party signoff, voice-profile registration, release toggle, revocation cascade.
  • Implement voice-pack browser for creators (curated tier): filter by language, persona, lineage; preview; entitlement gate; provenance display; no access to cloning machinery.
  • Implement runtime watermark verifier embedded in playback that flags missing/tampered watermarks before audio reaches user ears.
  • Implement abuse-detection surface at apps/oshun/admin/src/app/trust-safety/voice-abuse/: impersonation alerts, denylist matches, revocation cascade triggers, takedown coordination with §22 consent revocation.
  • Validation/abuse-detection/watermark/naturalness/voice-coherence evals.
  • Tests for consent enforcement (no clone without recorded consent), cloned-voice abuse evals (impersonation prompts, identity-protection breach), watermark presence in every produced sample, revocation-cascade reach (every artifact derived from a revoked profile flagged within SLA).

24.8 Music and audio generation#

No provider exists today; apps/oshun/web/src/app/studio/isis/music-generation/ and audio-generation/ are placeholder routes. Music generation is needed for ritual/meditation soundscapes (Tara), ambient explainers (Veritas), study beds (Metis/Nisaba), sky-event briefing audio (Nyx).

  • Implement music-generation provider abstraction at libs/isis/ai-providers/src/providers/music-generation/ covering MusicGen / Suno / Udio / Stable-Audio / custom-on-Comfy with workflow classes (ambient, ritual, meditation-bed, study-bed, score, stem-render).
  • Implement creator music card (curated tier) at apps/oshun/web/src/components/studio/generation/MusicCard.tsx: mood, tempo, duration, loopability, key, intensity-curve; Lilith tone policy enforced; Sophia source attribution if reference-track-driven.
  • Implement stems & mix surface (AAA tier, in Yemaya Studio per §24.11): per-stem isolation, gain, fade, loop-point editor, mix-bus routing.
  • Implement watermark + provenance bundle for every produced track (consent ID, prompt, model, license, generator, timestamp).
  • Implement disallowed-content guards: no copyrighted-style imitation without rights, no melody/voice clones without consent, no contemplative-tone violations (over-stimulation, rhythmic patterns flagged for crisis-state harm).
  • Implement length / file-size / format guardrails per workflow class.
  • Tests: workflow-class enforcement, watermark presence per produced track, copyrighted-style detector against fixture set, provenance completeness, stem alignment within tolerance, contemplative-tone regression evals.

24.9 3D generation and post-processing#

Code directories exist (libs/isis/3d-comfyui-nodes, libs/isis/3d-generation, apps/oshun/web/src/app/studio/isis/3d-*, gaussian-splatting, auto-rigging, texture-enhancement, topaz-enhancement, rife-interpolation, topology-verification) but no V1 spec or operator/ creator surfaces. 3D is primarily an AAA-tier surface (Yemaya); the contemplative product exposes only narrow read-mostly surfaces (e.g., Nyx sky-event 3D briefings).

  • Implement 3D generation provider abstraction at libs/isis/ai-providers/src/providers/three-d/ covering text-to-3D, image-to-3D, gaussian-splatting capture-to-mesh, auto-rigging, bound to the existing libs/isis/3d-comfyui-nodes node set.
  • Implement post-processing pipeline classes: topology verification, texture enhancement, RIFE interpolation, Topaz upscaling — chained via approved pipeline classes only; no ad-hoc chaining at runtime.
  • Implement operator pipeline-class authoring (graph + classes + cost class + rehearsal-fixture set); creator surfaces only select an approved pipeline.
  • Implement Nyx sky-event 3D briefing card (curated tier) producing a lightweight scene viewer for celestial events bound to approved 3D pipeline class.
  • Implement provenance: every 3D output carries source 2D refs, pipeline- class hash, model version, watermark embedded in mesh metadata.
  • Tests for pipeline-class binding, topology validity, texture-quality scoring against fixture set, provenance completeness, watermark preservation through enhancement passes.

Currently no unified gallery surface exists for generation outputs. §16.4 covers the asset-library metadata; this section adds the gallery UX that production work depends on.

  • Implement unified output gallery at apps/oshun/web/src/app/studio/generation-gallery/ and corresponding admin gallery at apps/oshun/admin/src/app/isis/output-gallery/, backed by libs/yemaya/asset-library/ and §13.3 provenance bundles.
  • Implement filter facets: domain, persona, workflow class, freshness, license, generator, model, language/locale, tenant, entitlement.
  • Implement per-output lineage tree: prompts, model, workflow class, parent outputs, child outputs, dependent artifacts (used in lesson X, cited by claim Y, embedded in passage Z).
  • Implement branch / variation: derive new run from existing output with delta inputs within workflow-class bounds; lineage edge persisted; cost estimate before launch.
  • Implement replay-with-tweak: surface original inputs, allow targeted parameter override within workflow-class allowed range, run, append to lineage tree, side-by-side compare with parent.
  • Implement compare grid (2-up, 4-up, n-up) with diff overlays: pixel delta for image, frame-delta + audio-delta for video, waveform delta for audio, mesh-delta for 3D.
  • Implement send-to-editorial / send-to-asset-library / takedown flows from gallery; takedown cascades through dependent artifacts per §16.4.
  • Implement provenance-bundle inspector for every output (consent ID, prompt, model, watermark, timestamp, invoking user, tenant, workflow class, cost ledger entry).
  • Implement bulk actions on gallery selections (re-tag, send-to-editorial, revoke-consent, takedown) with operator audit and undo window.
  • Tests for lineage chain integrity, branch/replay determinism within seed, takedown cascade reach, provenance display completeness, filter correctness, bulk-action authorization.

24.11 Yemaya AAA Studio cross-reference and surface boundary#

The contemplative-product Studio (apps/oshun/web/src/app/studio/) ships only the curated cards from §24.6, the curated music card from §24.8, the narrow Nyx 3D card from §24.9, and the gallery from §24.10. The AAA-creator power-user surfaces (raw graph editor, full Civitai browser, LoRA training, model merging, music stem editor, voice clone, full 3D pipeline editor) live in Yemaya AAA Studio at apps/yemaya/studio-web/ and apps/yemaya/studio- desktop/ and are NOT exposed on the contemplative product.

  • Document boundary at docs/oshun/studio-vs-yemaya-studio.md listing every generation surface and its host app, entitlement, and rationale.
  • Audit apps/oshun/web/src/app/studio/isis/ against the §24.1 tier matrix; remove or redirect placeholder routes that should not exist on the contemplative product (representative list: gpu-worker, gpu-worker-architecture, multi-gpu-orchestration, nvidia-rtx- processing, lora-training, model-merging, model-comparison, topaz-enhancement, rife-interpolation, texture-enhancement, topology-verification, gaussian-splatting, auto-rigging, instantid, ip-adapter, controlnet, florence-2, animatediff-lightning, raw comfyui-nodes, raw comfyui-sdk).
  • Replace removed routes with entitlement-aware redirects: visiting an AAA-tier route from contemplative product returns disclosure copy + Yemaya signup gate for entitled users, hard-block for the rest.
  • Wire deep-links from Yemaya Studio back to Oshun output gallery so AAA-creator outputs can be promoted into curated content surfaces via §16 editorial lifecycle.
  • Tests for surface-boundary enforcement (contemplative-product entitlement cannot resolve to AAA-tier route or component, even via direct URL or import), redirect/disclosure correctness, cross-link integrity, gallery promotion handoff.

25. Living Scenes#

Living Scenes is a launch-blocking V1 capability that produces governed, continuous, AI-generated video sessions on the contemplative product, AAA-tier authoring in Yemaya Studio, and a public per-artifact viewer for kept Living Offerings. Five domain templates ship at V1 launch (Tara Contemplative Arcs, Nyx Sky Briefings, Veritas Grounded Explainers, Metis Lesson Visualizers, Arete Living Offerings); none is descoped. See V1/features.md "Living Scenes" for the full surface description; this section is the implementation backlog.

25.1 Score schema, runtime, and blend kernel#

  • Implement Score schema (Segment, Cue Plan, Render Envelope) at libs/yemaya/living-scenes-runtime/src/score/; Zod contracts exported from libs/contracts/src/living-scene/.
  • Implement Conductor runtime at libs/yemaya/living-scenes-runtime/src/conductor/ with parallel segment pre-warm (lookahead ≥ 2), carry-state protocol (CLIP anchor + last-frame conditioning + motion descriptor + LUT + audio tail), backpressure logic, reconnect support per Psyche envelope.
  • Implement Blend Kernel at libs/yemaya/blend-kernel/ with typed transitions (latent-warm-start, optical-flow-morph, color-LUT-match, audio-crossfade, narrative-pivot); deterministic across approved GPU nodes.
  • Implement Render Envelope determinism harness at libs/yemaya/living-scenes-runtime/src/determinism/; same-input pixel-equivalence across N nodes is a release gate.
  • Implement segment generator adapter abstraction over Hunyuan / WAN / etc. with workflow-class binding; raw model picker prohibited on contemplative tier.
  • Tests: score round-trip; blend continuity (FVD, flicker, color-jump, motion-vector); determinism across nodes; backpressure degradation pathways; reconnect mid-segment.

25.2 Live Direction channel (voice / tap / text)#

  • Implement cue verb vocabulary + cue parser at libs/yemaya/living-scenes-runtime/src/cues/: linger, advance, morph(target_descriptor), recall(prior_segment_id), shift-style(style_token), shape-by(signal), save-moment, abandon, kill.
  • Implement voice cue path: ASR partial → ASR final → cue parser → Lilith pre-screen → cue queue; speaker voiceprint identity-binding by default; shared-viewing mode opt-in disables binding with explicit notice.
  • Implement text cue path: input sanitize → cue parser → Lilith pre-screen → cue queue; raw text never reaches the segment generator unwrapped (defends against prompt-injection by construction).
  • Implement tap cue path: single-tap = linger, double-tap = advance, long-press = palette; immediate at next segment boundary.
  • Implement cue reconciliation (tap immediate; voice/text queued; recency with policy precedence; kill > abandon > advance > linger > rest).
  • Implement workflow-class verb restrictions (e.g., Veritas excludes morph(target_descriptor) per visual-claim-grounding policy).
  • Implement sensitive-intention classifier on every voice/text cue using the Lilith crisis taxonomy; crisis-signal cue triggers scene crisis frame.
  • Implement cue locale parity: classifiers reach parity with conversational Lilith classifiers across V1 launch locales.
  • Implement rejected-cue UX in the contemplative-product viewer: scene continues; soft notice ("let's stay with what's unfolding").
  • Tests: verb mapping correctness; ASR-error confidence threshold + explicit confirmation; prompt-injection resistance; locale parity; identity binding; reconciliation precedence; latency budgets (tap ≤ 1 frame, voice P95 ≤ 800 ms, text P95 ≤ 300 ms); crisis-signal detection.

25.3 Lilith continuous-video tone class#

  • Implement rhythmic-pattern + strobe detector at libs/lilith/continuous-video-policy/src/strobe/ with PSE-safe thresholds (ITU-R BT.1702-2 / WCAG flash); hard kill before frames reach the user.
  • Implement luminance / contrast / motion-density caps per persona class; enforced by the Conductor at frame emission.
  • Implement color-cycle and flicker-band guards; segments crossing the band replaced with a still in live, rejected from kept artifacts.
  • Implement narrative-cadence policy (per-domain pacing bands); briefing pace cannot apply to meditation templates and vice versa.
  • Implement live-cue policy gate (every voice/text cue Lilith-checked before queueing); voice and text rejection produce the soft-rejected-cue UX.
  • Implement sensitive-topic pre-roll for kept artifacts (grief, illness, etc.); content notice + autoplay-disabled on revisit.
  • Implement scene crisis frame: fade-to-still + plain operator voice + Iris memory-write suspension + safety-incident record creation; cannot be overridden by user, persona, or admin copilot.
  • Tests: PSE/strobe detection regression; persona-class motion budgets; cue policy precision/recall; crisis-frame coverage on every signal in the Lilith taxonomy; live override rejection.

25.4 Provenance, watermarking, and C2PA#

  • Implement visible-mark renderer (contemplative-aesthetic minimal corner mark with short-code) at libs/yemaya/living-scenes-runtime/src/provenance/visible/.
  • Implement inaudible audio watermark (spread-spectrum) at libs/yemaya/living-scenes-runtime/src/provenance/audio-watermark/; survives MP3 / AAC / Opus reencode.
  • Implement C2PA Content Credentials sidecar at libs/yemaya/living-scenes-runtime/src/provenance/c2pa/; signed at materialization.
  • Implement out-of-band attestation page resolver at apps/oshun/web/src/app/scene/[id]/ (per-artifact viewer doubles as attestation surface).
  • Implement channel robustness eval harness (Telegram, WhatsApp, Twitter/X, Instagram, Discord, email, generic web) at libs/yemaya/living-scenes-runtime/src/provenance/channel-robustness/; ≥ 1 signal recovery per channel is a release gate.
  • Tests: per-channel watermark survival rate; sidecar integrity through transcode; attestation-page round-trip from short-code; signed-credential verification.

25.5 Domain templates#

  • Tara Contemplative Arcs: ship five sub-variants (loving-kindness, body-scan, breath-anchor, nature-immersion, gratitude) at libs/isis/workflow-classes/living-scene/tara/; pace to breath-cycle clock; reduced-motion variant in lockstep; Lilith strictest tone band.
  • Nyx Sky Briefings: implement ephemeris adapter (Skyfield-class) at libs/nyx/sky-clock/; Northern + Southern hemisphere parity at V1 launch; constellation art rights cleared; observer-location opt-in; tonight-only briefing materializes once per location-bucket; cover planetary alignments, moon phases, meteor showers, ISS passes, aurora forecasts, comets, conjunctions. Workflow class at libs/isis/workflow-classes/living-scene/nyx/.
  • Veritas Grounded Explainers: workflow class at libs/isis/workflow-classes/living-scene/veritas/; Sophia source pin bound; visuals as mood/style anchors only (no empirical claims); the morph(target_descriptor) verb excluded; counterclaim/retraction cascade reaches kept artifacts; adversarial would-be-misleading fixtures in eval set.
  • Metis Lesson Visualizers: workflow class at libs/isis/workflow-classes/living-scene/metis/; bound to lesson knowledge-graph anchor set; "what if X?" branches constrained to the KG manifold with graceful fallback; Themis academic-integrity gate against active assessments; standards-aligned (Common Core, IB, NGSS, etc.) for institutional delivery.
  • Arete Living Offerings: workflow class at libs/isis/workflow-classes/living-scene/arete/; user states intention (voice/text) → score; private + public-redacted intent layers; strongest crisis pre-screen on intent; default duration 4–8 minutes within Arete pace bands; deterministic re-render; user-initiated branch-from-this-moment forks score with same intent and new seed.
  • Per-template fixture eval set (≥ 30 fixtures): golden-path, adversarial cue, crisis-trigger, locale-parity, accessibility-parity, grounding-correctness (Veritas / Metis); release gate blocks workflow-class promotion until thresholds met.
  • Per-template locale parity at V1 launch locales: narrator scripts, voice profile, captions, audio description, transcripts, RTL handling.
  • Per-template accessibility pass: alt-text for first-frame previews, caption accuracy, AD coverage, transcript completeness.

25.6 Customer-tier Living Scene card (contemplative product)#

  • Implement Living Scene card at apps/oshun/web/src/components/studio/generation/LivingSceneCard.tsx bound to approved templates only (no raw model picker, no LoRA, no scheduler choice); template picker resolves from tier + tenant entitlement.
  • Implement cue input affordances on the card: voice (mic), tap (gesture strip), text (compact field); all three available on every template.
  • Implement pre-flight cost/latency estimate, provenance preview, consent confirmation, locale fallback, send-to-gallery, branch-from-this-moment.
  • Implement viewer chrome with rejected-cue soft-notice UX, reduced-motion toggle, captions/AD toggle, OS-accessibility-setting respect.
  • Implement entitlement gate at component, route, and BFF layers; raw template graph never leaks via DOM, network, or URL.
  • Implement per-card kill-switch (per workflow class) and per-tenant entitlement gate; degrade gracefully when workflow class is frozen.
  • Tests: workflow-class binding; no raw-graph leaks (DOM / network / URL); entitlement gating at all three layers; rejected-cue UX; accessibility parity; cue input parity (voice + tap + text on every template); kill-switch behavior; locale fallback.

25.7 AAA Scene Score Editor (Yemaya Studio)#

  • Implement Scene Score Editor at apps/yemaya/studio-{web,desktop}/src/score-editor/: timeline view with Segment cards, transition pickers, narration-script overlay, motion-descriptor strip, narrator-cadence overlay, audio-bus tracks.
  • Implement Segment inspector with workflow-class-locked parameter ranges, persona/voice picker (allowlist), Lilith tone-band selector, Sophia source pin selector, accessibility-role selector.
  • Implement Transition inspector with overlap-window slider, fixture preview, eval scorecard (FVD / flicker / color-jump / motion-vector), manual override blocked below release-gate threshold.
  • Implement Latent-carry inspector visualizing carry-state handoff per boundary; surface contract violations.
  • Implement fixture-rehearsal harness running the score against the workflow-class fixture set; promotion blocked until thresholds met.
  • Implement replay scrubber with per-event annotations (cue applied, transition fired, policy intervention, fallback engaged).
  • Implement Score versioning with promotion path through Isis environments (dev → staging → prod); promotion gated through workflow-class release gates and Lilith policy review.
  • Implement Score templates library seeding new scores from approved templates with locked policy bindings.
  • Implement entitlement gating: editor is invisible to contemplative-tier entitlements at component, route, and BFF layers.
  • Tests: surface-boundary enforcement (contemplative tier cannot resolve to editor); version round-trip; fixture-rehearsal correctness; release-gate enforcement; replay-scrubber event integrity.

25.8 Psyche scene-event additions#

  • Extend Psyche event model at libs/oshun/embodiment-psyche/src/events/ with scene events: segment-start, segment-end, transition-start, transition-end, live-direction-applied, scene-policy-intervention, scene-crisis-frame, scene-fallback-engaged.
  • Implement frame-stream channel over the Psyche envelope with backpressure on degraded providers.
  • Implement per-event timing and trace correlation (per §11.5 diagnostics).
  • Tests: event-schema round-trip; frame-stream backpressure; reconnect with cue-plan replay; trace-ID propagation through the scene pipeline.

25.9 Determinism, render envelope, re-render-from-score#

  • Implement Render Envelope persistence (engine version, blend-kernel version, model hashes, Lilith policy version, Isis workflow-class version, locale, persona, voice profile, Sophia source pin set, base seed, per-segment seeds) at libs/yemaya/living-scenes-runtime/src/envelope/.
  • Implement re-render-from-score on demand against a stored Envelope; pixel-equivalent output across N approved nodes within tolerance.
  • Implement engine-upgrade migration: when any envelope component is deprecated, kept artifacts gain a "v2 available" notice with one-tap re-bake; original remains playable from cache.
  • Implement determinism eval harness with N-node parity assertion as a release gate; failing reproducibility blocks workflow-class promotion to contemplative tier.
  • Implement materialization-on-share (MP4 / HLS / AV1 with channel watermark bake-in); cache 30 days post-share, evict, re-render on demand.
  • Tests: Envelope round-trip; N-node pixel-equivalence within tolerance; engine-upgrade migration UX; materialize-on-share + evict + re-render cycle.

25.10 Keep, share, and personal artifacts#

  • Implement Keep action in the contemplative-product viewer chrome and in the gallery; persists Score + Envelope + Cue Plan as a kept Living Offering bound to the user account; lifetime persistence; no quota-based eviction.
  • Implement Share action with explicit consent gate distinct from Keep; three privacy levels (private link, link-with-password, public); noindex default; opt-in indexability per artifact via robots-meta toggle.
  • Implement public viewer at apps/oshun/web/src/app/scene/[id]/ (also serves as out-of-band attestation page); contemplative aesthetic; no autoplay-with-sound; accessibility-first; Open Graph + Twitter Card previews from first-frame and public-redacted intent.
  • Implement embed (<iframe> + oEmbed) honoring share privacy level and tenant policy.
  • Implement revocation: invalidate public URL within SLA; remove Open Graph + embed availability; tombstone with "this offering has been retired" notice.
  • Implement per-share download grant producing MP4 with C2PA + visible mark + audio watermark intact.
  • Implement per-page abuse report at apps/oshun/web/src/app/scene/[id]/report/ routing to Lilith review queues.
  • Implement rate-limit and abuse pipeline on the public surface; mass-share-pattern detection (one user → many channels short window).
  • Implement pre-share Lilith re-check on the materialized artifact; blocks share with explanatory copy on re-check failure.
  • Implement tenant-branded public viewer with tenant logo, color, attribution copy for tenant-internal shares.
  • Tests: keep + share + revoke + delete cycle; three privacy levels; noindex default + opt-in indexing; embed honoring policy; mass-share detection; pre-share re-check coverage; attestation-page resolution from short-code; tenant-brand surfacing.

25.11 Cue privacy and intent redaction#

  • Implement two-layer intent field on Score (private, public-redacted).
  • Implement Lilith-governed redaction classifier scrubbing named persons, deceased, medical conditions, abuse disclosures, locations of safety, and other sensitive categories defined in the Lilith taxonomy.
  • Implement default-deny on share-with-private; explicit per-share opt-in records the choice in the artifact audit log.
  • Implement operator inspection gating: cue history + private intent visible only at Iris-memory authority class (consented or elevated-authorization); standard reviewers see public-redacted layer only.
  • Implement cue-history retention per Iris retention profile of the originating user; deletion cascades to artifact Cue Plan field.
  • Tests: redaction precision/recall against fixture intent corpus across V1 launch locales; default-deny enforcement; operator-inspection authority enforcement; retention/deletion cascade.

25.12 Shareability matrix#

  • Implement per-component shareability matrix at libs/yemaya/living-scenes-runtime/src/shareability/: voice, likeness, persona, source, music, intent, tenant_policy, lilith_policy, crisis_state.
  • Implement per-component grants from the relevant consent records (cloned voice share-out grant; teacher persona share rights; Sophia source redistribution license; music rights metadata; user-likeness consent).
  • Implement matrix resolution at save and at share; artifact reach restricted to the most restrictive component.
  • Implement reduced-shareability fallbacks (still-frame preview with audio muted, transcript-only, audio-with-still); user picks; system never silently degrades.
  • Implement crisis-state precedence: crisis-touched artifacts are private_only regardless of other components, with soft notice.
  • Tests: matrix resolution against fixture component sets; fallback surfacing UX; crisis-state private-only enforcement; per-component revocation cascade.

25.13 Takedown cascade across kept and shared artifacts#

  • Implement voice-profile-retired disposition: artifact voice track muted + banner + re-render-with-substitute or text-only narration option; shared-link banner.
  • Implement Sophia-source-retracted disposition: artifact retraction banner; corrected-source re-render option; shared-link reflection.
  • Implement workflow-class-frozen disposition: cache-playable; re-render and share disabled; existing shared-link "no longer be reshared" notice.
  • Implement Lilith-policy-drift disposition: policy-version notice; one-tap re-render-under-current-policy.
  • Implement re-detection-sweep disposition: PSE / strobe / luminance failure force-quarantines artifact; shared link invalidated until re-render under updated detector completes.
  • Implement persona-contract-terminated disposition: equivalent to voice-retired with substitute persona option.
  • Implement originating-user-account-deletion cascade: hard-delete kept + shared artifacts; public viewer pages tombstone within SLA.
  • Implement nightly cascade-reach audits asserting SLA compliance across the artifact corpus.
  • Tests: every disposition end-to-end with banner copy, re-render path, shared-link behavior; nightly audit produces ≥ 99.9% SLA-met rate against fixture corpus; cascade reach against derivative artifacts.

25.14 Tenant entitlements and share policy#

  • Implement per-tenant share toggle (deny outright) in Tenant Console Living Scenes governance surface at apps/oshun/admin/src/app/tenant-console/living-scenes/.
  • Implement per-tenant share-scope toggle (deny public, allow tenant-internal only).
  • Implement per-tenant retention policy (kept-artifact retention defaults; 30-day, 1-year, indefinite); user preference within tenant policy.
  • Implement tenant-branded public viewer plumbing for tenant-internal shares (logo, color, attribution copy).
  • Implement tenant audit log for every share action (artifact ID, sharer, audience, channel, policy disposition); tenant operator revoke any tenant-member share.
  • Implement fail-closed enforcement: ambiguous policy resolves to deny.
  • Implement Metis Lesson Visualizer student-default share scope of tenant_internal_only with operator override.
  • Tests: per-tenant share enforcement at the share endpoint; ambiguous-policy fail-closed; audit completeness; tenant-brand surfacing parity; Metis student-default scope.

25.15 Reshare, lineage, remix attribution#

  • Extend Output Gallery lineage tree (per §24.10) with user-owned-artifact branch and attribution-policy edges at libs/yemaya/asset-library/src/lineage/living-scene/.
  • Implement reshare action preserving attribution to originating user by default; tenant-internal scope cannot escalate to public.
  • Implement replay-with-tweak from public artifacts producing children with attribution-policy edges; default strips originating-creator identifying metadata unless they opted into derivative attribution.
  • Implement branch-from-this-moment forking new score from kept artifact at chosen segment boundary; new seeds and Cue Plan owned by the branching user; original unchanged.
  • Implement customer-side lineage view (own derivations + parent-creator attribution where consent given); admin-side lineage view (full lineage including non-attributed parents).
  • Implement remix takedown: parent retraction propagates retraction notice to children but does not delete child artifacts authored by other users.
  • Tests: lineage integrity; attribution-policy enforcement; branch determinism; remix takedown cascade with non-deletion of unrelated children; admin-vs-customer view parity.

25.16 Reduced-motion and accessibility renders#

  • Implement reduced-motion render path producing still-image carousel with same narration + ambient audio at same per-segment cadence; emitted in lockstep with full-motion render.
  • Implement reduced-motion as independent shareable artifact; honors shareability matrix.
  • Implement sidecar caption track per locale; optional burn-in toggle for channels that strip sidecars.
  • Implement audio-description track per template, per locale.
  • Implement transcript artifact (narration + AD) linked from public viewer; downloadable.
  • Implement viewer chrome respecting OS-level accessibility (high-contrast, large-text, reduced-motion preference); keyboard cue access; assistive-tech navigability.
  • Accessibility release gate: every workflow-class promotion requires reduced-motion + AD + captions + transcript parity.
  • Tests: parity across full-motion and reduced-motion at the artifact level; AD coverage; caption accuracy; screen-reader navigation; OS-setting respect; keyboard cue parity with voice/tap/text; accessibility release gate enforcement.

25.17 Backend strategy and Phase 176 bridge#

  • Implement chained-clip backend as the V1 contemplative-tier backend (parallel pre-warm, blend kernel, materialize-or-stream).
  • Implement feature-flagged Phase-176 backend bridge (Nous world-model serving) for AAA-tier sessions only; tier resolver guarantees contemplative tier never resolves to Phase-176 backend.
  • Implement workflow-class-declared backend support; tier resolver picks the highest-quality backend the session is entitled to and the system can serve under SLO.
  • Tests: backend swap on AAA-tier without breaking customer surface; contemplative-tier hard-block from Phase-176 backend; SLO-driven backend selection.

25.18 Eval sets, release gates, rollback#

  • Implement per-template fixture sets (≥ 30 fixtures per template at V1) covering golden-path, adversarial cue, crisis-trigger, locale-parity, accessibility-parity, grounding-correctness fixtures.
  • Implement continuity evals (boundary FVD, temporal-flicker, color-jump, motion-vector continuity, narration-time alignment).
  • Implement determinism evals (N-node pixel-equivalence within tolerance).
  • Implement watermark robustness evals (per-channel survival ≥ 1 signal).
  • Implement cue-policy evals (cue-rejection precision/recall across V1 launch locales).
  • Implement crisis-detection evals (scene-stream parity with conversational detector across the Lilith taxonomy).
  • Implement accessibility evals (reduced-motion parity, AD coverage, caption accuracy, screen-reader navigability).
  • Implement release gates: every workflow class must pass continuity, determinism, watermark, cue policy, crisis, and accessibility evals before promotion to contemplative tier; failures block promotion and surface in the Isis release-gate dashboard.
  • Implement rollback: any production workflow class can be rolled back to a prior version; in-flight sessions complete on current version; new sessions resolve to rolled-back version; kept artifacts pinned to rolled-back version remain playable.
  • Tests: every release gate against fixture corpus; rollback round-trip; pinned-artifact playability after rollback; release-gate dashboard surfacing; cross-locale parity.

25.19 Cinematographic technique catalog#

  • Define CinematographicTechnique Zod contract at libs/contracts/src/living-scene/technique.ts with fields {id, displayName, kernelComposition[], overlapWindowRange, requires[], forbids[], toneBands[], templateAllowlist[], evalThresholds, accessibilityNote, reducedMotionFallback, provenanceTag} and a contract test that round-trips a full fixture for every V1 catalog entry.
  • Implement the V1 catalog (12 entries) at libs/yemaya/blend-kernel/src/catalog/: hard-cut, match-cut, L-cut, J-cut, dissolve, smash-cut, whip-pan, jump-cut, match-action, cross-cut, montage, fade-to-black. Each entry binds to the Blend Kernel primitives listed in features.md § "Cinematographic Technique Catalog".
  • Implement catalog versioning + Isis release-gate review hook so catalog additions/deprecations promote through the same governance path as workflow classes.
  • Implement re-render-from-score compatibility for kept artifacts that used deprecated techniques (artifact pinned to its catalog version; deprecation does not break playback).
  • Tests: catalog round-trip; entry-level conformance to Blend Kernel bindings; deprecation playability; release-gate hook fires on additions.

25.20 Segment-pair compatibility scorer#

  • Implement SegmentPairCompatibilityScorer at libs/yemaya/blend-kernel/src/compatibility/ returning per-dimension scores (style-anchor, motion-descriptor, audio-role, narration, tone-band, grounding, persona) in [0, 1] plus a composite decision.
  • Implement hard-incompatible pair detection (policy-blocked regardless of mechanical scores): crisis ↔ non-crisis without recovery transition; pedagogical ↔ entertainment intra-Score; Tara contemplative ↔ forbidden technique; Veritas Segments with mutually-retracted Sophia source pins.
  • Implement soft-incompatible warning surfacing with rationale strings; override permitted at AAA tier (audited) and forbidden at customer tier.
  • Persist SegmentPairCompatibilityScore records on CompositionDraft and in the promoted Score's Render Envelope so audit and replay can reconstruct the decision.
  • Tests: scorer determinism across approved GPU nodes (same pair → same scores); hard-incompatible-pair coverage against the catalogued list; override audit; per-template threshold enforcement.

25.21 AI Compose Assist#

  • Implement Compose Assist agent at libs/yemaya/living-scenes-runtime/src/compose-assist/ invoked via Isis as an AgentRun with budget caps, tool grants, cost-ledger, and operator audit per § 18 Agentic AI Studio.
  • Compose Assist output schema: candidate Segment, ranked techniques (with confidence bands), rationale string, continuity-eval pre-score.
  • Implement timeline-inline suggestion UI in customer-tier composition surface (web + mobile) — one-tap accept inserts Segment + applies top technique; long-press opens alternatives; manual override logged.
  • Implement gold-set fixtures per V1 launch locale and per template: high-compatibility golden paths, low-compatibility "should refuse" pairs, adversarial intent traces attempting to bypass tone gating.
  • Implement champion-challenger rollout for Compose Assist quality (precision, recall, refusal-rate); promotion blocked by gold-set regression.
  • Implement soft-refusal UX when no viable suggestion exists ("there isn't a clean bridge from here yet — try a different anchor"); silent failure forbidden.
  • Tests: agent envelope conformance; gold-set evaluation harness; adversarial-pair refusal coverage; locale parity; budget-cap enforcement; operator replay round-trip.

25.22 Customer-tier composition surface#

  • Implement web composition surface at apps/oshun/web/src/app/studio/compose/ with drag-arrange Segment timeline, boundary Technique Picker, scrub-preview, and one-tap Compose-Assist accept.
  • Implement mobile composition surface at apps/oshun/mobile/.../compose/ with the same affordances translated to touch (long-press boundary opens picker; drag-reorder Segments).
  • Implement Segment-library sources: kept Living Scenes the user owns (cross-template only when destination policy permits), per-template anchor sets (Tara breath, Nyx celestial, Veritas topic-hub, Metis lesson-step, Arete intention-derived), and tenant rights-tagged imports.
  • Implement tier caps: free tier ≤ 6 Segments / ≤ 90 s, paid tier ≤ 24 Segments / ≤ 8 min; AAA tier routes to Yemaya Studio Scene Score Editor. Crisis frame disables free composition (active sessions complete; no new composition).
  • Implement CompositionDraft → Score promotion with all-boundary continuity-gate enforcement and workflow-class policy validation.
  • Implement Live Direction co-existence: composition-time technique selection is respected at runtime unless a cue overrides it (linger extends Segment past planned transition_out; kill always wins).
  • Implement reduced-motion variant generated automatically: same Segment ordering, same narration, dissolve / fade-to-black substituted for motion-heavy techniques.
  • Tests: tier caps enforcement; crisis-frame composition lock; Score promotion gating against failing continuity; reduced-motion auto-substitution coverage; mobile parity for every web flow.

25.23 Per-template technique allowlists and tone gating#

  • Encode per-template allowlists in the catalog entries (Tara, Nyx, Veritas, Metis, Arete) matching features.md § "Per-Template Availability and Tone Gating".
  • Enforce allowlists in three places: customer Technique Picker (don't surface), Compose Assist candidate generation (don't suggest), Score promotion (block).
  • Implement crisis-frame collapse: technique allowlist reduces to hard-cut, dissolve, fade-to-black within 1 frame of crisis-frame activation regardless of template.
  • Implement Themis interlock for Metis: every technique blocked on in-progress assessment Segments.
  • Tests: every disallowed technique rejected by all three enforcement points per template; crisis-frame collapse latency; Themis assessment lockout coverage.

25.24 Continuity-eval extensions for named techniques#

  • Extend Continuity Eval suite at libs/yemaya/blend-kernel/src/continuity-evals/ with per-technique thresholds: match-cut shape-similarity floor, L/J-cut audio lead/lag tolerance and bus-crossover smoothness, whip-pan motion magnitude floor, jump-cut framing-similarity floor + intentionality marker, match-action motion-continuity envelope match, montage tempo regularity + shared style-anchor cluster tightness, fade-to-black terminal luminance + audio floor.
  • Implement gate enforcement at composition-draft promotion and at runtime (before Blend Kernel executes); failures surface to customer tier as warnings, block AAA-tier promotion, and feed Compose Assist learning loop.
  • Implement auto-substitution rules (e.g., motion-too-gentle whip-pan → match-action; unintentional jump-cut → failed hard-cut).
  • Tests: per-technique threshold fixtures (≥ 10 per technique); auto-substitution coverage; gate-failure logging carries the failing metric for Compose Assist learning.

26. Messaging Channels and Conversational Surfaces#

V1 docs previously had no spec for messaging channels (Telegram, WhatsApp, Discord, Slack, SMS, email-as-channel). Existing scaffolding in yaa/packages/social/telegram-channel-setup and yaa/packages/social/whatsapp-business-service is on a separate codebase and not wired to Oshun BFF / domain services. This section specifies a channel-abstraction layer with Telegram as the first-class conversational surface (bot + Mini Apps + channels + inline + login + payments) and thin adapters for WhatsApp, Discord, Slack, SMS, and email-as-transactional. The audience-tier discipline from §24.1 applies: no operator/AAA-tier surfaces ship over messaging; curated-creator and customer-tier delivery only.

26.1 Channel abstraction and tier-aware routing#

  • Implement channel registry at libs/oshun/messaging-channels/src/registry.ts enumerating channels (telegram-bot, telegram-channel, telegram-miniapp, whatsapp-business, discord-bot, slack-app, sms-twilio, push-fcm, push-apns, email-ses) with per-channel: capability matrix (text, rich-cards, inline-buttons, voice, files, payments, miniapp), cost class, residency profile, consent profile, retention profile, disclosure-rendering capability, crisis-handling capability.
  • Implement channel-aware delivery dispatcher at libs/oshun/messaging-channels/src/dispatcher.ts that takes (recipient, message intent, content variants, persona, policy, provenance) and routes via the user's preferred channel respecting entitlement, residency, opt-in, quiet hours, and per-channel capability fall-through (e.g., rich card → plain text + link if channel cannot render rich).
  • Implement tier-aware routing: no AAA-tier or operator-tier intent ever resolves to a messaging channel; surface-guard from §24.1 applies.
  • Implement per-user channel preferences in Iris memory (§10) with default-off opt-in for each channel; channel binding requires verified ownership (Telegram Login Widget signature, WhatsApp opt-in, etc.).
  • Implement per-tenant channel allowlist with residency-driven defaults (e.g., EU tenant: WhatsApp + email default; Telegram opt-in with data-residency disclosure).
  • Implement quiet-hours respect, frequency caps, and crisis-state suppression (§12.3) per channel.
  • Tests for tier enforcement (admin/AAA intents never dispatched), capability fall-through correctness, per-tenant allowlist, quiet-hours / frequency-cap respect, crisis-state suppression, opt-in revocation.

26.2 Telegram bot — delivery and light assistant#

  • Implement Telegram bot service at apps/oshun/telegram-bot/ (Node / TypeScript, grammY framework) with webhook receiver bound to apps/oshun/bff/src/telegram/webhook.ts, structured update handlers (message, callback_query, inline_query, edited_message, my_chat_member), and per-update audit envelope.
  • Implement bot-token rotation, per-environment bot instances (dev / staging / prod), and webhook-secret verification on every inbound update.
  • Implement domain-aware command handlers: /start, /menu, /today (Tara today + Veritas + Nyx + Arete check-in), /save (save current message to notebook), /sources (open Sophia evidence pack), /voice (toggle voice replies), /quiet (set quiet hours), /stop (unsubscribe), /help.
  • Implement Sophia-grounded Q&A handler: incoming text → Sophia retrieval + grounding → answer with inline-keyboard citation buttons → each citation opens Mini App or web deep-link to source. Lilith persona enforced; no answer ships without grounding state.
  • Implement crisis-aware behavior per §12.3: any §12.3 trigger phrase or classifier hit breaks bot persona to plain operator voice, surfaces verified hotlines as inline buttons, escapes to web app for clinical surfaces, sets crisis-state suppression flag for the conversation.
  • Implement voice-note ingestion: Telegram voice → STT (libs/iris/voice/ providers) → assistant turn; bot reply offers TTS-back as voice or text.
  • Implement disclosure-copy enforcement: every synthetic / AI-generated response includes Lilith disclosure copy in message body that survives forwarding/quoting (no reliance on UI badges).
  • Implement provenance footer on every grounded answer (model, confidence band, source count, timestamp) with deep-link to provenance bundle.
  • Implement rate limiting per user, per chat, per workflow class with friendly degradation copy.
  • Tests for command parity, grounding-state enforcement (no answer ships ungrounded), crisis-trigger suppression and hotline surfacing, voice-note STT pipeline, disclosure-copy survival through forwarding, provenance-footer presence on every answer, rate-limit behavior.

26.3 Telegram Mini Apps — curated Studio surfaces in chat#

  • Implement Mini App host at apps/oshun/telegram-miniapp/ (Next.js static export or Vite SPA with tight-bundled React shell + Telegram WebApp SDK) deployed under HTTPS-pinned domain tma.oshun.app/{surface}.
  • Implement initData verification at apps/oshun/bff/src/telegram/ verify-initdata.ts per Telegram WebApp protocol (HMAC-SHA256 of sorted query params with bot-token-derived key); reject expired or tampered initData.
  • Implement Telegram-bridged auth: initData user → Iris identity mapping, scoped JWT issued for Mini App session, per-tenant entitlement resolution.
  • Implement curated Mini App surfaces (one per intent, all bound to §24.1 curated-creator tier or customer tier — no operator/AAA-tier):
    • Today / Tara ritual player (timer, breath cues, narration playback, complete button) bound to libs/tara/... content.
    • Sophia Q&A with evidence sidebar — full evidence pack inspector, citation drill-down, save-to-notebook (mirrors §9.7 customer surface).
    • Veritas claim card — claim, sources, counterclaims, confidence badge, save / share / regret-flag.
    • Nyx sky viewer — celestial event visualization, observation window, calendar-add (lightweight scene from §24.9 curated 3D card).
    • Arete daily check-in — habit tick, mood snapshot, streak with humane recovery state.
    • Nisaba passage reader — passage view, edition switch, lexicon lookup, annotation save.
    • Curated illustration card from §24.6 — generation request + lineage view + send-to-notebook.
  • Implement Mini App theme sync (light/dark/colors from Telegram.WebApp.themeParams) with fallback for in-browser preview.
  • Implement Telegram-native UI bridge: MainButton, BackButton, haptic feedback, BiometricManager (where supported), scan-qr, request-write- access, share-to-story.
  • Implement provenance and Lilith disclosure rendering inside Mini App identical to web equivalent (no degraded surface).
  • Implement service-worker fallback for Mini App offline read (where Telegram allows; many platforms suppress SW — guard accordingly).
  • Implement BFF endpoint hardening for Mini App callers: every Mini App → BFF request carries initData header, server re-verifies, tenant + entitlement resolved server-side; never trust client-claimed identity.
  • Tests for initData verification (valid, expired, tampered, replay, cross-bot), entitlement resolution, surface-boundary (Mini App cannot reach AAA-tier or operator routes), theme sync, MainButton/BackButton lifecycle, offline fallback, BFF auth header presence.

26.4 Telegram channels — editorial publishing target#

  • Implement channel-publish target in §16.3 editorial pipeline: Veritas daily briefings, Nyx event alerts, Tara seasonal programs, Arete weekly reflection threads, Nisaba passage-of-the-day publish to operator- managed Telegram public channels.
  • Implement channel registry at apps/oshun/admin/src/app/messaging/telegram-channels/ (operator-only): add/remove channels, bind channel to editorial pipeline, owner role, crisis-state suppression switch, takedown action with audited rationale.
  • Implement message format synthesis per channel: title + summary + hero image + inline-keyboard CTA (open in app, save, view evidence) with per-locale variants and Lilith tone enforcement.
  • Implement scheduling integration with §16.3 calendar: scheduled publish, embargo respect, takedown cascade pulls channel posts via edit-message API where allowed, otherwise posts a correction notice.
  • Implement engagement attribution via Telegram channel statistics + deep-link UTM parameters back into BFF analytics (§30).
  • Implement disclosure-copy enforcement per channel post (synthetic / grounding state visible in body, not relegated to UI affordance).
  • Tests for scheduled publish fidelity, embargo respect, takedown cascade, locale variant correctness, attribution capture, disclosure survival.

26.5 Telegram inline mode — save, share, attribution#

  • Implement inline-query handler at apps/oshun/telegram-bot/src/inline/ supporting @oshunbot save <text or link> (save to notebook), @oshunbot share <artifact-id> (insert official artifact card with provenance), @oshunbot find <query> (Sophia search → inline result list with citations).
  • Implement attribution-preserving share cards: every shared artifact card includes provenance footer, source count, license badge, synthetic-content disclosure if applicable; cards survive forwarding with attribution intact.
  • Implement save-to-notebook from inline mode with provenance bundle capture; cross-link with §17 customer curation.
  • Implement bot-author rate limits and abuse-detection on inline queries.
  • Tests for inline-result formatting, attribution survival through forwarding, save-to-notebook handoff, provenance integrity, abuse- detection thresholds.

26.6 Telegram authentication — Login Widget and Mini App initData#

  • Implement Login Widget integration at apps/oshun/web/src/auth/ telegram/ for low-friction signup/binding: button on auth surfaces, callback verification at BFF, identity binding to existing Oshun user or new account creation.
  • Implement Login Widget signature verification on BFF (HMAC-SHA256 against bot-token-derived secret); reject expired or tampered payloads.
  • Implement scope contract: Telegram-bound identity grants only non-sensitive scopes (read content, save to notebook, ritual play, sky view, Q&A) — never grants admin, never grants privacy/consent management, never grants payment management without elevation step.
  • Implement step-up auth requirement: any sensitive action initiated from Telegram-bound identity (consent change, billing, voice clone, AAA- tier promotion) redirects to web with primary-credential challenge.
  • Implement Telegram-binding management surface in account settings: view, revoke, re-bind; revocation cascades to active Mini App sessions and bot subscriptions.
  • Tests for signature verification (valid/expired/tampered/replay), scope-cap enforcement, step-up redirect on sensitive actions, revocation cascade.

26.7 Telegram payments — entitlement upgrade flows (V1.x optional)#

  • Implement Telegram payments adapter at apps/oshun/bff/src/telegram/payments.ts using Telegram's sendInvoice + pre_checkout_query + successful_payment flow, bound to §23 entitlement and billing services.
  • Implement per-tenant payment provider configuration (Stripe via Telegram, regional providers); fall back to web checkout for tenants where Telegram-native payment is unavailable.
  • Implement provenance-bundled receipts and audit-trailed entitlement upgrades; revoke flow on chargeback / refund.
  • Implement crisis-state suppression: no upselling or payment surfacing during a crisis-flagged conversation.
  • Tests for invoice→pre-checkout→success state machine, refund cascade, regional fall-back, audit completeness, crisis-state suppression.

26.8 WhatsApp Business adapter — transactional template messaging#

  • Implement WhatsApp Business Cloud API adapter at libs/oshun/messaging-channels/src/whatsapp/ covering verified template messages only (transactional: receipts, reminders, password reset, login codes, billing alerts, scheduled-event nudges).
  • Implement template registry with Meta-approved templates per locale + use-case; release gates require approved template before promotion.
  • Implement 24-hour customer-initiated session window handling: no free-form replies after window closes; degrade to template message or email fallback.
  • Implement per-tenant Meta Business account binding, opt-in capture, and message-status webhook ingestion.
  • Implement cost ledger entry for every WhatsApp message (per-locale pricing) bound to §23 cost controls.
  • Tests for template-only enforcement, session-window respect, opt-in/opt-out fidelity, status-webhook ingestion, cost ledger accuracy.

26.9 Email, push, and SMS adapters#

  • Implement email adapter at libs/oshun/messaging-channels/src/email/ bound to existing transactional email infra (SES / SendGrid / equivalent) with per-tenant DKIM/SPF/DMARC, bounce + complaint handling, list-unsubscribe headers, locale-aware templates.
  • Implement push adapter at libs/oshun/messaging-channels/src/push/ covering FCM (Android/web) and APNs (iOS) with per-platform payload synthesis, silent-push background sync, badge management, action buttons.
  • Implement SMS adapter at libs/oshun/messaging-channels/src/sms/ using Twilio (or equivalent) for verified-identity flows only (login codes, password reset, billing alerts, crisis hotline escalation); enforce A2P 10DLC registration in US.
  • Implement consistent disclosure-copy + provenance footer rendering across email/push/SMS within each channel's capability constraints.
  • Implement per-channel deliverability monitoring (bounce rate, open rate, click-through, push-grant rate, SMS-failure rate) feeding §30 analytics.
  • Tests for delivery success, bounce / unsubscribe handling, silent-push determinism, SMS-only-for-verified-identity enforcement, disclosure rendering per channel.

26.10 Discord and Slack adapters — community and institutional surfaces#

  • Implement Discord adapter at libs/oshun/messaging-channels/src/discord/ for AAA-creator community surfaces (Yemaya Studio creator community, Project Obsidian production coordination); not exposed on contemplative product.
  • Implement Slack adapter at libs/oshun/messaging-channels/src/slack/ for institutional Metis delivery: course progress notifications, assignment reminders, instructor digests; per-workspace OAuth installation and scope contract.
  • Implement command surfaces (/oshun today, /oshun save, /oshun ask) with the same Sophia-grounding + Lilith persona discipline as Telegram bot.
  • Implement workspace-level entitlement gate (Slack workspace bound to Metis institution; Discord server bound to Yemaya AAA-creator community); deny-by-default for unbound workspaces/servers.
  • Tests for OAuth install / uninstall flow, scope enforcement, command grounding-state enforcement, workspace-entitlement binding.
  • Document channel boundary at docs/oshun/messaging-boundary.md: per channel, what content classes ship, what residency profile applies, what retention policy applies, what consent must be captured, what provenance is preserved, what disclosure mechanisms exist, what audit events are emitted.
  • Implement Iris memory ingestion guard: chat content from third-party channels (Telegram, WhatsApp, Discord, Slack) is tagged with channel provenance and subject to stricter retention + per-channel redaction rules; user must explicitly opt in to "remember from chat" before any durable Iris write.
  • Implement per-channel retention policy (Telegram: ephemeral by default with 30-day operator-side audit; WhatsApp: per Meta requirements; Discord/Slack: per workspace policy) and DSAR cascade (§22) reaching every channel-stored message and bound provenance bundle.
  • Implement consent-revocation cascade: revoking channel binding pulls bot subscriptions, terminates Mini App sessions, removes scheduled sends, redacts cached chat-state per retention policy, and posts revocation-notice in chat where supported.
  • Implement crisis-state cross-channel suppression: a crisis-flag on any channel suppresses non-essential sends across all channels for the affected user until cleared (operator audit + user-visible notice).
  • Implement channel-aware audit envelope: every send/receive carries channel ID, recipient ID, intent class, persona, policy hash, provenance bundle ID, residency tag, retention class, disclosure verification result.
  • Implement per-tenant channel residency report (which channels authorized, which content classes flow over each, which jurisdictions affected) for compliance review.
  • Tests for residency-tag enforcement, retention-policy fidelity, DSAR cascade reach across channels, consent-revocation cascade, crisis-state cross-channel suppression, audit-envelope completeness.

27. Architecture and Platform Foundations#

(Most foundations live in Section 1; this section captures items not covered there.)

  • Domain service consolidation: identify standalone apps and services that share scope, document a deprecation map, route incoming calls via a single consolidation point, run end-to-end shell-to-service integration tests.
  • Implement service discovery + circuit breakers + health checks + readiness probes.
  • Implement public API platform: OAuth 2.1/PKCE for first-party clients and third-party integrations, scoped tokens, refresh, revocation, rate limits, per-key quotas, audit, tenant-aware scoping across BFF and domain services.
  • Implement typed shared-service contracts (OpenAPI/proto/schema artifacts as applicable) with backward-compatibility, schema-drift, rollback, and compatibility tests for BFF-to-domain and domain-to-substrate calls.

28. Security, Access Control, Operational Hardening#

  • Define canonical role model spanning customer, support, reviewer, moderator, privacy operator, model operator, persona operator, admin leadership.
  • Enforce least-privilege scopes for every admin workspace.
  • Implement step-up authentication for sensitive actions.
  • Implement policy-controlled tenant + environment separation.
  • Implement audit coverage for privileged actions with immutable events.
  • Standardize secrets handling for provider integrations / generation pipelines / voice / avatar / analytics / BFF / services with rotation, scoping, consistent loading.
  • Implement validated configuration for feature flags, policy bundles, experiment guardrails, env configs.
  • Implement safe rollback plans for shell, admin, grounding, assistant, persona, generation releases.
  • Implement permission and authorization regression coverage for admin routes/actions; function-level authorization for support, review, moderation, privacy, model, persona, Metis institutional APIs; tenant-isolation and cross-account leakage suites.
  • Implement object-property authorization, excessive-data-exposure, and mass-assignment protections through canonical Zod request/ response shapes.
  • Run authenticated DAST against staging customer web, admin web, and launch-critical APIs; gate release on results.
  • Run SAST + CodeQL on shipped code; gate release.
  • Run dependency vulnerability + secret scanning in CI.
  • Generate SBOM + provenance verification on containers, web bundles, packages.
  • Implement release signing where supported.
  • Build fuzz + malicious-input suites for uploads, imports, markdown, rich-text rendering, search, prompt+tool surfaces, webhook endpoints.
  • Enforce SSRF, unsafe-upstream-consumption, egress-policy controls for URL ingestion, fetch tools, webhooks, BYOM, retrieval connectors.
  • Implement resource-consumption + abuse controls (rate limits, payload size, pagination caps, query-cost ceilings) on search, export, upload, generation, webhook, analytics APIs.
  • Run API inventory + shadow-endpoint discovery checks before each release.
  • blocked:external Run pre-GA penetration testing + red-team exercises (auth, RBAC, privacy, Metis, grounded generation, admin escalation paths) with documented scope and signoff. — re-marked [~] 2026-06-12: external-vendor pen test / red-team exercise; evidence cannot live in-repo (the "How to use this file" section's own [~] example).

29. Design System and Experience Quality#

  • Codify Tara-centered product language at libs/oshun/design-language/.
  • Publish unified IA, cross-domain journey models, customer/admin shell distinction, morning/midday/evening flows, research-to-practice flows, story-to-source flows, sky-to-text flows, assistant-led flows.
  • Publish customer visual thesis + admin visual thesis, redesign inventory, surface scorecards, minimal-chrome rules, layout-density tiers, scan-first hierarchy, ergonomic budgets, immersive-vs- instrumental guidance.
  • Define color, typography, spacing, elevation, motion, domain accents tokens (extend libs/oshun/design-tokens/).
  • Define evidence UI, disclosures, synthetic indicators, trust/ confidence/provenance badges, severity states, queue states, persona switching, avatar/voice identity, review states, approval states, degraded states, fallback visuals.
  • Define responsive grid/gutter/max-width/measure/reading rhythm, imagery, illustration, texture, ambient media, card-avoidance rules, motion hierarchy, loading/skeleton/empty/offline/error states, sticky/docked actions, hover/press/selection/drag affordances.
  • Build reusable components for domain switchers, continuity cards, evidence cards, evidence sidebars, claim items, source items, passage items, notebooks, collections, assistant disclosure, memory state, provenance badges, admin queues, filters, incident severity, SLA timers, review decisions, policy diffs, avatars, voice packs, rights, licenses.
  • Implement accessibility, reduced motion, content tone, AI disclosure copy, error copy, outage copy, fallback copy, one-handed mobile ergonomics, dense-data admin ergonomics, form-entry ergonomics, copy compression, contrast, focus indicators.
  • Build design-review and Playwright-backed visual QA checklists for shell, domain, admin, mobile, desktop, laptop, tablet, narrow-mobile.

30. Analytics, Observability, Experimentation, Evaluation#

  • Implement customer event taxonomy at libs/oshun/analytics/src/customer-taxonomy.ts (verify) covering activation, retention, domain navigation, home, search, library, activity, onboarding, profile, privacy, memory, billing.
  • Implement admin event taxonomy covering queues, review, moderation, appeal, support, privacy, incidents, model ops, persona ops, rights, provenance, policy.
  • Implement assistant event taxonomy covering interactions, memory state, grounding state, persona state, disclosure, avatar mode, voice mode, source inspection.
  • Implement review/moderation/appeal/model-intake/promotion/media-gen/ audit/compliance event schemas.
  • Build dashboards for activation, retention, cross-domain use, Nisaba adoption, assistant quality, disclosure visibility, service health, queue health, support SLAs, satisfaction, trust, grounding quality, citation degradation, memory anomalies, provider outage, failover, incidents, launch readiness.
  • Implement structured tracing across shell / BFF / Sophia / Iris / Psyche / Lilith / Isis / Metis / review / support / admin (use OpenTelemetry; trace IDs propagate end-to-end).
  • Implement experiment support for recommendation ranking, assistant presentation, disclosure presentation, home/dashboard composition.
  • Build unified evaluation pipeline for grounded answers, assistant quality, safety, search, recommendation, persona, voice, avatar, Metis pedagogy, generated artifacts.
  • Manage benchmark datasets (ownership, promotion thresholds, regression blocking) with admin readiness summaries.

31. Testing, QA, Accessibility, Performance#

  • Establish mandatory automation matrix by change type and critical journey at docs/testing/automation-matrix.md.
  • Vitest unit coverage for every contract, adapter, and policy.
  • Playwright coverage for customer web journeys: auth, onboarding, home, domain switching, search, library, activity, Tara, Veritas, Nyx, Nisaba, Metis, assistant, profile, privacy, memory, billing, offline/PWA.
  • Playwright coverage for admin web: auth, RBAC, review decisions, moderation, appeals, support, privacy, persona approval, model promotion, incidents, exports, policy, research integrity, dense-data workspaces.
  • Mobile E2E coverage: auth, onboarding, home, quick actions, Tara, Arete, Veritas, Nyx, Nisaba, Metis, assistant text, assistant voice, notifications, memory, privacy, offline, retry, admin urgent queues.
  • Accessibility coverage: shared shell, assistant, admin queues, dense data, keyboard-only, focus order, reduced motion, zoom, screen readers, assistive technology.
  • Browser/device/locale/RTL/long-string/viewport/low-bandwidth/latency/ network-interruption/permission-state/lifecycle/mobile-web-PWA matrices.
  • Contract/event-schema/retry/deduplication/idempotency/replay/ dead-letter/migration/analytics/audit/seed/synthetic-data tests.
  • Failure/recovery/chaos/background-job/concurrent-session/conflict/ disaster-recovery/restore/load/spike/soak/memory-leak/performance/ queue-throughput tests.
  • Golden/holdout/adversarial/fuzz/property-based/malicious-input/ mutation-strength/differential/metamorphic/replay/clock-skew/canary/ synthetic-monitor/red-team/API-authorization/resource-consumption/ SSRF/DAST/SAST/dependency/secret-scanning/SBOM/build-integrity/ provenance checks.
  • Implement CI reporting + flaky-test quarantine policy + deflake SLA + merge/release blocking for missing critical automation + trace/HAR/screenshot retention.
  • Lighthouse budgets enforced in CI for every customer route.
  • Visual regression testing (Percy/Chromatic equivalent) wired into CI.

32. Content, Localization, Documentation#

32.1 Launch-quality content#

  • Define minimum-viable + launch-quality content bundles per domain (Tara/Veritas/Nyx/Arete/Nisaba/Metis) at docs/content/v1-bundles.md.
  • Define premium bundle definitions where required.
  • Define content review checklists per domain.
  • Define accessibility plans per domain content bundle, including transcript, alt text, captions, reduced-motion alternatives, and large-text review requirements.
  • Build seed data for demos/evidence fixtures/concept-graph fixtures/ persona fixtures/review-incident fixtures/model-workflow-provenance fixtures.

32.2 Locale architecture#

  • Externalize every customer-facing string under libs/oshun/i18n/ with locale-aware date/time/timezone, calendar, number, currency, region formatting.
  • Define translation workflows, glossary ownership, language fallback, RTL and text-expansion QA.
  • Define launch locale coverage list for customer + admin journeys at docs/launch/locale-coverage.md.

32.3 Documentation#

  • Architecture docs.
  • Consumer IA docs.
  • Admin IA docs.
  • Data model docs.
  • Testing strategy docs.
  • Evaluation pipeline docs.
  • Release-gate docs.
  • Launch readiness checklists.

32.4 Runbooks#

  • Shell-outage runbook.
  • Grounding-failure runbook.
  • Assistant-failure runbook.
  • Provider-failover runbook.
  • Moderation-surge runbook.
  • Privacy-incident runbook.
  • Model/workflow rollback runbook.
  • Persona rollback runbook.
  • Provenance-failure runbook.
  • Watermark-verification-failure runbook.

32.5 Training#

  • Support operators training program.
  • Moderators training.
  • Reviewers training.
  • Persona operators training.
  • Model operators training.
  • Privacy operators training.
  • Compliance operators training.
  • Product training.
  • Launch support training.

33. Launch Readiness#

V1 is not feature-complete until every item below is checked.

33.1 Pre-launch drills#

  • blocked:release Internal dogfood drill (≥ 30 days, all customer + admin journeys). — re-marked [~] 2026-06-12: requires a ≥30-day real-world drill by a human cohort; evidence cannot live in-repo.
  • blocked:human Safety review pass (Lilith + Trust&Safety + Privacy review board). — re-marked [~] 2026-06-12: real-world review-board sign-off; not locally actionable.
  • blocked:human Quality review pass (per-domain content + AI eval scores meet published thresholds). — re-marked [~] 2026-06-12: human editorial/quality review event; eval scores are repo-verifiable but the review pass itself is a real-world gate.
  • blocked:release Private beta with measurable target metrics. — re-marked [~] 2026-06-12: requires a real-world beta cohort and live metrics; evidence cannot live in-repo.
  • blocked:release Beta-blocking-issue remediation + signoff. — re-marked [~] 2026-06-12: depends on private-beta findings and a real-world signoff; not locally actionable until the beta runs.

33.2 Go/no-go#

  • Launch go/no-go checklist completed at docs/launch/go-no-go.md.
  • blocked:governance General Availability approval captured. — re-marked [~] 2026-06-12: real-world organizational approval event; evidence cannot live in-repo.
  • blocked:governance Rollout plan approved (canary % schedule, rollback triggers). — re-marked [~] 2026-06-12: the plan can live in-repo but "approved" is a real-world go/no-go decision.
  • blocked:governance Rollback plan approved (per substrate). — re-marked [~] 2026-06-12: the plan can live in-repo but "approved" is a real-world go/no-go decision.
  • blocked:release Post-deploy monitoring dashboards live. — re-marked [~] 2026-06-12: "live" requires a production deployment; dashboard definitions can live in-repo but liveness cannot.
  • blocked:release Canary analysis automation enabled. — re-marked [~] 2026-06-12: requires live production rollout infrastructure; "enabled" cannot be evidenced in-repo.

33.3 Critical-journey verification#

  • Tara: ritual start → pause → resume → completion → reflection capture.
  • Arete: daily check-in → habit complete → weekly review.
  • Veritas: briefing → claim inspect → source drill → counterclaim view.
  • Nyx: tonight view → save event → calendar sync → reminder fires.
  • Nisaba: passage open → annotate → notebook capture → resume on mobile.
  • Metis: BYOM ingest → grounded course generation → tutor session → assessment → mastery update.
  • Studio: author draft → bind sources → request review → apply changes → publish gate → rollback with public change note.
  • Agentic AI Studio: invoke agent → inspect run plan/DAG → pause/redirect → approve gate → publish output → replay run with audit bundle.
  • Assistant: persona switch → grounded answer → memory update → privacy pause toggle.
  • Support/billing: upgrade → metered usage alert → payment failure grace → support case → refund/credit decision → audit trail.
  • Privacy: DSAR end-to-end (export + delete + restore-blocked-where- applicable + audit).
  • Tenant: SSO login → SCIM sync → OneRoster import → custom role assignment → audit explore → data export.
  • Public distribution: public page → app-store deep link → auth handoff → app link open → minimum-version/forced-update path → status banner.
  • Admin: queue triage → review approve → publish gate → audit trail → kill-switch fire → fallback recovery.

33.4 Exit criteria signoff#

  • Customer web and mobile feel like one coherent product across all six domains.
  • Tara is visibly the product center.
  • Nisaba and Metis are fully integrated, not just routed.
  • Sophia grounding is visible everywhere evidence matters.
  • Cross-domain continuity is useful, credible, and tested.
  • Admin web + admin mobile operate every launch-critical workflow.
  • Oshun Studio supports authoring/editorial/asset/taxonomy/versioning/ localization/collaboration/customer-curation across every content domain with grounded source binding, persona/tone policy, and release-gate enforcement.
  • Agentic AI Studio operational with governance gates enforced and tenant-scoped budgets honored.
  • Tenant Console operational with SSO/SCIM/OneRoster/role-customization/ audit/bulk-ops/API-keys/webhooks/lifecycle-comms/help-authoring/ status-banner — strictly isolated from operator Oshun Admin.
  • Iris/Psyche/Lilith/Sophia/Isis/Metis ownership boundaries true in implementation, not just in docs.
  • External model sources cannot bypass review/rights/safety/provenance/ Isis release gates.
  • Metis high-stakes outputs emit claim-level evidence and pass grounding/pedagogy/safety/rights/academic-integrity/standards/drift gates.
  • Public website + app store listings + deep links + public status page ready for launch.
  • Recommendation candidate generation, signal ingestion, offline evaluation, observability operational.
  • Aja embodied-instruction services required by Metis are ready or explicitly deferred with approved scope boundaries.
  • All critical workflows have risk-tiered automated verification.
  • Accessibility, performance, security, resilience, observability, documentation, training, runbooks, canaries, rollback triggers, post-deploy monitors all satisfy launch gates.

34. Studio Substrate Bridges (Bellona, Hathor, Neith)#

Added 2026-06-12. V1/features.md § Subsystem Glossary declares Bellona, Hathor, and Neith as Studio-only V1 substrates (confirmed in-v1 2026-05-29), but this backlog previously carried no tasks for them. The walked surface inventory lives at WALKTHROUGH/studio/domain-bridges/{bellona,hathor,neith}/ (82, 74, and 1 surface docs respectively); Studio routes exist under apps/oshun/web/src/app/studio/{bellona,hathor,neith}/, and implementations under libs/bellona/* and libs/hathor/*. Nothing below has been verified; each task requires the per-task verification protocol (read the code, verify domain correctness, run the adversarial scan) before marking.

  • Not a box since 2026-09-18: each surface has its own box in the coverage family walkthrough-studio (WALKTHROUGH/studio/domain-bridges/bellona/), so this roll-up counted the same work twice; its progress log below is kept. Verify every Bellona Studio surface inventoried under WALKTHROUGH/studio/domain-bridges/bellona/ (82 docs: bridge-core and protocol/sessions, Unity/Unreal/Godot/Blender/DaVinci/Houdini bridges, OpenUSD interchange and layer composition, build/export pipeline, mocap/retargeting, MetaHuman, XR / virtual production) against the routes under apps/oshun/web/src/app/studio/bellona/ and the libs/bellona/* implementations, one surface at a time.
    • 2026-07-01 progress: /studio/bellona/bridge-protocol-and-sessions and its /studio/bellona/bridge-core alias now have focused real-dev-infra Playwright coverage for live catalog load, AuthProvider admin bearer propagation, clean FSM replay, invalid-transition issue rendering, direct BFF auth/payload gates, malformed JSON with no POST, pending submit disablement, catalog 503/malformed states, malformed replay success, transport failure, non-admin unauthorized, anonymous redirect, route-map / quick-action affordances, mobile 44px controls, and alias navigation. The whole Bellona task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-01 progress: /studio/bellona/openusd-stage-management now has focused real-dev-infra Playwright coverage for live catalog load, AuthProvider Bellona-admin bearer propagation, clean USD stage validation, invalid_path / duplicate_path / orphan_prim / default_prim_not_root issue rendering, direct BFF auth/payload gates, malformed JSON with no POST, pending submit disablement, catalog 503/malformed states, malformed validation success, transport failure, non-admin unauthorized, anonymous redirect, route-map / quick-action affordances, and mobile 44px controls. The whole Bellona task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-01 progress: /studio/bellona/content-addressable-build-cache and its /studio/bellona/database alias now have focused real-dev-infra Playwright coverage for live CAS catalog load, AuthProvider Bellona-admin bearer propagation, default dedup replay, hash-collision and malformed-key issue rendering, direct BFF auth/payload gates, malformed JSON with no POST, pending submit disablement, catalog 503/malformed states, malformed replay success, transport failure, non-admin unauthorized, anonymous redirect, route-map / quick-action affordances, mobile 44px controls, and alias IA / breadcrumb verification. The whole Bellona task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-01 progress: /studio/bellona/openusd-variant-management now has focused real-dev-infra Playwright coverage for live variant catalog load, AuthProvider Bellona-admin bearer propagation, default explicit/fallback/ unselected resolution, invalid_selection / invalid_fallback / empty_set / duplicate_variant / unselected issue rendering, direct BFF auth/payload gates, malformed JSON with no POST, pending submit disablement, catalog 503/malformed states, malformed resolve success, transport failure, non-admin unauthorized, anonymous redirect, route-map / quick-action affordances, and mobile 44px controls. The whole Bellona task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-01 progress: /studio/bellona/openusd-layer-composition now has focused real-dev-infra Playwright coverage for live LIVRPS catalog load, AuthProvider Bellona-admin bearer propagation, default composition resolve, same-arc sublayer/list tie-break ordering, invalid-arc validation surfacing, direct BFF auth/payload gates, malformed JSON with no POST, pending submit disablement, catalog 503/malformed states, malformed resolve success, transport failure, non-admin unauthorized, anonymous redirect, route-map / quick-action affordances, and mobile 44px controls. The whole Bellona task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-01 progress: /studio/bellona/openusd-materialx now has focused real-dev-infra Playwright coverage for live MaterialX catalog load, AuthProvider Bellona-admin bearer propagation, default clean graph validation, float promotion, type_mismatch / unknown_from_node / cyclic_graph diagnostics, direct BFF auth/payload/schema gates, malformed JSON with no POST, pending submit disablement, catalog 503/malformed states, malformed validation success, transport failure, non-admin unauthorized, anonymous redirect, route-map / quick-action affordances, and mobile 44px controls. The whole Bellona task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-01 progress: /studio/bellona/format-registry now has focused real-dev-infra Playwright coverage for live registry catalog load, AuthProvider Bellona-admin bearer propagation, default clean registry validation, invalid_version / invalid_mime / no_extensions / unknown_capability / extension_collision / dangling_superseded / self_superseded / missing_superseded diagnostics, direct BFF auth/payload/schema gates, malformed JSON with no POST, pending submit disablement, catalog 503/malformed states, malformed validation success, transport failure, non-admin unauthorized, anonymous redirect, route-map / quick-action affordances, and mobile 44px controls. The whole Bellona task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-01 progress: /studio/bellona/asset-interchange-formats now has focused real-dev-infra Playwright coverage for live conversion-chain catalog load, AuthProvider Bellona-admin bearer propagation, default lossy FBX -> USD -> glTF planning, lossless and lossy-intermediate behavior, unknown-format diagnostics, direct BFF auth/payload/schema gates, malformed JSON and non-object JSON with no POST, pending submit disablement, catalog 503/malformed states, malformed plan success, transport failure, non-admin unauthorized, anonymous redirect, route-map / quick-action affordances, and conversion textarea / submit / quick-action mobile 44px controls. The whole Bellona task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-01 progress: /studio/bellona/interchange-batch-conversion now has focused real-dev-infra Playwright coverage for live batch-scheduler catalog load, AuthProvider Bellona-admin bearer propagation, default LPT schedule, balanced and surplus-worker schedules, invalid scheduler diagnostics, direct BFF auth/payload/schema gates, malformed JSON and non-object JSON with no POST, pending submit disablement, catalog 503/malformed states, malformed schedule success, transport failure, non-admin unauthorized, anonymous redirect, route-map / quick-action affordances, and batch JSON textarea / submit / quick-action mobile 44px controls. The whole Bellona task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-01 progress: /studio/bellona/build-job-authoring now has focused real-dev-infra Playwright coverage for live incremental-build planner catalog load, AuthProvider Bellona-admin bearer propagation, default rebuild plan, full cache-hit, new-step miss, dependency-cycle diagnostics, direct BFF auth/payload/schema gates, malformed JSON with no POST, pending submit disablement, catalog 503/malformed states, malformed plan success, transport failure, non-admin unauthorized, anonymous redirect, route-map / quick-action affordances, planner mobile 44px controls, and the fixture-backed shell workflows for docs, policy, command palette, stream, filtering, saved views, bulk actions, detail, wizard, collaboration, import/export, API parity, readiness, audit, telemetry, and responsive preview. The whole Bellona task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-01 progress: /studio/bellona/build-templates now has focused real-dev-infra Playwright coverage for live build-matrix expander catalog load, AuthProvider Bellona-admin bearer propagation, default Cartesian matrix expansion, partial-exclusion behavior, ineffective-exclusion and unknown-axis diagnostics, direct BFF auth/payload/schema gates, malformed JSON with no POST, pending submit disablement, catalog 503/malformed states, malformed expansion success, transport failure, non-admin unauthorized, anonymous redirect, route-map / quick-action affordances, and matrix textarea / submit / quick-action mobile 44px controls. The whole Bellona task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-01 progress: /studio/bellona/build-queue-tracking now has focused real-dev-infra Playwright coverage for live build-queue scheduler catalog load, AuthProvider Bellona-admin bearer propagation, default priority/FIFO schedule, same-priority job-id tie-breaks, single-worker serialization, duplicate-job diagnostics, direct BFF auth/payload/schema gates, malformed JSON with no POST, pending submit disablement, catalog 503/malformed states, malformed schedule success, transport failure, non-admin unauthorized, anonymous redirect, route-map / quick-action affordances, scheduler mobile 44px controls, and the fixture-backed shell workflows for docs, policy, command palette, stream, filtering, saved views, bulk actions, detail, wizard, collaboration, import/export, API parity, readiness, audit, telemetry, observability, and responsive preview. The whole Bellona task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-01 progress: /studio/bellona/build-artifact-management now has focused real-dev-infra Playwright coverage for live artifact-retention planner catalog load, AuthProvider Bellona-admin bearer propagation, default LRU eviction, alternate multi-eviction behavior, duplicate / invalid-payload diagnostics, direct BFF auth/payload/schema gates, malformed JSON and non-object JSON with no POST, pending submit disablement, catalog 503/malformed states, malformed plan success, transport failure, non-admin unauthorized, anonymous redirect, route-map / quick-action affordances, retention textarea / submit / quick-action mobile 44px controls, and the fixture-backed shell's React-covered local workflows. The whole Bellona task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-01 progress: /studio/bellona/build-to-export-orchestration now has focused real-dev-infra Playwright coverage for live ordered-handoff evaluator catalog load, AuthProvider Bellona-admin bearer propagation, default failed-sign/pending blockers, complete/skipped export-ready paths, duplicate/invalid phase diagnostics, direct BFF auth/payload/schema gates, malformed JSON with no POST, pending submit disablement, catalog 503/malformed states, malformed evaluation success, transport failure, non-admin unauthorized, anonymous redirect, route-map / quick-action affordances, and handoff textarea / submit / quick-action mobile 44px controls. The whole Bellona task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-01 progress: /studio/bellona/package-builder now has focused real-dev-infra Playwright coverage for live asset-export package-builder catalog load, AuthProvider Bellona-admin bearer propagation, default GLB/USD ready manifest generation, optional-count blocked and needs-attention readiness via the real BFF, direct BFF auth/payload/schema gates, empty asset / empty target client guards, pending submit disablement, catalog 503/malformed states, malformed build success, transport failure, non-admin unauthorized, anonymous redirect, route-map / quick-action affordances, and asset/source/target/submit/quick-action mobile 44px controls. The whole Bellona task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-01 progress: /studio/bellona/export-pipeline now has focused real-dev-infra Playwright coverage for live CPM analyzer catalog load, AuthProvider Bellona-admin bearer propagation, default critical-path analysis, alternate timing/slack behavior, zero-duration terminal stage timing, unknown-dependency and dependency-cycle diagnostics, direct BFF auth/payload/schema gates, malformed JSON and non-object JSON with no POST, pending submit disablement, catalog 503/malformed states, malformed analysis success, transport failure, non-admin unauthorized, anonymous redirect, route-map / quick-action affordances, and pipeline textarea / submit / quick-action mobile 44px controls. The whole Bellona task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-01 progress: /studio/bellona/motion-capture-streaming now has focused real-dev-infra Playwright coverage for live stream-planner catalog load, AuthProvider Bellona-admin bearer propagation, default capacity plan, over-budget and tight-headroom diagnostics, optional overhead direct-BFF calculation, direct BFF auth/payload/schema gates, invalid field/no POST guards, pending submit disablement, catalog 503/malformed states, malformed plan success, transport failure, non-admin unauthorized, anonymous redirect, route-map / quick-action affordances, and numeric input / submit / quick-action mobile 44px controls. The whole Bellona task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-01 progress: /studio/bellona/motion-capture-skeleton-management now has focused real-dev-infra Playwright coverage for live skeleton-integrity catalog load, AuthProvider Bellona-admin bearer propagation, default clean hierarchy validation, multiple-root / orphan-parent / cycle / joint-budget diagnostics, direct BFF auth/payload/schema gates, malformed JSON and non-object JSON with no POST, pending submit disablement, catalog 503/malformed states, malformed validation success, transport failure, non-admin unauthorized, anonymous redirect, route-map / quick-action affordances, and skeleton JSON textarea / submit / quick-action mobile 44px controls. The whole Bellona task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-01 progress: /studio/bellona/motion-retargeting now has focused real-dev-infra Playwright coverage for live retarget-validator catalog load, AuthProvider Bellona-admin bearer propagation, default clean bone-map validation, missing-required / duplicate-target / hierarchy-warning diagnostics, direct BFF auth/payload/schema gates, malformed JSON and non-object JSON with no POST, pending submit disablement, catalog 503/malformed states, malformed validation success, transport failure, non-admin unauthorized, anonymous redirect, route-map / quick-action affordances, and retarget JSON textarea / submit / quick-action mobile 44px controls. The whole Bellona task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-01 progress: /studio/bellona/virtual-production now has focused real-dev-infra Playwright coverage for the unified parent hub, including anonymous redirect, Studio breadcrumbs, capability summary, single-h1 heading hierarchy, route map, quick-action mobile 44px controls, all four embedded live VP catalogs with AuthProvider Bellona-admin bearer propagation, default camera-tracking / genlock-timecode / LED-wall / ICVFX submit flows against the real BFF, exact delegated POST bodies, embedded catalog-failure isolation, and non-admin fail-closed behavior across all embedded lanes. The whole Bellona task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-01 progress: /studio/bellona/virtual-production-camera-tracking now has focused real-dev-infra Playwright coverage for live latency/jitter analyzer catalog load, AuthProvider Bellona-admin bearer propagation, default high-jitter verdict, over-budget latency and under-sampled tracking from the real BFF, custom delay-frame budget behavior, direct BFF auth/payload/schema gates, malformed JSON and non-object JSON with no POST, pending submit disablement, catalog 503/malformed states, malformed analysis success, transport failure, non-admin unauthorized, anonymous redirect, route-map / quick-action affordances, and camera-tracking payload / submit / quick-action mobile 44px controls. The whole Bellona task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-01 progress: /studio/bellona/virtual-production-genlock-timecode now has focused real-dev-infra Playwright coverage for live genlock/SMPTE timecode catalog load, AuthProvider Bellona-admin bearer propagation, default timecode-drift verdict, locked volume, fps mismatch, invalid timecode, drifting phase, unlocked phase, drop-frame arithmetic, direct BFF auth/payload/schema/domain gates, malformed JSON and non-object JSON with no POST, pending submit disablement, catalog 503/malformed states, malformed analysis success, transport failure, non-admin unauthorized, anonymous redirect, route-map / quick-action affordances, and genlock JSON textarea / submit / quick-action mobile 44px controls. The whole Bellona task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-01 progress: /studio/bellona/virtual-production-icvfx now has focused real-dev-infra Playwright coverage for live ICVFX inner-frustum catalog load, AuthProvider Bellona-admin bearer propagation, default under-resolved frustum verdict, adequate-density, overflow, alternate-padding, invalid-FOV behavior, direct BFF auth/payload/schema/domain gates, malformed JSON and non-object JSON with no POST, pending submit disablement, catalog 503/malformed states, malformed analysis success, transport failure, non-admin unauthorized, anonymous redirect, route-map / quick-action affordances, and ICVFX shot JSON textarea / submit / quick-action mobile 44px controls. The whole Bellona task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-01 progress: /studio/bellona/virtual-production-led-wall now has focused real-dev-infra Playwright coverage for live LED-wall calculator catalog load, AuthProvider Bellona-admin bearer propagation, default within-capacity sizing verdict, over-capacity and non-standard-aspect diagnostics, omitted default colour-depth / processor-capacity behavior, invalid-pitch handling, direct BFF auth/payload/schema/domain gates, malformed JSON and non-object JSON with no POST, pending submit disablement, catalog 503/malformed states, malformed sizing success, transport failure, non-admin unauthorized, anonymous redirect, route-map / quick-action affordances, and LED-wall JSON textarea / submit / quick-action mobile 44px controls. The whole Bellona task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-01 progress: /studio/bellona/gameplay-runtime-ai-behavior now has focused real-dev-infra Playwright coverage for live behavior-tree validator catalog load, AuthProvider Bellona-admin bearer propagation, default valid-tree verdict, empty-composite failure, unreachable warning, cycle direct-BFF diagnostic, direct BFF auth/payload/schema gates, malformed JSON and non-object JSON with no POST, pending submit disablement, catalog 503/malformed states, malformed validation success, transport failure, non-admin unauthorized, anonymous redirect, route-map / quick-action affordances, and behavior-tree JSON textarea / submit / quick-action mobile 44px controls. The whole Bellona task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-01 progress: /studio/bellona/gameplay-runtime-combat now has focused real-dev-infra Playwright coverage for live damage-mitigation resolver catalog load, AuthProvider Bellona-admin bearer propagation, default armor/resistance/crit expected-damage verdict, immunity and vulnerability warnings from the real BFF, one-hit direct-BFF verdict, direct BFF auth/payload/schema gates, malformed JSON and non-object JSON with no POST, pending submit disablement, catalog 503/malformed states, malformed resolution success, transport failure, non-admin unauthorized, anonymous redirect, route-map / quick-action affordances, and combat JSON textarea / submit / quick-action mobile 44px controls. The whole Bellona task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-01 progress: /studio/bellona/gameplay-runtime-inventory now has focused real-dev-infra Playwright coverage for live slot/weight inventory packer catalog load, AuthProvider Bellona-admin bearer propagation, default stack packing verdict, slot overflow and weight overflow diagnostics from the real BFF, direct BFF auth/payload/schema gates, malformed JSON and non-object JSON with no POST, pending submit disablement, catalog 503/malformed states, malformed packing success, transport failure, non-admin unauthorized, anonymous redirect, route-map / quick-action affordances, and inventory JSON textarea / submit / quick-action mobile 44px controls. The whole Bellona task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-01 progress: /studio/bellona/gameplay-runtime-input now has focused real-dev-infra Playwright coverage for live input-binding analyser catalog load, AuthProvider Bellona-admin bearer propagation, default device/key/context conflict verdict, redundant duplicate-binding warning, context/device isolation, direct BFF auth/payload/schema gates, malformed JSON and non-object JSON with no POST, pending submit disablement, catalog 503/malformed states, malformed analysis success, transport failure, non-admin unauthorized, anonymous redirect, route-map / quick-action affordances, and input-binding JSON textarea / submit / quick-action mobile 44px controls. The whole Bellona task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-01 progress: /studio/bellona/gameplay-runtime-save-load now has focused real-dev-infra Playwright coverage for live save-migration planner catalog load, AuthProvider Bellona-admin bearer propagation, default migratable path verdict, up-to-date, downgrade, missing-migration and overshoot diagnostics from the real BFF, direct BFF auth/payload/schema gates, malformed JSON and non-object JSON with no POST, pending submit disablement, catalog 503/malformed states, malformed planning success, transport failure, non-admin unauthorized, anonymous redirect, route-map / quick-action affordances, and save migration JSON textarea / submit / quick-action mobile 44px controls. The whole Bellona task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-01 progress: /studio/bellona/engine-synchronization now has focused real-dev-infra Playwright coverage for live lockstep checksum analyser catalog load, AuthProvider Bellona-admin bearer propagation, default desync/laggard verdict, fully agreed clean run, unknown-peer / empty-peer / empty-frame / schema gates from the real BFF, malformed JSON and non-object JSON with no POST, pending submit disablement, catalog 503/malformed states, malformed analysis success, transport failure, non-admin unauthorized, anonymous redirect, route-map / quick-action affordances, and engine-sync JSON textarea / submit / quick-action mobile 44px controls. The whole Bellona task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-01 progress: /studio/bellona/sync-conflict-resolution now has focused real-dev-infra Playwright coverage for live vector-clock LWW resolver catalog load, AuthProvider Bellona-admin bearer propagation, default concurrent-edit verdict, causality-over-wall-clock resolution, equal-timestamp replica tie-break behavior, empty-edit / invalid-edit / schema gates from the real BFF, malformed JSON and non-object JSON with no POST, pending submit disablement, catalog 503/malformed states, malformed resolution success, transport failure, non-admin unauthorized, anonymous redirect, route-map / quick-action affordances, and sync-conflict JSON textarea / submit / quick-action mobile 44px controls. The whole Bellona task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-01 progress: /studio/bellona/shared-xr-capabilities now has focused real-dev-infra Playwright coverage for live shared-XR capability catalog load, AuthProvider Bellona-admin bearer propagation, default cross-platform portability verdict, universal / unsupported / unknown-capability outcomes from the real BFF, direct BFF auth/payload/schema gates, malformed JSON and non-object JSON with no POST, pending submit disablement, catalog 503/malformed states, malformed resolution success, transport failure, non-admin unauthorized, anonymous redirect, route-map / quick-action affordances, and shared-XR JSON textarea / submit / quick-action mobile 44px controls. The whole Bellona task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-01 progress: /studio/bellona/xr-platform-support now has focused real-dev-infra Playwright coverage for live XR platform capability catalog load, AuthProvider Bellona-admin bearer propagation, default cleared launch gate with degraded optional eye tracking, blocked required-feature behavior, degraded optionals, unknown-feature diagnostics from the real BFF, direct BFF auth/payload/schema gates, malformed JSON and non-object JSON with no POST, pending submit disablement, catalog 503/malformed states, malformed resolution success, transport failure, non-admin unauthorized, anonymous redirect, route-map / quick-action affordances, and XR platform JSON textarea / submit / quick-action mobile 44px controls. The whole Bellona task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-01 progress: /studio/bellona/visionos-features now has focused real-dev-infra Playwright coverage for live visionOS presentation / immersion-space catalog load, AuthProvider Bellona-admin bearer propagation, default mixed-immersive compatibility verdict, Full Space / Shared Space / passthrough-space / unknown-feature outcomes from the real BFF, direct BFF auth/payload/schema gates, malformed JSON and non-object JSON with no POST, pending submit disablement, catalog 503/malformed states, malformed resolution success, transport failure, non-admin unauthorized, anonymous redirect, route-map / quick-action affordances, and visionOS JSON textarea / submit / shared XR-feature quick-action mobile 44px controls. The whole Bellona task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-01 progress: /studio/bellona/meta-quest-features now has focused real-dev-infra Playwright coverage for live Quest device-model / OS-version feature catalog load, AuthProvider Bellona-admin bearer propagation, default Quest 3 feature-gating verdict, supported-model / requires-update / Quest-Pro / unknown-feature outcomes from the real BFF, direct BFF auth/payload/schema gates, malformed JSON and non-object JSON with no POST, pending submit disablement, catalog 503/malformed states, malformed resolution success, transport failure, non-admin unauthorized, anonymous redirect, route-map / quick-action affordances, and Meta Quest JSON textarea / submit / shared XR-feature quick-action mobile 44px controls. The whole Bellona task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-01 progress: /studio/bellona/blender-bridge-commands now has focused real-dev-infra Playwright coverage for live Blender bridge-command catalog load, AuthProvider Bellona-admin bearer propagation, default healthy/degraded/unhealthy SLO classification, Blender cost-model metrics, invalid config issue-code rendering, direct BFF auth/scope/payload/schema gates, malformed JSON / non-object JSON / missing commands with no POST, pending submit disablement, catalog 503/malformed states, malformed analysis success, transport failure, non-admin unauthorized, anonymous redirect, route-map / quick-action affordances, and Blender command JSON textarea / submit / bridge-command quick-action mobile 44px controls. The whole Bellona task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-01 progress: /studio/bellona/unity-bridge-commands now has focused real-dev-infra Playwright coverage for live Unity bridge-command catalog load, AuthProvider Bellona-admin bearer propagation, default healthy/degraded/unhealthy SLO classification, Unity cost-model metrics, invalid config issue-code rendering, direct BFF auth/scope/payload/schema gates, malformed JSON / non-object JSON / missing commands with no POST, pending submit disablement, catalog 503/malformed states, malformed analysis success, transport failure, non-admin unauthorized, anonymous redirect, route-map / quick-action affordances, and Unity command JSON textarea / submit / bridge-command quick-action mobile 44px controls. The whole Bellona task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-01 progress: /studio/bellona/godot-bridge-commands now has focused real-dev-infra Playwright coverage for live Godot bridge-command catalog load, AuthProvider Bellona-admin bearer propagation, default healthy/degraded/unhealthy SLO classification, Godot cost-model metrics, invalid config issue-code rendering, direct BFF auth/scope/payload/schema gates, malformed JSON / non-object JSON / missing commands with no POST, pending submit disablement, catalog 503/malformed states, malformed analysis success, transport failure, non-admin unauthorized, anonymous redirect, route-map / quick-action affordances, and Godot command JSON textarea / submit / bridge-command quick-action mobile 44px controls. The whole Bellona task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-01 progress: /studio/bellona/unreal-bridge-commands now has focused real-dev-infra Playwright coverage for live Unreal bridge-command catalog load, AuthProvider Bellona-admin bearer propagation, default healthy/degraded/unhealthy SLO classification, Unreal cost-model metrics, invalid config issue-code rendering, direct BFF auth/scope/payload/schema gates, malformed JSON / non-object JSON / missing commands with no POST, pending submit disablement, catalog 503/malformed states, malformed analysis success, transport failure, non-admin unauthorized, anonymous redirect, route-map / quick-action affordances, and Unreal command JSON textarea / submit / bridge-command quick-action mobile 44px controls. The whole Bellona task remains open until the other inventoried surfaces receive equivalent verification.
  • Not a box since 2026-09-18: each surface has its own box in the coverage family walkthrough-studio (WALKTHROUGH/studio/domain-bridges/hathor/), so this roll-up counted the same work twice; its progress log below is kept. Verify every Hathor Studio surface inventoried under WALKTHROUGH/studio/domain-bridges/hathor/ (74 docs: characters, factions, geography, timelines, quests, dialogue trees, economy/culture/ legal-system simulation, chronicle parsing, lore validation) against the routes under apps/oshun/web/src/app/studio/hathor/ and the libs/hathor/* implementations, one surface at a time.
    • 2026-06-25 progress: /studio/hathor/workbench-world-editor now has real-dev-infra Playwright coverage for admin catalog load, seeded missing-location verdict, clean export-ready verdict, BFF schema-error surfacing, malformed JSON client rejection with no POST, pending submit disablement, non-admin fail-closed state, route-map / quick-action affordances, mobile 44px controls, and axe. The whole Hathor task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-03 progress: /studio/hathor/chronicle-parser now has focused real-dev-infra Playwright coverage for live chronicle-parser catalog load, AuthProvider Hathor-admin bearer propagation, exact two-age parseChronicle statistics through the real BFF and @hathor/pre-production, document-reference parsing, client-only empty-source rejection, BFF detail surfacing, parse transport failure, catalog loading / 503 / malformed states, non-admin fail-closed behavior, pending submit disablement, route-map / quick-action affordances, mobile 44px controls, shared axe scans, and direct BFF auth/schema gates. The whole Hathor task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-03 progress: /studio/hathor/cinematography-planning now has focused real-dev-infra Playwright coverage for live cinematography reference catalog load, AuthProvider Hathor-admin bearer propagation, exact @hathor/theory shot-scale / lighting-style / camera-angle / color-scheme reference-card output through the real BFF, neutral fallback planning, client-only empty emotion/mood rejection, BFF detail surfacing, plan transport failure, catalog loading / 503 / malformed states, non-admin fail-closed behavior, pending submit disablement, the 247-entry route-map contract, quick-action affordances, representative panel-cluster presence, mobile 44px controls, shared axe scans, and direct BFF auth/schema gates. The whole Hathor task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-03 progress: /studio/hathor/game-design-theory-mda now has focused real-dev-infra Playwright coverage for live MDA catalog load, AuthProvider Hathor-admin bearer propagation, exact @hathor/theory Hunicke Challenge aesthetic and Resource Collection mechanic-template output through the real BFF, aesthetic-only and mechanic-only lookup bodies, client-only empty-selection rejection, BFF detail surfacing, lookup transport failure, catalog loading / 503 / malformed states, non-admin fail-closed behavior, pending submit disablement, route-map / quick-action affordances, mobile 44px controls, scoped axe scans, and direct BFF auth/schema gates. The whole Hathor task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-03 progress: /studio/hathor/character-modeling now has focused real-dev-infra Playwright coverage for live CGI packet issue-type catalog load, AuthProvider Hathor-admin bearer propagation, exact complete-packet and incomplete-packet @hathor/characters validation through the real BFF, client-only malformed-JSON rejection with no POST, BFF invalid_packet detail surfacing, malformed success payload handling, validate transport failure, catalog loading / 503 / malformed states, non-admin fail-closed behavior, pending submit disablement, route-map / quick-action affordances, mobile 44px/no-overflow controls, scoped axe scans, and direct BFF auth/schema gates. The whole Hathor task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-03 progress: /studio/hathor/culture-modeling now has focused real-dev-infra Playwright coverage for live culture catalog load, AuthProvider Hathor-admin bearer propagation, exact default and edited @hathor/domain-models culture-compatibility metrics through the real BFF, client-only malformed-JSON rejection with no POST, BFF culture.socialStructure must be a known social structure detail surfacing, malformed success payload handling, assess transport failure, catalog loading / 503 / malformed states, non-admin fail-closed behavior, pending submit disablement, route-map / quick-action affordances, mobile 44px/no-overflow controls, scoped axe scans, and direct BFF auth/schema gates. The whole Hathor task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-03 progress: /studio/hathor/economy-modeling now has focused real-dev-infra Playwright coverage for live economy catalog load, AuthProvider Hathor-admin bearer propagation, exact default and edited @hathor/domain-models resource-pricing metrics and sensitivity curves through the real BFF, client-only malformed-JSON rejection with no POST, BFF rarity must be a known rarity detail surfacing, malformed success payload handling, price transport failure, catalog loading / 503 / malformed states, non-admin fail-closed behavior, pending submit disablement, route-map / quick-action affordances, mobile 44px/no-overflow controls, scoped axe scans, and direct BFF auth/schema gates. The whole Hathor task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-03 progress: /studio/hathor/pre-production-project-management now has focused real-dev-infra Playwright coverage for live project-health category catalog load, AuthProvider Hathor-admin bearer propagation, exact default blocked, edited healthy, and edited lopsided @hathor/pre-production project-health scores through the real BFF, client-only malformed-line rejection with no POST, BFF each task needs taskId, a known category, and a status detail surfacing, malformed success payload handling, assess transport failure, catalog loading / 503 / malformed states, non-admin fail-closed behavior, pending submit disablement, route-map / quick-action affordances, mobile 44px/no-overflow controls, scoped axe scans, and direct BFF auth/schema gates. The whole Hathor task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-03 progress: /studio/hathor/visual-storyboarding now has focused real-dev-infra Playwright coverage for live storyboard-linter catalog load, AuthProvider Hathor-admin bearer propagation, exact seeded incomplete, edited clean, and edited location-info @hathor/pre-production storyboard validation through the real BFF, client-only malformed-JSON rejection with no POST, BFF storyboard.frames must be an array detail surfacing, malformed success payload handling, validate transport failure, catalog loading / 503 / malformed states, non-admin fail-closed behavior, pending submit disablement, route-map / quick-action affordances, mobile 44px/no-overflow controls, scoped axe scans, and direct BFF auth/schema gates. The whole Hathor task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-03 progress: /studio/hathor/lore-compilation-for-engines now has focused real-dev-infra Playwright coverage for live engine-format catalog load, AuthProvider Hathor-admin bearer propagation, exact seeded JSON, edited three-quest YAML, and edited SQLite @hathor/lore-compiler exports through the real BFF, client-only malformed-JSON and empty-array rejection with no POST, BFF invalid_quest reason surfacing, malformed success payload handling, compile transport failure, catalog loading / 503 / malformed states, non-admin fail-closed behavior, pending submit disablement, route-map / quick-action affordances, mobile 44px/no-overflow controls, scoped axe scans, and direct BFF auth/schema gates. The whole Hathor task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-03 progress: /studio/hathor/journal-and-codex now has focused real-dev-infra Playwright coverage for live codex-resolver catalog load, AuthProvider Hathor-admin bearer propagation, exact default 3-of-4-unlocked, edited empty-discovery 1-of-4-unlocked, and duplicate-flag codex unlock results through the real BFF, client-only malformed-JSON and non-object rejection with no POST, BFF duplicate entryId 'e' detail surfacing, malformed success payload handling, resolve transport failure, catalog loading / 503 / malformed states, non-admin fail-closed behavior, pending submit disablement, route-map / quick-action affordances, mobile 44px/no-overflow controls, scoped axe scans, and direct BFF auth/schema gates. The whole Hathor task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-03 progress: /studio/hathor/narrative-export now has focused real-dev-infra Playwright coverage for live segment-type catalog load, AuthProvider Hathor-admin bearer propagation, exact seeded runtime/page/type estimate and edited stage-direction partial-page estimate through the real BFF, client-only malformed-JSON and non-object rejection with no POST, BFF duplicate segmentId 'x' detail surfacing, malformed success payload handling, estimate transport failure, catalog loading / 503 / malformed states, non-admin fail-closed behavior, pending submit disablement, route-map / quick-action affordances, mobile 44px/no-overflow controls, scoped axe scans, and direct BFF auth/schema gates. The whole Hathor task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-04 progress: /studio/hathor/narrative-structure-analysis now has focused real-dev-infra Playwright coverage for live Ink/Yarn/JSON export format catalog load, AuthProvider Hathor-admin bearer propagation, exact seeded Ink EMPTY_CHOICE, edited all-ready complete dialogue, missing-entry NO_ENTRY_NODE, and Yarn self-cycle CYCLE_DETECTED validation through the real BFF, client-only malformed-JSON and non-object rejection with no POST, BFF malformed-node detail surfacing, malformed success payload handling, validate transport failure, catalog loading / 503 / malformed states, non-admin fail-closed behavior, pending submit disablement, route-map / quick-action affordances, mobile 44px/no-overflow controls, scoped axe scans, and direct BFF auth/schema gates. The whole Hathor task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-04 progress: /studio/hathor/scenario-generation now has focused real-dev-infra Playwright coverage for live issue-type/severity catalog load, AuthProvider Hathor-admin bearer propagation, exact seeded missing-scene-dependency, edited all-ready clean packet, missing-objective, warning-only missing-capture-requirement, and missing-cgi-export outputs through the real BFF, client-only malformed-JSON and non-object rejection with no POST, BFF malformed-scene detail surfacing, malformed success payload handling, validate transport failure, catalog loading / 503 / malformed states, non-admin fail-closed behavior, pending submit disablement, route-map / quick-action affordances, mobile 44px/no-overflow controls, scoped axe scans, and direct BFF auth/schema gates. The whole Hathor task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-04 progress: /studio/hathor/culture-evolution-simulation now has focused real-dev-infra Playwright coverage for live social-structure / attitude catalog load, AuthProvider Hathor-admin bearer propagation, exact seeded @hathor/domain-models compatibility 70 output, edited hostile / hierarchical compatibility -20 output, dominant-value / social-mobility / inequality metrics through the real BFF, client-only malformed-JSON and non-object rejection with no POST, BFF unknown-social-structure detail surfacing, malformed success payload handling, assess transport failure, catalog loading / 503 / malformed states, non-admin fail-closed behavior, pending submit disablement for both editors, route-map / quick-action affordances, mobile 44px/no-overflow controls, scoped axe scans, and direct BFF auth/schema gates. The whole Hathor task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-04 progress: /studio/aja/mobile-live-capture now has focused real-dev-infra Playwright coverage for the live adaptive-bitrate selector catalog load, AuthProvider Aja-admin bearer propagation, exact seeded r720 selection at 3200 usable kbps, low-bandwidth lo floor selection, per-rung sustainable/selected table state through the real BFF, client-only malformed-JSON and non-object rejection with no POST, BFF duplicate-rung detail surfacing, malformed success payload handling, select transport failure, catalog loading / 503 / malformed states, non-admin fail-closed behavior, pending submit disablement, route-map / quick-action affordances, mobile 44px/no-overflow controls, scoped axe scans, and direct BFF auth/schema gates. The whole Aja task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-04 progress: /studio/aja/desktop-live-capture now has focused real-dev-infra Playwright coverage for the live frame-budget analyzer catalog load, AuthProvider Aja-admin bearer propagation, exact seeded over-budget/dropped-frame output and edited clean no-over-budget output through the real BFF, client-side JSON/object validation with no POST, BFF duplicate-frame detail surfacing, malformed result handling, analyze transport failure, catalog loading / 503 / malformed states, non-admin fail-closed behavior, pending submit disablement, route-map / quick-action affordances, mobile 44px/no-overflow controls, scoped axe scans, and direct BFF auth/schema gates. The whole Aja task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-04 progress: /studio/aja/input-video-support now has focused real-dev-infra Playwright coverage for the live chunking/blending catalog load, AuthProvider Aja-admin bearer propagation, exact seeded 900-frame 30fps / 10s / 1s plan and edited 1500-frame 30fps / 20s / 2s plan through the real BFF, client-side integer/positive-number validation with no POST, malformed result handling, plan transport failure, catalog loading / 503 / malformed states, non-admin fail-closed behavior, pending submit disablement, route-map / quick-action affordances, mobile 44px/no-overflow controls, scoped axe scans, and direct BFF auth/schema gates. The whole Aja task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-04 progress: /studio/aja/medical-rehabilitation-pipeline now has focused real-dev-infra Playwright coverage for the live joint-angle-range-of-motion catalog load, AuthProvider Aja-admin bearer propagation, exact seeded out-of-range LeftLeg violation output and edited clean no-violation output through the real BFF, client-side joint/JSON/frame validation with no POST, BFF missing-joint detail surfacing, malformed result handling, analyze transport failure, catalog loading / 503 / malformed states, non-admin fail-closed behavior, pending submit disablement, route-map / quick-action affordances, mobile 44px/no-overflow controls, scoped axe scans, and direct BFF auth/schema gates. The whole Aja task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-04 progress: /studio/aja/performance-optimization now has focused real-dev-infra Playwright coverage for the live quantization catalog load, AuthProvider Aja-admin bearer propagation, exact default 8-bit symmetric quantization output and edited 8-bit asymmetric output through the real BFF, client-side numeric/bit-width validation with no POST, BFF detail surfacing, malformed result handling, quantize transport failure, catalog loading / 503 / malformed states, non-admin fail-closed behavior, pending submit disablement, route-map / quick-action affordances, mobile 44px/no-overflow controls, scoped axe scans, and direct BFF auth/schema gates. The whole Aja task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-04 progress: /studio/aja/dance-pipeline now has focused real-dev-infra Playwright coverage for the live temporal-coherence catalog load, AuthProvider Aja-admin bearer propagation, exact seeded teleport/stutter output and edited clean-flow output through the real BFF, client-side joint/JSON/frame-count validation with no POST, BFF validation detail surfacing, malformed result handling, analyze transport failure, catalog loading / 503 / malformed states, non-admin fail-closed behavior, pending submit disablement, Metis bridge links, route-map / quick-action affordances, mobile 44px/no-overflow controls, scoped axe scans, and direct BFF auth/schema gates. The whole Aja task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-04 progress: /studio/aja/fitness-pipeline now has focused real-dev-infra Playwright coverage for the live smoothness catalog load, AuthProvider Aja-admin bearer propagation, exact seeded jerk/discontinuity output and edited clean constant-velocity output through the real BFF, client-side joint/JSON/frame-count/threshold validation with no POST, BFF validation detail surfacing, malformed result handling, analyze transport failure, catalog loading / 503 / malformed states, non-admin fail-closed behavior, pending submit disablement, Metis bridge links, route-map / quick-action affordances, mobile 44px/no-overflow controls, scoped axe scans, and direct BFF auth/schema gates. The whole Aja task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-04 progress: /studio/aja/yoga-pipeline now has focused real-dev-infra Playwright coverage for the live naturalness catalog load, AuthProvider Aja-admin bearer propagation, exact seeded synchronized-limb coordination output and edited still balanced pose output through the real BFF, client-side joint/JSON/frame-count validation with no POST, BFF validation detail surfacing, malformed result handling, analyze transport failure, catalog loading / 503 / malformed states, non-admin fail-closed behavior, pending submit disablement, Metis bridge links, route-map / quick-action affordances, mobile 44px/no-overflow controls, scoped axe scans, and direct BFF auth/schema gates. The whole Aja task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-04 progress: /studio/aja/sports-pipeline now has focused real-dev-infra Playwright coverage for the live physical-plausibility catalog load, AuthProvider Aja-admin bearer propagation, exact seeded hip teleport violation output and edited static grounded pose output through the real BFF, client-side joint/JSON/frame-count validation with no POST, BFF validation detail surfacing, malformed result handling, analyze transport failure, catalog loading / 503 / malformed states, non-admin fail-closed behavior, pending submit disablement, Metis bridge links, route-map / quick-action affordances, mobile 44px/no-overflow controls, scoped axe scans, and direct BFF auth/schema gates. The whole Aja task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-04 progress: /studio/aja/martial-arts-pipeline now has focused real-dev-infra Playwright coverage for the live style-consistency catalog load, AuthProvider Aja-admin bearer propagation, exact seeded RightHand pose-shift style-break output and edited steady-form clean output through the real BFF, client-side joint/JSON/frame-count/window validation with no POST, BFF validation detail surfacing, malformed result handling, analyze transport failure, catalog loading / 503 / malformed states, non-admin fail-closed behavior, pending submit disablement, Metis bridge links, route-map / quick-action affordances, mobile 44px/no-overflow controls, scoped axe scans, and direct BFF auth/schema gates. The whole Aja task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-04 progress: /studio/aja/gaming-pipeline now has focused real-dev-infra Playwright coverage for the live perceptual-quality catalog load, AuthProvider Aja-admin bearer propagation, exact shipped balanced game-animation output and edited degraded clip output through the real BFF, client-side joint/JSON/frame-count validation with no POST, BFF validation detail surfacing, malformed result handling, analyze transport failure, catalog loading / 503 / malformed states, non-admin fail-closed behavior, pending submit disablement, route-map / quick-action affordances, mobile 44px/no-overflow controls, scoped axe scans, and direct BFF auth/schema gates. The whole Aja task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-04 progress: /studio/aja/film-vfx-pipeline now has focused real-dev-infra Playwright coverage for the live visual-quality catalog load, AuthProvider Aja-admin bearer propagation, exact shipped balanced professional pose output and edited asymmetric low-hand poor output through the real BFF, client-side joint/JSON/frame-count validation with no POST, BFF validation detail surfacing, malformed result handling, analyze transport failure, catalog loading / 503 / malformed states, non-admin fail-closed behavior, pending submit disablement, route-map / quick-action affordances, mobile 44px/no-overflow controls, scoped axe scans, and direct BFF auth/schema gates. The whole Aja task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-04 progress: /studio/aja/mocap-data-processing now has focused real-dev-infra Playwright coverage for the live footskate catalog load, AuthProvider Aja-admin bearer propagation, exact shipped sliding planted foot output, edited clean no-artifact output, and edited ground-penetration output through the real BFF, client-side joint/JSON/frame/threshold validation with no POST, BFF validation detail surfacing, malformed result handling, detect transport failure, catalog loading / 503 / malformed states, non-admin fail-closed behavior, pending submit disablement, route-map / quick-action affordances, mobile 44px/no-overflow controls, scoped axe scans, and direct BFF auth/schema gates. The whole Aja task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-04 progress: /studio/aja/mocap-input-formats now has focused real-dev-infra Playwright coverage for the live Alembic-JSON validator catalog load, AuthProvider Aja-admin bearer propagation, exact shipped valid document readback and edited malformed-document blocking errors/warnings through the real BFF, client-side blank-input validation with no POST, BFF validation detail surfacing, malformed result handling, validate transport failure, catalog loading / 503 / malformed states, non-admin fail-closed behavior, pending submit disablement, route-map / quick-action affordances, mobile 44px/no-overflow controls, scoped axe scans, and direct BFF auth/schema gates. The whole Aja task remains open until the other inventoried surfaces receive equivalent verification.
    • 2026-07-04 progress: /studio/aja/human-mesh-recovery now has focused real-dev-infra Playwright coverage for the live PCK catalog load, AuthProvider Aja-admin bearer propagation, exact shipped partially-correct keypoint output and edited perfect-pose output through the real BFF, client-side prediction/ground-truth JSON and normalization validation with no POST, BFF validation detail surfacing, malformed result handling, assess transport failure, catalog loading / 503 / malformed states, non-admin fail-closed behavior, pending submit disablement, breadcrumb / route-map / quick-action affordances, mobile 44px/no-overflow controls, scoped axe scans, and direct BFF auth/schema gates. The whole Aja task remains open until the other inventoried surfaces receive equivalent verification.
  • Verify the Neith inverse-modeling workspace (WALKTHROUGH/studio/domain-bridges/neith/studio-neith-inverse-modeling.md) against apps/oshun/web/src/app/studio/neith/inverse-modeling/ — feature extraction (mean, contrast, edgeEnergy, entropy, warmBias), parameter estimation across the four models (terrain, vegetation, urban, noise), confidence scoring, and export-manifest output — with domain-correctness tests (known reference image → known parameter estimates), not just render checks.
  • Verify Studio entitlement gating for every Bellona/Hathor/Neith route (auth: signed-in + studio entitlement, per the walkthrough front matter) is enforced at component, route, and BFF layers with deny-by-default behavior.

35. Dependency Gap Closure (from DEPENDENCIES self-flagged launch gaps)#

Added 2026-06-12. V1/DEPENDENCIES.md self-flags the launch gaps below, but no section of this backlog previously tracked them. Each task cites the registry section and line (line numbers as of 2026-06-12) that declares the gap.

  • Pin and integrate the missing mobile Expo modules — expo-notifications, expo-av, expo-image, expo-camera, expo-file-system — in apps/oshun/mobile/package.json, or declare the supporting Expo plugins / native modules in the prebuild config, covering push routing (domain/persona/quiet-hours/sensitivity), Tara meditation and Living Scenes narration audio, offline media caching, and camera/microphone capture (V1/DEPENDENCIES.md § 6 "Launch-readiness gap", lines 201–207). 2026-07-03: expo-notifications, expo-audio (+expo-camera, expo-image, expo-image-picker, expo-file-system, expo-crypto) are pinned via the pnpm catalog and declared as plugins in app.json (expo-av is deprecated in SDK 56; expo-audio is its successor and carries Tara meditation + narration playback). Real integrations: src/audio/meditationPlaybackEngine.ts (native playback + lock-screen Now Playing driving the Tara session state machine), src/capture/mobileCapturePermissionsBridge.ts (OS-truth camera/mic/ photo-library permissions), src/data/download-manager.ts (SDK 56 File/Directory + DownloadTask transfer port), and src/components/MeditationArtwork.tsx (expo-image artwork).
  • Pin a C2PA mint/verify SDK (e.g. c2pa-node or equivalent) in the pnpm catalog and wire manifest mint/verify so C2PA-signed manifests can be exported off-platform (V1/DEPENDENCIES.md § 19, line 546). 2026-07-06: c2pa-node ^0.5.26 pinned in the catalog (+onlyBuiltDependencies). New @oshun/c2pa-export (libs/oshun/c2pa-export): fail-loud signer resolution from OSHUN_C2PA_EXPORT_{CERT,KEY}_PEM (documented SDK quirk: the 0.5.x native binding timestamps every signature, so a TSA URL is required and signing needs egress; defaults to DigiCert), standards-compliant mint (JUMBF+COSE embed with c2pa.actions created-action + IPTC digitalSourceType, schema.org CreativeWork, optional c2pa.training-mining do-not-train, and an org.oshun.provenance assertion linking the in-house Ed25519 sidecar), and typed verify (valid/invalid/tampered/absent from real SDK validation statuses). Wired into the Living Scene share path (apps/oshun/bff/src/routes/living-scenes.ts): configured → the APNG carries an embedded interoperable manifest and the Ed25519 sidecar signs the embedded bytes; unconfigured → production fails closed (c2pa_export_signing_not_configured), dev reports standardC2pa.embedded=false with the reason. Round-trip + tamper + APNG-acTL-survival tests green (7 lib + 2 BFF; existing 22 route tests unaffected); env template documented in .env.example.
  • Document ARETE_DATABASE_URL, VERITAS_DATABASE_URL, NYX_DATABASE_URL, and METIS_DATABASE_URL in .env.example, or declare explicitly that those domains run against the shared oshun_dev database for V1 launch (V1/DEPENDENCIES.md § 21, lines 592–602). 2026-07-06: declared option (a) explicitly — .env.example now carries a "V1 Domain Databases" section pinning all four vars to the shared oshun_dev URL, documenting that the four domains are deliberately absent from POSTGRES_MULTIPLE_DATABASES, that libs/metis/knowledge-graph resolves METIS_DATABASE_URL ?? DATABASE_URL (fails loud when neither set), and that libs/oshun/persistence/src/migration-plan.ts names each var as the per-domain source DB for the post-V1 split.
  • Add NYX_*_URL entries to .env.example for the Nyx prediction sources (NASA JPL, IMO, IERS, NOAA SWPC, weather, Bortle) alongside the per-source API keys (V1/DEPENDENCIES.md § 18, lines 521–524). 2026-07-06: added a "Nyx Prediction Sources" section — seven NYX_*_URL base URLs (JPL Horizons + ssd-api, IMO calendar, IERS Bulletin A, NOAA SWPC, weather provider, Bortle atlas) mirroring the canonical endpoints compiled into libs/nyx/catalogs/solar-system/* and libs/nyx/realtime/solar (DEFAULT_NOAA_CONFIG), each annotated with its PredictionSourceKind mapping and consuming module, plus NYX_NASA_API_KEY (DEMO_KEY default documented as throttled) and NYX_WEATHER_PROVIDER_API_KEY.
  • Decide and record the ElevenLabs integration path: either keep the direct HTTP client as the supported V1 path (documented as such) or pin the elevenlabs SDK in pnpm-workspace.yaml (V1/DEPENDENCIES.md § 9, line 260). 2026-07-06: decided — the direct HTTP client is the supported V1 path, recorded in V1/DEPENDENCIES.md § 9. Grounds: the direct client is a deep, tested integration (~5.1k-line libs/isis/audio-generation/src/voice/elevenlabs-client.ts with spec + ~1.4k-line libs/isis/ai-providers/.../elevenlabs-provider.ts), and the official SDK would duplicate it for no capability gain. Revisit only if ElevenLabs ships an API surface the direct client cannot reach.

36. Mentor Presence — Meditating with a Master#

Added 2026-07-06. Forward spec at V1/features/mentor-presence.md: the meditation player's static artwork becomes an embodied mentor scene — one to three governed mentor personas arrive (already-present, walk-in, emerge-from-water, materialize), settle into a lineage-appropriate posture, and guide the sit with voice, cadence-locked breath, and held silence. Every task below is unstarted; the spec page marks which existing contracts each task composes.

36.1 Contracts and taxonomies#

  • Implement mentor-presence contracts in libs/contracts/src/tara/mentor-presence.ts: the setting catalog (8 launch settings with water, ether/mist variant, sensoryLoad, and context-tag affinity), the arrival vocabulary (already-present, walk-in, emerge-from-water, materialize) with per-arrival duration ceilings (≤ 30s; materialize ≥ 8s condense), and the posture catalog keyed by modality family — exported as validated runtime constants (satisfies), not just types. 2026-07-06: shipped as a "Mentor Presence" section appended to libs/contracts/src/tara/index.ts rather than a sibling module — a standalone mentor-presence.ts importing the taxonomies from ./index hits the ESM re-export hoisting cycle (TDZ on ContextTagSchema et al.), and the monolith is the house style for taxonomy contracts. MENTOR_PRESENCE_SETTINGS (8, satisfies-validated, night/sleep-onset settings pinned to low sensory load), MENTOR_ARRIVALS (4, ≤ 30s, materialize ≥ 8s, only already-present permitted under reduced motion/high distress, non-instant arrivals barred from sleep-onset), MENTOR_POSTURES (6) + MODALITY_FAMILY_POSTURES (all 7 families; embodiment=standing, devotional=kneeling/seiza), plus resolveMentorArrival forcing function. 30 domain tests in mentor-presence.spec.ts, tsc clean, stub scan clean.
  • Implement the choreography score schema (MentorPresenceScore): mentors (1–3, one lead voice), setting, arrival, posture set, cadence binding, and render-envelope reference, with superRefine invariants: arrival-setting legality (emerge-from-water requires a water setting; materialize requires an ether/mist variant), posture-modality matching, reduced-motion and high-distress-mood forcing of already-present, cross-lineage circles requiring a comparative-role lead (syncretism gate), and sound-singing-bowl seating an instrument. 2026-07-06: MentorPresenceScoreSchema in libs/contracts/src/tara/index.ts carries every listed invariant plus exactly-one-lead, one-voice-at-a-time (voiced companions rejected), unique persona ids, night/sleep-onset setting-affinity matching, low-sensory practice never resolving to a moderate arrival, counted breathwork pinned to the modality's canonical BreathworkCadence (mentor never contradicts the practice clock), and lead posture ∈ the avatar pack's lineage-reviewed posture set. Each invariant has a negative + positive test (48 tara contract tests green).

36.2 Mentor cast#

  • Register the launch mentor personas in @oshun/persona-registry (teacher role solo/same-lineage leads; one comparative-role lead for cross-lineage circles) with avatar packs (safety blendshapes + full viseme maps), voice profiles, and consent ledgers; realism capped at photoreal-generic, launch cast at stylised-3d/semirealistic-3d, source identity synthetic-only. 2026-07-06: mentor-presence-cast.ts ships MENTOR_PRESENCE_CAST — four mentors (sela-stillwater secular / anand-breathkeeper pranayama / ishya-heartlamp bhakti as teacher leads; sage-confluence as the single comparative lead), each with a PersonaRecord at drafted status (release requires the §36.6 gates), a synthetic voice profile (breath-paced 0.88× rate, 900 ms sentence pauses, spoken-synthesis disclosure + C2PA required), an avatar pack passing the strict validator (safety blendshapes, full 13-viseme map, per-frame watermark + C2PA, active license), synthetic-only likeness (consent ledger empty BY CONSTRUCTION — the validator enforces no fabricated consents), home/permitted settings, permitted arrivals (all include already-present), and lineage-reviewed posture sets. validateMentorPresenceCast() returns zero errors and catches corrupted entries (ceiling breach, protected-identity name, missing comparative). 18 tests; full registry suite 66 files / 1,462 tests green.
  • Add the venerated-figure denylist for this surface: the named lineage teachers in TARA_LINEAGE_TAXONOMY (Gautama Buddha, Buddhaghosa, Shantideva, Padmasambhava, Patanjali, Mirabai) are never rendered, named as the mentor, or vocally imitated; wire detectPromptImpersonationAttempt on mentor-selection and live-direction inputs.
    • 2026-07-06: the denylist is shipped — MENTOR_VENERATED_FIGURE_DENYLIST (11 identities with aliases: all real and venerated figures in TARA_LINEAGE_TAXONOMY including Avalokiteshvara, Yeshe Tsogyal, T. Krishnamacharya, Adi Shankara, Ramana Maharshi beyond the six named here) + MENTOR_PRESENCE_DENYLIST (seed list included) + screenMentorDirectionPrompt() combining detectPromptImpersonationAttempt with a normalized venerated-name scan (blocks "make the mentor look like Guru Rinpoche" even without an impersonation verb; diacritics normalized). Wired at the BFF: POST /v1/tara/mentor-presence/direction-screen (apps/oshun/bff/src/routes/mentor-presence.ts) screens every mentor-selection / live-direction prompt and 422s blocked directions naming the venerated hits; the cast validator additionally rejects any cast member whose display name or id resolves to a protected identity. Route + unit tests green. Marked complete below.
  • Run lineage sensitivity review (postures, vestments, settings, parting forms) per mentor under the Lilith cultural and lineage sensitivity policy, with the lineage disclosureLabel shown at selection. Board tag 2026-09-18: a review by people under the cultural and lineage sensitivity policy. blocked:human

36.3 Choreography decision layer#

  • Implement the pure choreography state machine in libs/oshun/domain-tara/src/mentor-presence/ (Conductor-style: decision layer only, no pixels): session state in → mentor behavior out, covering all eight SessionStateSchema states (paused = rest-with-you, drifted = one soft bell + settled gaze, abandoned = scene rests without disappointment, completed = parting bow) with no invented states and legal-transition checks against SESSION_STATE_TRANSITIONS. 2026-07-06: choreography.ts — 11-behavior catalog (every behavior holds silence; voice only in guide/partings; breath idle everywhere except pre-start and the crisis frame), mentorBehaviorForSessionState spec table, and reduceMentorChoreography with double-checked transitions (stream coherence + isValidSessionStateTransition), phase walk arrive → settle → guide, re-anchor on resume, and out-of-band crisis collapse that tracks the session underneath and never auto-resumes guidance.
  • Implement the cadence-lock driver: breath idle paced by the practice's real BreathworkCadence (and TARA_SUBVARIANTS breath cycles), scaled on the audio clock under QUALITY_PRESERVING_PLAYBACK_RATE_POLICY (0.85×–1.25×) so mentor breath never contradicts the heard cues; silence is held (idle continues, no filler). 2026-07-06: cadence-lock.ts — breathPhaseAtAudioPosition (raised-cosine chest expansion, zero-length holds skipped, resting in-4/out-6 breath for un-counted practice) and audioPositionAtWallClock through the contracts' own normalizePlaybackRate (rates snap to the 0.05 step; out-of-range throws PlaybackRateRangeError). Known-value tests: box mid-inhale expansion 0.5 at t=2; 1.6 wall-seconds at 1.25× lands the chest exactly where 2 s at 1× does.
  • Emit/consume Psyche scene events for presence sessions (scene.segment-start, scene.policy-intervention, scene.crisis-frame, scene.fallback-engaged, …) with the monotonic gap-free stream check. 2026-07-06: scene-events.ts — per-sit emitter over the real @oshun/embodiment-psyche envelope; phases map to indexed segments (arrival 0 … parting 3), forced arrivals surface as motion-cap policy interventions carrying the forcing reason, crisis emits crisis-frame + still-image-only fallback; deterministic event/span ids; verifyEventStream accepts the emitted stream in tests. Also added the contracts↔persona-registry vocabulary drift guard here (registry mirrors asserted equal to MENTOR_PRESENCE_SETTINGS/MENTOR_ARRIVALS/ MENTOR_POSTURES). 19 tests; full domain-tara suite 28 files / 303 tests green.

36.4 Authored performance render pipeline#

  • Implement the Isis-governed offline render job for authored performances (session × mentor × setting × arrival): watermarked per-frame, C2PA manifest minted, authorisePersonaConsent checked at render time, deterministic re-render from choreography score + envelope. 2026-07-06: apps/oshun/bff/src/mentor-presence/performance-render.ts + POST /v1/tara/mentor-presence/performances. The job validates the score under MentorPresenceScoreSchema, resolves the lead against the registered cast (unknown mentor 404; settings/arrivals outside the mentor's permits 422), applies the same structural arrival overrides as the live path (resolveMentorArrival), runs the REAL authorisePersonaConsent gate (synthetic-only mentors pass on an empty required set by construction; a consented mentor without artifacts fails closed), renders through the deterministic CPU compositor (@yemaya/rendering-pipelines) with a per-frame watermark that BIT-ENCODES the performance key (32×8 decodable dot matrix — tests decode it back), enforces the WCAG 2.3.1 seizure gate, assembles APNG, and embeds a standards-compliant C2PA manifest when export signing is configured (production fails closed; dev reports the gap). Determinism stated honestly and tested: same score + envelope → identical rawRenderSha256; the C2PA signature attests each materialization. 10 route tests green.
  • Wire performance media into the existing session media pipeline: cacheable/pre-cacheable like session audio, offline sits unchanged, and never blocking session start (audio-first invariant — presence attaches when ready or not at all).
    • 2026-07-06 progress: the BFF half is done — GET /v1/tara/mentor-presence/performances/:id/media serves content-addressed image/apng with cache-control: public, max-age=31536000, immutable, a sha256 ETag (304 revalidation tested), and the deterministic raw-render hash in x-oshun-raw-render-sha256, so the existing session-media downloader can pre-cache it exactly like audio. Stays open until the players (§36.5) consume it audio-first (presence attaches when ready or not at all) and the mobile offline pre-cache list carries it without blocking session start.
    • 2026-07-06 (later): both players now consume the media AUDIO-FIRST — the web layer's attach chain is fire-and-forget relative to the sit clock, and the mobile component renders the artwork rung immediately while presence attaches (expo-image's disk cache then serves it offline exactly like session artwork).
    • 2026-07-06 (complete): proactive offline enrollment shipped — cacheTaraOfflinePresenceMedia (taraOfflineCache.ts) queues the content-addressed media (its sha256 IS the download checksum) through the SAME download manager as session audio, under the customer's offline-downloads preference, with corrupt-item repair and the standard retention window; the mobile component enrolls fire-and-forget AFTER the sit is already playing (audio-first held; tested: enrollment call carries performanceId/sha256/size; skipped when no session id is known). Marked complete above.

36.5 Player integration#

  • Web: add the presence layer to TaraSitPlayer (apps/oshun/web/src/components/lilith/TaraSitPlayer.tsx) as the third visual state (presence → artwork → tonal block → audio-only), rendered behind the transcript/caption layer, with the in-player toggle. 2026-07-06: MentorPresenceLayer.tsx — opt-in toggle (default off, persisted, aria-pressed), audio-first attach chain (capability → mentors → governed render → authed media blob), honest states (off/attaching/active/unavailable with the reason), persistent "Synthetic mentor · name · lineage disclosure" caption, screen-reader scene description as the media alt text, live status line driven by the real mentorBehaviorForSessionState choreography table ("Your mentor rests with you." on pause; "Your mentor bows." on completion), reduced motion forcing already-present in the requested score, per-mentor and per-setting preferences honored from storage. 7 layer tests + existing player suite green.
  • Mobile: add the presence layer at the MeditationArtwork seam (apps/oshun/mobile/src/components/MeditationArtwork.tsx) with the same ladder; thermal/battery pressure steps down one rung proactively; reduced-data mode never fetches presence media.
    • 2026-07-06 progress: MentorPresenceArtwork.tsx wraps the seam in the Tara now-playing card (app/domain/[domainId].tsx) with the ladder presence → artwork → tonal block; resolveMentorPresenceRung never fetches presence media in reduced-data mode (metered connection without the customer's syncOnCellular consent, via NetInfo isConnectionExpensive through useConnectionExpensive); reduced motion forces already-present at render time; every failure steps down to the artwork rung with the reason held. 5 component + 3 rung tests green. Remaining: PROACTIVE thermal/battery step-down — the app pins no battery/thermal native module today (expo-battery is not in the catalog), so there is no honest device-pressure signal to read; pin expo-battery (prebuild impact) and feed lowPowerMode into resolveMentorPresenceRung before checking this off. 2026-09-18: if what remains is the thermal and battery step-down because "the app pins no battery/thermal native module", install one (expo-battery, and a thermal-state module for the React Native version in apps/oshun/mobile/package.json), record the versions, and finish the ladder; a missing module is work, not a blocker.
  • Add the Account → Preferences toggle (default off), per-mentor and per-setting preferences, revocable any time, stored under the consented Tara personalization scope; entitlement-gate voiced/embodied sits per generation tiers. 2026-07-06: mobile Account → Preferences carries the "Mentor presence" toggle (default off, revocable) in app/(tabs)/profile.tsx, persisted through mobileExperienceSettings.ts (mentorPresence: false default, coerced on hydrate); the web player persists the toggle plus per-mentor (oshun.tara.mentor-presence.mentor) and per-setting (oshun.tara.mentor-presence.setting) preferences, validated against the mentor's permitted sets. Entitlement gate shipped at the BFF: free-tier render requests 403 insufficient_tier via the same authoritative parseEntitlementsFromRequest resolution as every other generation surface (mobile per-mentor selection UI defaults to the first cast mentor for now — the picker rides the web prefs).

36.6 Governance gates#

  • Extend the Lilith contemplative tone rubric with a choreography axis (no startle, no spectacle, walking-pace or slower) and gate arrival/settle choreography on it, alongside the existing script-tone publish gate. 2026-07-06: choreography-tone-gate.ts (libs/oshun/domain-tara/src/mentor-presence/) — reviewer lilith-contemplative-tone-rubric/choreography-axis scoring three axes from the contracts' real numbers: no-startle (entry onset vs the 2 s slow-breath floor), no-spectacle (sensory load × whether the setting structurally carries the effect — an emergence in a waterless garden scores 0), and pace-walking-or-slower (implied traversal speed over canonical entry paths vs the 1.4 m/s ceiling; walk-in is 0.5 m/s by construction). Wired at render time in performance-render.ts — a failing review 422s choreography_tone_rejected before any pixels render. 6 gate tests; hurried/sudden/misplaced choreography all fail.
  • Wire crisis collapse: on a crisis signal the presence layer drops to the static safe frame within one frame hold and the Lilith crisis handoff owns the screen; high-distress moods (agitated, grieving, fearful) suppress theatrical arrivals structurally. 2026-07-06: three layers — (1) the BFF render route consults the REAL crisis-frame runtime (isCrisisFrameActiveForUser) and 409s crisis_frame_active while a frame is active, so no presence media exists to attach and the player stays on the static safe frame (tested against a seeded durable crisis frame); (2) the §36.3 choreography machine's crisis-signal input collapses to the crisis-collapse behavior immediately (breath idle stops, session tracked underneath, guidance never auto-resumes); (3) high-distress arrival suppression is structural in the §36.1 contracts (permittedAtHighDistress only on already-present, enforced by the score schema and resolveMentorArrival, both tested).
  • Route every mentor through the Isis release gate with §14 rehearsal fixtures, multi-party signoff, and a tested rollback plan; measure disclosure visibility in-player against the customer floors (≥ 30s, ≥ 0.85 fraction, ≥ 14px, ≥ 4.5:1, ≤ 0.05 occlusion) plus spoken synthesis disclosure on first voiced use.
    • 2026-07-06 progress: the routing machinery is shipped and FAIL-CLOSED — mentor-presence-release.ts (@oshun/persona-registry) evaluates every cast member through the §14 stack (all 8 rehearsal fixture categories with captured-evidence floors, the real evaluateAvatarReleaseGate at the strictest tara-teacher class, the 6 required reviewer-role signoffs, and a written+exercised rollback plan), and the capability endpoint reports the honest not-ready verdict with blocker counts on every read. The in-player disclosure now meets the customer floors: 14 px at ink-2 (~10:1 contrast, computed with real WCAG math in measureMentorDisclosureAgainstCustomerFloor + wcagContrastRatio), rendered the whole time media shows, never occluded; mobile disclosure raised to 14 px light-ink on the dark card. Voice profiles REQUIRE the spoken synthesis disclosure (requireSpokenSynthesisDisclosure: true, validator-enforced). Remaining before checking off: run the actual rehearsals (real fixture evidence), capture avatar-gate measurements from rendered takes, collect the six human signoffs, and write+exercise the rollback plan — human/process gates that cannot be fabricated in-repo. Board tag 2026-09-18: the routing is shipped and fails closed; what remains is the multi-party sign-off per mentor. blocked:human

36.7 Accessibility and quality evals#

  • Implement reduced-motion presence (forced already-present, luminance breath instead of body motion, no camera drift) and screen-reader scene descriptions with state-change announcements at arrival, settle, and parting. 2026-07-06: forced already-present is structural (§36.1) and honored end-to-end (web layer forces it in the requested score; tested). The render pipeline now has a REAL reduced-motion variant (performance-render.ts): ONE spatial composition — no band drift, no camera motion — with each frame's RGB scaled on the resting-breath raised-cosine curve (±3%, scaleFrameLuminance), adjacent-frame luminance swing measured with the real analyzer and gated under the WCAG 2.3.1 general-flash threshold; deterministic and distinct from the full-motion render (both tested). Screen readers get the scene description as the media alt text / accessibilityLabel ("A flat lake under heavy mist; your mentor Sela Stillwater is seated, breathing slowly…") and an aria-live status line announcing state changes through the choreography behavior table (arriving / settling / resting / bowing).
  • Enforce photosensitivity bounds on materialize (luminance-ramp cap, flicker/color-jump ceilings from the scene eval thresholds) and sensory-load matching (low-sensory practice never resolves to a moderate arrival). 2026-07-06: materialize carries the ≥ 8 s condense floor in its contract (no flash is representable); EVERY render passes the WCAG 2.3.1 general-flash gate (seizureSafe from per-frame luminance analysis; the reduced-motion path additionally measures its own swing explicitly); sensory-load matching is structural in the score schema AND resolveMentorArrival (low-sensory practice → already-present), both tested. Color-jump ceilings beyond the flash gate remain the Contemplative Arc runtime's per-template eval thresholds when presence composes with full Living Scenes.
  • Ship eval fixtures gating release: arrival calm, posture correctness per lineage, breath-sync tolerance against the cadence clock, lip-sync during guidance at LIPSYNC_ALIGNMENT_DEFAULT_THRESHOLD = 0.85 with hard-fail axes ≥ 0.9, and caption-occlusion measurement ≤ 0.05. 2026-07-06: eval-fixtures.ts (libs/oshun/domain-tara/src/mentor-presence/) — runMentorPresenceEvalFixtures() runs arrival-calm (23-case sweep of every arrival × every setting that structurally carries it through the choreography tone gate) and breath-sync-tolerance (99 cases: every counted cadence + the resting breath × all 9 legal playback-rate steps, each phase boundary within ±50 ms of the contract clock). Lip-sync gates in the release dossier via the real avatar release gate (tara-teacher class holds 0.88 ≥ the 0.85 default; the registry's lip-sync eval hard-fails axes below 0.9); posture-per-lineage gates in the cast tests (bhakti ⊆ kneeling/seiza, pranayama includes standing, secular includes chair-seated); caption occlusion ≤ 0.05 gates in the web disclosure measurement. All fixtures green.

36.8 Analytics and honesty of the seam#

  • Instrument presence sessions (opt-in rate, fallback-rung distribution, completion delta vs. artwork sits, crisis-collapse count) under the standard analytics consent scope. 2026-07-06: mentor-presence/analytics.ts (BFF) + POST /v1/tara/mentor-presence/events + GET /v1/tara/mentor-presence/analytics. The store computes exactly the named measures (opt-in rate from toggle events; per-rung fallback distribution with bounded-cardinality reasons; completion delta = presence completion rate − artwork completion rate from sit-started/completed pairs; crisis-collapse count). Recording is gated on the customer's standard analytics consent flow — a revoked flow records NOTHING and the response says recorded: false / analytics_consent_not_granted (tested both ways); the web layer emits opt-in/opt-out, presence-attached, and fallback-engaged events fire-and-forget.
  • Keep the seam honest: while the live-embodiment path is unshipped, the player must report presence capability as unavailable (fail-loud/configured: false seam) rather than simulating it; no placeholder mentor renders behind the toggle. 2026-07-06: the capability endpoint reports liveEmbodiment: { configured: false, reason: 'live_embodiment_not_implemented' } and the honest release-gate verdict on every read; the players render REAL authored performances from the governed pipeline or step down to the artwork/typographic rung with the reason held — every failure path lands on an honest state (unavailable + reason on web; artwork rung on mobile), never a simulated mentor. Route + layer tests assert both.

Adversarial Verification (run before any signoff)#

Per CLAUDE.md "Adversarial Verification Pass" — every checked item must survive this scan with zero actionable hits in the changed code:

bash
grep -rn -i \
  -e "in production" -e "in a full implementation" -e "would require" \
  -e "for demo" -e "simple approach" -e "simulated" -e "simulate" \
  -e "placeholder" -e "not yet implemented" -e "TODO" -e "FIXME" \
  -e "HACK" -e "dummy" -e "hardcoded" -e "hard-coded" -e "fake" \
  --include="*.ts" --include="*.tsx" --include="*.py" --include="*.rs" \
  --exclude-dir=node_modules --exclude-dir=dist \
  <changed-paths>

Any hit must be either resolved or annotated // stub:legitimate <reason> on the same line — never used to bypass tracked stubs.

Also scan for silent stubs with no telltale comment:

  • Math.random() in deterministic functions.
  • catch blocks returning fabricated success.
  • Functions returning fixed literals regardless of input.
  • Functions logging "would …" instead of doing it.
  • Functions ignoring most of their parameters; _-prefixed parameters that should be used.
  • Public methods delegating to a private stub.
  • Tests that assert only truthiness or wide ranges.
  • Mock/simulated runtimes where real ones belong.

The four signoff conditions — all required:

  1. Mandatory grep returns zero actionable hits.
  2. Every public function in the change has been read.
  3. Every private function delegated to from a public function has been read.
  4. The silent-stub pattern scan has been performed.