Intelligence Engine

System Identity

ARC and Katalyst occupy two distinct layers of a single system. Understanding the boundary between them is essential to understanding why the architecture works.

ARC: The Product Layer

ARC is the user-facing product. It exists to translate user goals into actionable decisions, reduce friction to action, and guide users through progressive behavior change. ARC does not contain intelligence logic. It consumes intelligence from the engine below it and renders it across surfaces (mobile, web, coaching dashboards).

Katalyst: The Engine Layer

Katalyst is the singular intelligence engine within ARC. It processes behavioral data, diagnoses user state, prioritizes domains, and generates structured action options. Every coaching message, every escalation decision, every plan adjustment traces back to Katalyst. There is no second engine, no bypass path, no alternative intelligence source.

System Hierarchy

The system follows a strict five-level structural hierarchy. Each level has a precise definition, and nothing exists outside this tree.

• System: ARC (the Intelligence-Guided Behavior System). The top level.
• Engine: Katalyst (the singular intelligence engine). There is exactly one.
• Module: A functional grouping of related layers within the engine (e.g., Data Intelligence, Coaching Intelligence).
• Layer: A distinct intelligence capability with defined inputs, logic, and outputs. Each layer file carries a *Layer.ts suffix by convention.
• Logic Component: A supporting piece of logic that serves a layer. Named descriptively without the "Layer" suffix.

This hierarchy is not aspirational. It is enforced at build time: a CI (Continuous Integration) gate validates parity between the layer registry documentation and the actual source files in the codebase. If documentation and code disagree, the pull request fails.

Engine Structure

Katalyst contains 38 registered layers and 52 logic components, organized across five modules.

Governance (Cross-System, 2 Layers)

Governance is not owned by any module. It operates as a cross-system authority ensuring correct surface behavior, valid data entry, and consistent system expression. All modules must comply with Governance rules before any output reaches the user. Governance includes the Surface Layer (controlling what kind of language appears on each coaching surface) and Input Validation (sanitizing data at pipeline boundaries).

Data Intelligence (7 Layers)

Captures and computes user state. This module includes the Arc Score (a 0–100 composite from four behavioral dimensions with phase-adaptive weighting), the Athletic Development Index (Knowledge 40%, Skill 40%, Behavior 20%), an Athletic Performance score evaluated against sport-position demands across 32 attributes, physiology calculations, deficit prediction using independent physiology/intake and scale-weight paths, and readiness assessment with five profile-specific weightings.

Diagnostic Intelligence (9 Layers)

Identifies gaps and interprets behavior. The Signal Layer performs persistent signal detection with severity scoring and temporal progression. Gap Classification detects multiple cause types (seven gap categories) and selects the primary gap. The Environment Signal Layer distinguishes "user can't" from "user won't" by analyzing behavioral pattern shifts, a critical distinction that determines whether the system responds with accommodation or re-engagement. The Outcome Stall Detection Layer catches a specific failure mode: high consistency paired with flat outcomes, triggering a messaging pivot rather than continuing to praise compliance that isn't producing results.

Coaching Intelligence (12 Layers, 30 Logic Components)

The largest module. Transforms diagnostics into actionable decisions. The MPC Pipeline selects which domain deserves system focus. The Tiered Action Layer generates Full, Modified, and Minimum Viable action options. Coaching Orchestration selects a primary insight plus up to two supporting insights with confidence thresholds. The Swap Equivalency Layer provides constrained, reason-aware substitution for planned items, with 19 supporting logic components covering domain-specific equivalency strategies, tradeoff dimensions, and adherence impact tracking.

Behavior Intelligence (8 Layers)

Executes behavior progression and reinforcement. The Bootstrap Layer manages the four-state onboarding progression (Onboarding, Exploring, Emerging, Guided) where transitions are behavior-driven, not time-based. The Re-Entry Layer handles gap detection and decay suppression when users return after absence. The Weekly Loop Layer orchestrates the Plan, Execute, Review, Adjust cycle. The Behavioral Feedback Layer provides continuous proof of progress with always-positive framing, covering Weekly Wins, Behavioral Trend Narratives, and Post-Log Coaching Reinforcement.

Core Behavioral Progression

The entire system exists to move users through a single progression:

Non-Action → Action → Consistency → Performance

This is the system's objective function. It is not a suggestion or a design principle; it is a validation rule. Every layer in the engine must declare which transition or transitions it supports. If a layer cannot map to at least one transition, it does not belong in the system. A layer that fails this validation must not be implemented.

The validation table in the Layer Registry makes this concrete. Each layer declares Primary or Secondary support for each transition:

