This document consolidates and supersedes all prior Wellness Notebook proposals, revisions, and Pitchfork assessments. It serves as the authoritative build baseline for the first implementation.
Sources incorporated:
Wellness Notebook is a local-first behavioral wellness client for the Pancakes / Pitchfork ecosystem.
The product is inspired by late-2000s wellness software such as Nintendo DS wellness applications that emphasized:
The system intentionally rejects:
The core product thesis:
A lightweight wellness system consistently used is more valuable than a precise system abandoned.
Wellness Notebook is not:
It is:
Wellness Notebook is not the ecosystem source of truth.
The architecture is:
private client records
→ node identity + permission checks
→ minimal Pitchfork events
→ capped settlement
→ derived symbolic projections
→ client-specific presentation
Pitchfork accounts.
Clients interpret.
Nodes govern.
Identity authorizes.
Pancakes humanizes.
The application should feel like:
It should not feel like:
Every session should feel:
The product must avoid:
The system minimizes:
This is a first-class engineering and QA requirement.
The system intentionally favors:
The MVP avoids:
Approved coaching behavior:
Approved examples:
Prohibited examples:
The node governs:
Pitchfork:
Pitchfork should generally receive:
Pitchfork should not receive:
Wellness Notebook:
The Daily Session is the central interaction loop.
It includes:
Important separation:
DailySession = ordinary personal metadata
SensitiveReflection = sensitive local/private content
Mood and reflection text must never live directly on ordinary session records.
MVP movement tracking is:
Features:
Out of MVP:
Exact step counts remain client-private.
Pitchfork receives only:
Food tracking models:
behavioral balance
rather than:
nutritional optimization.
MVP food categories:
Meal types:
No:
Activity logging supports:
Quick mode:
light
moderate
intense
Detailed mode:
activity_family
duration_band
intensity
Examples:
The system intentionally validates ordinary movement as meaningful participation.
Challenges provide:
Approved categories:
movement
hydration
food_balance
mindfulness_general
rest_general
environment
routine
Sensitive challenge categories must never be projected into Pitchfork measures.
MVP coaching is:
Not allowed:
Primary architecture:
single local Pancakes node
→ local database
→ local users
→ local Pitchfork module
→ export/import
→ optional hosted deployment
Hosted deployment must not become the privileged architecture.
Redis may store:
Redis must never store:
Background jobs must pass IDs only.
Every record must include data_class.
Allowed values:
public
node_shared
household
group
personal
sensitive
regulated_high_risk
economic
cryptographic_secret
Examples:
Examples:
Out of MVP:
Allowed values:
private
local_client
node_local
household
guild
trusted_participants
public_symbolic
economic_settlement
MVP defaults:
private
local_client
Pitchfork-facing identity primitives:
actor_id
node_id
local_user_id may exist for Flask internals only.
Every projectable record must resolve to:
NodeRef
- node_id
- node_type
- policy_version
ActorRef
- actor_id
- node_id
- identity_claim_id
- assurance_level
DailySession
- id
- node_id
- actor_id
- local_user_id
- session_date
- completion_state
- data_class = personal
- permission_scope
- retention_policy_id
- retention_policy_version
- created_at
- updated_at
- deleted_at
SensitiveReflection
- id
- node_id
- actor_id
- session_id
- encrypted_body
- mood_label optional
- data_class = sensitive
- permission_scope
- retention_policy_id
- retention_policy_version
- encrypted_at
- export_inclusion_default = false
- last_sensitive_access_audit_id
- created_at
- updated_at
- deleted_at
Defaults:
MovementLog
- id
- node_id
- actor_id
- local_user_id
- session_id
- exact_step_count
- source_type = manual
- data_class = personal
- permission_scope = local_client
- pitchfork_permission_grant_id
- pitchfork_event_id
- pitchfork_idempotency_key
- pitchfork_event_status
- pitchfork_last_error_code
- pitchfork_last_attempt_at
- retention_policy_id
- retention_policy_version
- created_at
- updated_at
- deleted_at
FoodBalanceLog
- id
- node_id
- actor_id
- session_id
- meal_type
- food_category
- quantity_estimate
- data_class
- permission_scope
- pitchfork_permission_grant_id
- pitchfork_event_id
- pitchfork_idempotency_key
- pitchfork_event_status
- retention_policy_id
- retention_policy_version
- created_at
- updated_at
- deleted_at
Food records escalate to sensitive if they include:
MVP recommendation:
ActivityLog
- id
- node_id
- actor_id
- session_id
- activity_family
- duration_band
- intensity
- data_class
- permission_scope
- pitchfork_permission_grant_id
- pitchfork_event_id
- pitchfork_idempotency_key
- pitchfork_event_status
- retention_policy_id
- retention_policy_version
- created_at
- updated_at
- deleted_at
ChallengeAttempt
- id
- node_id
- actor_id
- session_id
- challenge_category
- completion_state
- data_class
- permission_scope
- pitchfork_permission_grant_id
- pitchfork_event_id
- pitchfork_idempotency_key
- pitchfork_event_status
- retention_policy_id
- retention_policy_version
- created_at
- updated_at
- deleted_at
Required fields:
retention_policy_id
retention_policy_version
deleted_at
Allowed MVP policy IDs:
user_controlled
sensitive_user_controlled
audit_minimal
backup_limited
node_policy
Future fields:
purged_at
projection_deleted_at
backup_delete_after
Soft-deleted records must not appear in:
Separate grants are required.
grant_private_participation
Allowed event types:
grant_sensitive_reflection_completion
Allowed event types:
Sensitive grants must:
Canonical flow:
private client record
→ permission grant lookup
→ EventRequest builder
→ PitchforkAdapter
→ record_event()
→ settlement persistence
→ audit hook
MVP supported types:
movement_logged
activity_logged
food_balance_logged
daily_session_completed
challenge_completed
reflection_completed
rest_logged
Pitchfork receives:
{
"movement_band": "light",
"step_band": "2500_4999"
}
Never:
{
"exact_steps": 4327
}
{
"meal_type": "lunch",
"balance_categories": ["fruits_vegetables", "protein"],
"quantity_estimate": "some"
}
{
"activity_family": "walking",
"duration_band": "10_29_minutes",
"intensity": "light"
}
{
"reflection_completed": true
}
No raw reflections.
Projection types must come from a registry.
Initial registry:
pitchfork_rpg_private
wellness_notebook_local_summary
nexus_private_summary
ambient_private_symbolic
MVP-active:
pitchfork_rpg_private
wellness_notebook_local_summary
Pitchfork settlement is authoritative.
Clients must not create uncapped reward systems.
Example:
daily_wellness_participation:
event_type: daily_session_completed
period: day
max_private_resource_grants: 1
Participation should yield:
baseline access
not:
optimization pressure
Allowed transitions:
not_submitted -> pending
pending -> accepted
pending -> rejected
pending -> retryable_error
pending -> permission_revoked
retryable_error -> pending
retryable_error -> rejected
permission_revoked -> pending only after new permission_grant_id
accepted -> terminal
rejected -> terminal unless manually reclassified
If Pitchfork write fails:
1. Preserve private record.
2. Persist failure state.
3. Retry safely if retryable.
4. Never shame the user.
Approved copy:
Your notebook entry was saved.
Avoid:
Your activity did not count.
Required:
Sensitive content must never appear in:
Audit required for:
Audit records must not contain raw sensitive payloads.
Exports are first-class features.
Pitchfork exports:
Client exports:
Sensitive exports should support encryption.
Never send to Pitchfork by default:
Never use Pitchfork for:
Release-blocking questions:
Required tests:
Before broader implementation:
MovementLog exact steps saved privately
→ EventRequest contains only step_band
→ permission grant checked
→ record_event called with idempotency key
→ settlement accepted
→ event_id/status persisted
→ exact steps absent from logs/Redis/Pitchfork payload
This becomes the template for all event builders.
Highest-risk module:
PitchforkAdapter / PitchforkEventBuilder
Responsibilities:
This module requires the highest test coverage.
1. Shared enums/constants
2. Projectable model fields
3. PitchforkAdapter
4. Movement EventRequest builder
5. Challenge EventRequest builder
6. Redaction/idempotency tests
7. End-to-end movement contract test
8. Expand to food/activity/session/reflection
Movement is the preferred first implementation because:
Wellness Notebook is:
a local-first Pancakes wellness client
with private behavioral records
that emits minimal, permissioned Pitchfork events
for capped symbolic settlement and private projections
without exposing raw intimate life data
while preserving psychologically safe daily participation.