• Bootstrap and Re-Entry are Primary for Non-Action to Action. They exist to get users moving.
• Weekly Loop and Behavioral Feedback are Primary for Action to Consistency. They exist to sustain engagement.
• Arc Score, Athletic Performance, and Gap Classification are Primary for Consistency to Performance. They exist to refine outcomes.
• Governance layers (Surface, Input Validation) support all three transitions because they enforce system-wide correctness.

The Behavior First Rule

The system's most consequential design constraint:

If a feature improves intelligence but reduces action, reject it.

This rule exists because sophisticated analysis that users don't act on is worthless. A system that produces brilliant diagnostics but overwhelms users into inaction has failed. The Behavior First Rule forces every design decision through a single question: will the user act? If the answer is no (or even "maybe, but with more friction") the feature is rejected regardless of its analytical merit.

Decision Hierarchy

When design decisions conflict, the system resolves them through a strict priority order:

1. Behavior: Will the user act?
2. Clarity: Do they understand?
3. Relevance: Is it correct?
4. Optimization: Is it ideal?

This means the system will sacrifice analytical precision (Relevance) to preserve user understanding (Clarity), and sacrifice both to preserve the user's likelihood of acting (Behavior). Optimization (getting the recommendation exactly right) is the lowest priority. A slightly imprecise recommendation that the user follows is more valuable than a perfect recommendation that sits unread.

Deterministic Decisions

This is the engine's hardest constraint and its most distinctive property.

Every input combination produces exactly one classification. Every classification produces exactly one decision path. Every decision path produces exactly one output or an explicit null. All decisions are comparisons against defined thresholds with explicit boundary assignments. No randomness exists in the decision process. Reproducing a decision requires the same complete inputs, the relevant history and state, and the same rule version. Presentation is separate from the decision: some coaching titles rotate by day, so the same decision can be worded differently on different days.

This is achieved through rigorous threshold design:

• No overlapping ranges in any classification
• Boundary values are assigned to exactly one category (inclusive and exclusive bounds are explicit for every range)
• Every possible numeric value for every signal maps to exactly one classification
• Unresolved borderline cases default to Exploration (the system defers intervention when the behavioral signal is ambiguous)

The deterministic decision process means a coaching decision can be traced. Given a user's behavioral signals, you can trace the exact path through classification, trend modifiers, decision gates, execution constraints, and output quality to arrive at the same coaching action the system produced. There is no "it depends on the model" or "it varies by run" in the decision itself.

Five-Tier Behavioral Law Hierarchy

The Katalyst Behavioral Laws define the decision rules governing how the engine classifies behavior and produces coaching actions. They operate at the engine layer, above all modules, layers, and logic components. The laws are organized into five tiers that execute in strict sequential order. Each tier receives the output of the prior tier as input. No tier may bypass or override a higher tier's decision.

Tier 1: Classification

Determines what the system is evaluating. Runs first and can short-circuit all lower tiers.

Classification consumes five core signals: Adjustment Rate (proportion of plan items replaced), Adjusted Completion Rate (follow-through on adjusted items), Skip Count (disengagement without adaptation), Adjustment Fidelity (substitution quality), and Raw Adherence (overall plan compliance).

These signals resolve to one of three intent classifications:

• Exploration: The user is actively substituting and completing. High adjustment rate plus high adjusted completion plus low skips. The system preserves structure and does not reduce the plan. This classification sets a bypass flag that skips escalation entirely.
• Friction: The user is struggling. Low adjusted completion, high skip count, or very low substitution quality. The system delegates to the Decision Gates for confirmation and potential escalation.
• Engagement Drift: The user is executing the plan as-is with minimal adjustment and no skips. High adherence, stable trend. No required system action; the user is on track.

The classification flow includes a six-step algorithm with explicit shortcut paths, a computed exploration score with weighted components, borderline resolution rules, and a stability lock that prevents classification from oscillating between cycles when the score lands in the borderline zone. Users with fewer than three weeks of data receive new-user protection: borderline scores resolve to Exploration, giving the system more time to observe before intervening.

Tier 2: Trend Modifiers

Adjusts thresholds and timing for lower tiers based on trajectory. Trend Modifiers do not produce actions; they adjust parameters only.

The trend is calculated from the difference between current week adherence and the average of the two prior weeks. It classifies into five ranges: Declining Rapid, Declining Gradual, Stable, Improving Moderate, and Improving Strong. Each range modifies the confirmation window that Tier 3 uses to decide when to act. Declining Rapid compresses confirmation to one week. Improving Strong with adherence at or above 60% extends confirmation and blocks escalation entirely.

Tier 3: Decision Gates

Controls when and at what level the system acts. Contains three gates: Confirmation, Escalation, and De-escalation.

The Confirmation Gate prevents premature intervention. Standard friction requires two weeks of confirmation before the system acts. Acute disruption (adherence drop of 40+ points or effective adherence below 20%) bypasses confirmation entirely for an immediate Level 1 response, but never higher. The system distinguishes between momentary difficulty and persistent struggle.

The Escalation Gate defines four intervention levels: None (no friction), Tune (small parameter adjustments), Restructure (simplify or rebalance plan structure), and Reset (reduce to minimum viable plan). Levels cannot be skipped. Each escalation requires both signal severity and persistence.

The De-escalation Gate manages four system states: Escalating, Stable at Level, De-escalating, and Fully Exited. The system is always in exactly one state. De-escalation has explicit thresholds for each transition (Level 3 to 2 requires 50%+ adherence; Level 1 to 0 requires 75%+ adherence plus minor-or-less friction). During de-escalation, every level transition output must acknowledge improvement, describe what structure is being restored, and note what remains simplified. Transitional guidance must not include new restrictions, regression warnings, or internal metrics.

Tier 4: Execution Constraints

Shapes the output within the decision made by Tier 3. The system must output exactly one primary action and up to two supporting actions. Supporting actions must reinforce the primary action; they must not introduce unrelated priorities.

Key constraints include: completion of adjusted actions is weighted higher than strict adherence to the original plan (the system recognizes that adapting and completing is compliance); the system addresses only the highest-impact constraint per cycle (multiple unrelated directives are prohibited); actions must resolve the identified constraint with the smallest necessary change; and adjustments must preserve the intent of the original plan.

Tier 5: Output Quality

Validates output before delivery. This tier determines whether the composed output is actually sent to the user or suppressed.

Suppression is permitted only when the system has confirmed no action is required: the system state is Fully Exited, escalation level is zero, and no de-escalation transition is in progress. Suppression during escalation, during a stable hold, or during de-escalation is prohibited.

Non-Repetition prevents the system from repeating the same directive without new behavioral justification. Escalation-level changes and de-escalation transitions are structurally distinct and are not treated as repetition.

Coaching Clarity requires all actions to be specific, measurable, and executable. Vague language, passive suggestions, and non-actionable statements are prohibited.

Tone Adjustment modifies language without changing decisions. It can soften framing for improving users or reframe severity ("focused sessions" rather than "reduced sessions"), but it cannot remove actions, downgrade escalation levels, or suppress output. Tone receives the composed output from Tier 4 and returns a version with identical structure: same number of actions, same domains.

System Guardrails

Five constraints that are absolute. They cannot be overridden by any tier, any module, or any product decision.

• No Overwhelm. One priority at a time. The system never presents multiple unrelated action areas simultaneously.
• No Silence. The system always provides a next step. A user should never face a screen with no guidance and no path forward.
• No Punishment. No negative reinforcement, ever. Missed targets are reframed as data, not failure.
• No Hidden Logic. Every coaching action includes What, Why, and Impact. The system's reasoning must be visible to the user.
• Behavior First. If a feature improves intelligence but reduces action, reject it. This is the supreme constraint.

Operating Model

The system operates on three temporal layers, each with a distinct role.

Weekly Loop (Primary)

The core cycle: Plan, Execute, Review, Adjust. This is the heartbeat of the system. Most coaching decisions, escalation checks, and behavioral feedback are anchored to the weekly loop.

Daily Execution Layer

Supports plan execution and tracks adherence. The daily layer does not override the weekly plan; it serves it. Post-log coaching reinforcement and immediate feedback operate here.

Multi-Week Layer

Tracks trends, adjusts expectations, and governs progression. Trend calculations, de-escalation thresholds, and arc lifecycle decisions operate at this timescale.

Action Delivery Model

How the system translates intelligence into what the user actually sees.

Domain Prioritization

One primary domain per cycle, selected via the MPC Pipeline. The system does not spread attention across all domains simultaneously. It focuses.

Soft Focus Model

The primary domain receives actionable guidance. Secondary domains remain visible and informational. Inactive domains are hidden entirely. This prevents overwhelm while preserving user awareness of their full picture.

Tiered Action Model

Each primary domain generates three tiers of action: Full (the ideal recommendation), Modified (an adapted version), and Minimum Viable (the smallest meaningful step). The default is Minimum Viable. The system proposes; the user commits. Adherence is measured against the user's chosen commitment, not the system's ideal recommendation.

Behavior Principles

• Success equals forward action. Any movement in the right direction counts. The system does not define success as hitting a specific target.
• Momentum over accuracy in early stages. When a user is building the habit of engagement, getting them to act matters more than getting the recommendation exactly right. Precision increases as the user progresses.
• Actions must match user capability. The system calibrates effort to what the user can actually do, not what the program ideally prescribes.
• Progress must be visible and cumulative. The user must always be able to see that they are moving forward and that past effort counts.

State-Based Systems

Bootstrapping

New users progress through four states: Onboarding, Exploring, Emerging, and Guided. Transitions between states are behavior-driven, not time-based. A user who engages actively will move through bootstrapping faster than a user who logs intermittently. The system adapts to the user, not the calendar.

Re-Entry

When a user returns after a gap, the Re-Entry system removes friction, suppresses negative signals, and defaults to Minimum Viable actions. There is no "you've been gone for three weeks" guilt message. The system treats return as a positive signal and makes it as easy as possible to resume.

Tone Progression

The system's communication tone progresses through four states: Encourage, Reinforce, Clarify, and Illuminate. Tone is governed by ignore count, gap severity, goal proximity, and user response history. As the user demonstrates greater engagement and capability, the system shifts from encouragement to deeper insight.

The Lineage Rule

Every component in the system must trace to two things: the behavioral progression (Non-Action to Action to Consistency to Performance) and at least one Intelligence Layer.

If a component cannot establish this lineage, it does not belong in ARC. This rule prevents architectural drift, the gradual accumulation of features that seem useful but do not serve the system's core purpose. The Lineage Rule is a deletion criterion: it tells you not just what to build, but what to remove.

System Objective Validation

The Lineage Rule is enforced through a formal validation table in the Layer Registry. Every layer must declare its support for at least one behavioral transition. The table records both Primary (the layer exists for this transition) and Secondary (the layer contributes to this transition) designations.

This is not a documentation exercise. It is a design-time validation rule with CI enforcement. If a new layer is added to the registry without declaring at least one Primary transition, the system considers it invalid.

Examples from the validation table:

• The Environment Signal Layer is Primary for Non-Action to Action and nothing else. Its sole purpose is to distinguish "can't" from "won't" so the system can remove barriers for users who aren't acting.
• The MPC Pipeline is Primary for both Action to Consistency and Consistency to Performance. Domain prioritization matters at both stages.
• The Tiered Action Layer is Primary for Non-Action to Action (getting users to do something) and Secondary for Action to Consistency (keeping them doing it), but has no role in the Performance transition.
• The Tone Layer is Secondary for Non-Action to Action and Primary for Action to Consistency. Encouragement matters most when building the habit.

CI-Enforced Documentation Parity

The Layer Registry is not a standalone document; it is a contract between documentation and source code. A CI script validates parity between the registry and the actual layer files in the codebase. If a layer exists in the registry but not in code, or in code but not in the registry, the pull request fails.

The parity check detects mismatches between registered layers and their corresponding source files. Descriptions of behavior still require review against the implementation.

Intelligence Transparency

Every coaching action the system produces must include three elements: What (the specific action), Why (the behavioral reasoning), and Impact (what the action is expected to change). This is not a UX guideline; it is a system constraint enforced by the Governance module. Coaching output that lacks any of these three elements is non-compliant.

This transparency requirement serves two purposes. For the user, it builds trust. The system never asks you to do something without explaining its reasoning. For the development team, it forces the engine to produce structured output that can be validated and audited. If the engine cannot articulate why it is recommending an action, the recommendation is suspect.

Coherence Constraints

Two final constraints protect the system from a class of bugs that deterministic logic alone cannot prevent.

Coaching coherence: A rendered directive's domain must never contradict the engine's computed primary focus. If the MPC Pipeline says the primary gap is in training, the coaching surface cannot render nutrition guidance as the primary action. A genuine disagreement between the tier output and the MPC focus is treated as a signal bug to surface, not output to render. The system fails explicitly rather than rendering contradictory guidance.

No phantom frames: A directive must not reference a construct the user has not entered ("your current cycle" when no cycle exists) or synthesize a gap from default targets absent a real plan. Coaching premises must be true before they are spoken. This constraint was born from production incidents where the engine generated plausible-sounding guidance built on assumptions that did not hold for the specific user.

Summary

The Katalyst Intelligence Engine is a deterministic, five-tier decision pipeline with 38 registered layers, 52 logic components, and formal validation rules that ensure every component serves the behavioral progression. It classifies user behavior, modifies thresholds based on trajectory, gates interventions through confirmation and escalation, constrains output to the smallest effective change, and validates quality before delivery. Decisions are reproducible from the same inputs, history, and rule version.

The system's design reflects a specific philosophical position: intelligence without action is worthless. Analytical sophistication that reduces the user's likelihood of acting is rejected, full stop. Every architectural decision (from the five-tier pipeline to the Lineage Rule to the CI-enforced registry parity) exists to ensure that the system's intelligence serves behavior, not the other way around.