Harmonic Completion Engine [AGPro Series]

Jun 1

Harmonic Completion Engine [AGPro Series]


🧠 Core Idea

Is this harmonic pattern completing cleanly enough to act on - and where is the risk?


📌 Overview / What It Does

The Harmonic Completion Engine detects XABCD harmonic structures - Gartley, Bat, Butterfly and Crab - directly from confirmed swing pivots, and turns each one into a structured read.

It does three things: it measures how cleanly a pattern's Fibonacci ratios complete inside its potential reversal zone (PRZ) and grades that on a 0-100 completion score; it frames an entry, a protective stop, two targets, a reward-to-risk figure and an invalidation level; and it reports a single, clear state so you always know where the setup stands.

It does not predict price, it does not place orders, and it does not claim that a completed pattern must reverse. It is an analytical and visualization layer for traders who already work with harmonic structure.


🎯 Purpose & Design Philosophy

Most harmonic tools stop at drawing the shape. They leave the trader to eyeball whether the ratios are clean, where the zone really is, and what the risk would be.

This engine was built to close that gap. It is for the discretionary trader who wants a disciplined, repeatable read on harmonic setups instead of forcing every rough shape into a trade. The design favours patience and clarity: one quality number, one state, one risk frame.


⚡ Why This Script Is Different

Most tools draw a harmonic pattern and stop there.

This script does not just draw a shape and leave you to judge it.

Instead, it scores the completion quality, frames risk and targets, and resolves the setup into a clear act / wait / invalid state - so a harmonic structure becomes a decision, not just a drawing.


⚙️ Methodology

1. Context detection - confirmed swing pivots are tracked into an alternating X-A-B-C-D structure.
2. Reference mapping - the engine measures the key retracement and projection ratios of the legs (notably the B and D Fibonacci relationships to the X-A leg).
3. Reaction evaluation - those measured ratios are compared against the tolerance bands for Gartley, Bat, Butterfly and Crab, producing a 0-100 completion score for the best-fitting pattern.
4. Visual output - the structure, the PRZ, a centered summary label, the trade levels and the decision panel are rendered.


🗺️ How To Read The Chart

- Polyline (X-A-B-C-D) - the detected harmonic structure.
- PRZ zone - the potential reversal zone around the completion point (D).
- Centered label - pattern name, completion score and current state, inside the zone.
- Colors - bullish, bearish, neutral and invalidated states each have their own tone.
- Panel - the full decision summary in one place.


🚦 Signals & States

- Forming -> no qualifying pattern is currently present.
- Watch -> a pattern has completed at moderate quality.
- Ready -> the completion score is at or above your Ready threshold.
- Invalid -> price has closed beyond X and the pattern is invalidated.

These describe structure. They are not buy or sell instructions.


🔔 Alerts Logic

Three alerts are available:
- Bullish pattern ready
- Bearish pattern ready
- Pattern invalidated

An alert is an attention marker that a condition has occurred. It is not a trade instruction and carries no guarantee.


🧩 Confluence Logic

A read is stronger when several things line up: a high completion score, a clean PRZ, and alignment with your own higher-timeframe bias or structure. Treat confluence as context that raises or lowers your conviction - not as confirmation of an outcome.


📊 When To Use

- Reactive, ranging or corrective phases where harmonic structure tends to form.
- Works on any timeframe; the 1H to Daily range tends to produce the cleanest harmonic structures and the most readable zones.


⚠️ When NOT To Use

- Thin liquidity, extreme volatility, or news-driven gaps, where swing pivots become unreliable.
- Very noisy, fast chop where structure is not well defined.


🎛️ Key Inputs

- Pivot Length - swing sensitivity; higher values produce larger, fewer patterns.
- Ratio Tolerance - how far measured ratios may deviate from the ideal before a pattern is rejected.
- Minimum / Ready Score - the quality thresholds for recording a pattern and for treating it as Ready.
- Stop Buffer / PRZ Width / Targets - the risk-framing controls.
- Calculation Window - how many recent bars the engine processes (lower is faster on long histories; the visible setup is unaffected).
- Display - theme, panel location, font size, and show / hide toggles.


🖥️ Interface & Visual Design

A single merged header panel presents the decision summary with a clear visual hierarchy and a premium palette. Label density is kept moderate so the chart stays readable at a glance, and the panel can be shown or hidden, repositioned and resized.


🧪 Practical Usage Workflow

1. Read the panel - pattern, completion score, state.
2. Check the PRZ and the X-A-B-C-D structure.
3. Evaluate how price reacts at the zone.
4. Confirm against your own context and plan before acting.


🔍 Interpretation Guidelines

Treat the completion score as a quality gauge, not a probability of success. A higher score means cleaner geometry, not a guaranteed reversal. The engine organises information; the decision remains yours.


🚫 What This Script Is NOT

- It is not a prediction engine.
- It is not financial advice.
- It is not an automated trading system.
- It does not produce guaranteed signals.


⚠️ Limitations & Transparency

Patterns are confirmed from completed swing pivots, so a structure appears with a lag equal to the pivot length. Once drawn, a pattern's points do not change; however, the engine displays the most recent qualifying pattern and will switch to a newer one as it forms. Timeframe and volatility affect how patterns appear, and harmonic completion never guarantees a reversal.


🧠 Market Context Notes

Harmonic zones mark areas of potential reaction. They are best read alongside broader structure, trend and liquidity rather than in isolation.


🔐 Non-Promise Statement

There are no guarantees and no certainty here. Any outcome depends on market conditions and on your own decisions and risk management.


📉 Risk Disclosure

Trading involves substantial risk of loss and is not suitable for everyone. This script is provided for educational and analytical purposes only and does not constitute financial advice or a recommendation to buy or sell any asset. You remain solely responsible for your own decisions.


📚 Educational Note

Use this engine to study how harmonic structure forms, completes and invalidates over time. The goal is to build a more disciplined, repeatable way of reading setups.

Jun 9

Release Notes

UPDATE NOTES - 2.0

This update focuses on decision depth: turning a single ratio score into a
four-factor Quality score, adding a full setup lifecycle, and reporting how past
setups actually resolved.

The core purpose of the script remains unchanged. It still auto-detects Gartley,
Bat, Butterfly and Crab XABCD structures from swing pivots and frames entry, stop
and targets. This release deepens HOW each completion is scored and tracked, and
fixes how a setup is followed once it completes.

This script continues to function as an analytical and visualization tool. It does
not attempt to predict price direction or provide guaranteed outcomes.


------------------------
What Changed
------------------------

- New four-factor Quality score (0-100)
The single ratio-precision number has been replaced by a transparent composite. The
panel now shows each factor on its own line so the score is auditable: Ratio
(Fibonacci fit), Structure (BC retracement and CD/AB symmetry), Reaction (the actual
rejection at point D), and Trend (premium / discount location of D in the range).

- Full setup lifecycle
A setup is now tracked from Ready through Triggered, T1 Hit, T2 Hit, Stopped and
Expired. The State line always reflects where the setup currently stands, so a
completed or stopped setup is never shown as if it were still actionable.

- Outcome statistics
A new statistics block reports how previous completed setups resolved within the
window: the share that reached Target 1 and Target 2, with the sample size (n).
These are measured from chart history, not assumed.

- Corrected extension-pattern handling
The previous structural-break check could mark Butterfly and Crab patterns, whose D
extends beyond X, as broken the moment they completed. Failure is now defined solely
by the ATR-based stop beyond D, which applies correctly to all four pattern types.

- Setup expiry
A Ready setup that neither triggers nor invalidates within a configurable number of
bars is now marked Expired, keeping the panel honest on quiet structure.

- Reward:Risk quality color
The Reward:Risk value is now colored by quality (red below 1R, amber 1-2R, green
above 2R), so the trade-off is readable at a glance.


------------------------
Visual Improvements
------------------------

- Improved chart readability by muting the pattern polyline, point D and the PRZ
zone once a setup reaches a terminal state, so live and finished setups are visually
distinct.

- Reduced visual clutter by drawing entry, stop and target lines only while the
setup is still live, not after it has resolved.

- Refined visual hierarchy so the active PRZ zone and its centered state label carry
the current lifecycle stage clearly.

- Adjusted target line coloring to follow the setup direction for clearer reading.


------------------------
Interface & Usability
------------------------

- Restructured the panel into four readable blocks: Verdict, Quality Breakdown, Plan
and Outcome Statistics, separated by divider rows for clearer information flow.

- Added an Action line that states the current next step (watch the PRZ, follow
through, trail after T1, complete, or expired).

- Reorganized inputs with a Setup Expiry control and a Location Lookback for the
Trend factor.

- Enhanced overall user experience while keeping panel theme, location and font size
fully adjustable, with the panel shown by default.


------------------------
Behavior Notes
------------------------

This update changes how the Quality number is calculated, expanding it from one
factor to four, and adds lifecycle tracking and outcome statistics. The underlying
pivot detection and pattern matching are unchanged.

The goal is to improve clarity, depth and usability, not to introduce predictive
behavior. The statistics describe how past setups resolved within the visible window
and are not forecasts.

Users should continue to interpret outputs as context, now with a more detailed and
auditable readout.


------------------------
Limitations Reminder
------------------------

The script remains a rule-based analytical tool.

Market conditions such as volatility, liquidity and timeframe differences may affect
how patterns, scores and statistics appear, and small samples should be read with
care.

Outputs should always be interpreted within broader market context.


------------------------
Risk Reminder
------------------------

This script is for educational and analytical purposes only.

It does not provide financial advice or guaranteed trading outcomes.

Users remain responsible for their own decisions.

Jul 19

Release Notes

🔧 UPDATE NOTES - 2.0.1

This update focuses on D-point calculation alignment, lifecycle chronology, outcome-statistics integrity, interface clarity, and chart readability.

The core purpose of the script remains unchanged. Harmonic Completion Engine still detects Gartley, Bat, Butterfly, and Crab XABCD structures from confirmed swing pivots; grades each completion through Ratio, Structure, Reaction, and Trend factors; maps the active PRZ; and follows the setup through its established lifecycle.

This release corrects how existing geometry, risk references, and historical outcomes are measured. It does not add prediction, automated execution, or guaranteed outcomes.


------------------------
What Changed
------------------------

• D-bar calculation alignment
ATR, PRZ width, stop distance, Reaction normalization, and premium/discount location are now aligned to the actual confirmed D pivot bar. V2.0 used values from the later pivot-confirmation bar, which could shift the risk frame and factor scores away from the pattern's completion point.

• Confirmed pivot ingestion
New pivot events are committed only after the chart bar closes. A developing real-time bar can no longer create a persistent pattern or Ready alert before its pivot confirmation is final.

• Deterministic outside-pivot handling
If one bar qualifies as both a pivot high and pivot low, the engine accepts only the side that preserves the alternating XABCD stream. Without prior stream history, it keeps the larger confirmed swing. This prevents two opposite pivots from occupying the same bar.

• Target-order safety
The nearer user target is always treated as Target 1 and the farther target as Target 2, even if the two retracement inputs are entered in reverse order.

• Entry-bar isolation
Lifecycle and outcome evaluation now begins on the bar after a pattern is confirmed. High/low movement that occurred before the pattern became observable can no longer resolve that new setup immediately.

• Conservative same-bar precedence
When a later OHLC bar contains both a stop and a target, the stop receives precedence because bar data cannot prove which level was reached first.

• Expiry-aware outcome statistics
Patterns that reach neither Target 2 nor the stop are now resolved when their configured Setup Expiry window ends. Expired patterns remain in the denominator, removing the upward bias caused by silently excluding unresolved setups.

• More responsible proof threshold
Historical reach rates remain visually de-emphasized until at least 10 patterns have resolved instead of five.


------------------------
Visual Improvements
------------------------

• Completion markers now use compact uppercase wording such as LONG Q78 and SHORT Q85.

• The PRZ badge uses the premium single-line format “PATTERN | Q00 | STATE”.

• The PRZ badge remains horizontally and vertically centered inside the active zone.

• Bullish, bearish, neutral, terminal, and pivot-point labels now use contrast-safe filled backgrounds and text colors.

• Label Font Size now defaults to Normal while remaining adjustable.


------------------------
Interface & Usability
------------------------

• The first panel row remains one merged blue header containing only “AG Pro Harmonic Completion Engine.”

• Action has been renamed Context, with neutral analytical wording for Ready, Triggered, T1, terminal, and expired states.

• State names use consistent premium uppercase formatting.

• Disabling Show Panel now clears the complete table immediately, preventing stale panel content from remaining on the chart.

• Panel theme, location, panel font size, label font size, pivot structure, pattern, PRZ, levels, and marker controls remain available.


------------------------
Behavior Notes
------------------------

This update preserves the four supported pattern families, pivot architecture, ratio tolerance, best-fit matcher, Minimum Ratio Score, four-factor Quality weights, Ready threshold, PRZ geometry concept, lifecycle states, marker limits, trade-level geometry, and alert set.

Quality, Reaction, Trend, stop distance, Reward:Risk, and historical reach rates may change because the calculation is now aligned to D and outcomes no longer use pre-confirmation movement or omit expired patterns.

Target and stop handling uses completed OHLC bars. Stop-first precedence is intentionally conservative when intrabar order is unknowable.


------------------------
Limitations Reminder
------------------------

The script remains a rule-based analytical and visualization tool.

Confirmed pivots appear after the selected Pivot Length, so harmonic structures are intentionally delayed. OHLC bars do not reveal the exact intrabar path. Liquidity, volatility, timeframe, tolerance, lookback, and expiry settings can materially affect pattern frequency, scores, and reach statistics.

Historical reach rates describe the loaded chart sample; they are not forecasts or probabilities promised for future patterns.


------------------------
Risk Reminder
------------------------

This script is for educational and analytical purposes only.

It does not provide financial advice, automated execution, or guaranteed trading outcomes.

Users remain responsible for their own decisions and risk management.

Jul 24

Release Notes

🔧 UPDATE NOTES - V2.0.2

• Refreshed the publication and access routing information.
• Core harmonic-completion logic, panel behavior, inputs, alerts, visuals, and outputs remain unchanged.

Jul 30

Release Notes

🔧 UPDATE NOTES - V2.0.3

This update focuses on visual hierarchy, panel clarity, and cleaner Potential Reversal Zone presentation.

The harmonic detection, ratio evaluation, quality model, setup lifecycle, outcome tracking, and alert logic remain unchanged.

This script continues to function as an analytical and visualization tool. It does not attempt to predict price direction or provide guaranteed outcomes.


------------------------
What Changed
------------------------

• Added a product-specific panel question: “IS THIS HARMONIC COMPLETION VALID?”
This gives the dashboard a clearer analytical purpose at first glance.

• Rebuilt the active PRZ badge as a compact two-line label.
Pattern, quality, and lifecycle state remain centered inside the zone without covering as much price structure.

• Extended the panel by one row while preserving the existing section separators.
The original information architecture and metrics remain intact.

• Added theme-aware question text contrast.
The question remains readable in both Dark and Light panel themes.


------------------------
Visual Improvements
------------------------

• Reduced the horizontal footprint of the centered PRZ status label

• Improved separation between the panel title, analytical question, verdict, quality breakdown, plan, and outcome statistics

• Preserved the premium AGPro color hierarchy and centered zone-label convention

• Reduced visual obstruction around the harmonic completion area


------------------------
Interface & Usability
------------------------

• Panel visibility, location, theme, and font-size controls remain available

• Label font-size and display-density controls remain available

• The panel now communicates the script’s core decision question before presenting supporting evidence

• Existing XABCD markers, PRZ, entry, stop, and target controls remain unchanged


------------------------
Behavior Notes
------------------------

This update does not change the core analytical logic of the script.

Gartley, Bat, Butterfly, and Crab recognition, ratio tolerances, readiness scoring, lifecycle states, historical outcome tracking, and alerts behave as before.

The goal is to improve clarity and usability, not to introduce new predictive behavior.


------------------------
Limitations Reminder
------------------------

Harmonic structures depend on pivot selection, ratio tolerance, market volatility, and timeframe.

A visually complete XABCD structure does not guarantee a reversal, target reach, or profitable outcome.

Outputs should always be interpreted within broader market context.


------------------------
Risk Reminder
------------------------

This script is for educational and analytical purposes only.

It does not provide financial advice or guaranteed trading outcomes.

Users remain responsible for their own decisions.

Aug 18

Release Notes

Version 2.1.0 – Terminal PRZ Lifecycle Clarity

This update corrects the visual ownership of completed harmonic setups while preserving the confirmed-pivot stream, four-family matcher, quality model, setup lifecycle, outcome statistics, and alerts.

• Bounded terminal PRZ zones to the original D-point completion area, preventing completed or stopped patterns from producing a horizontal band that extends across months of later price action.

• Preserved forward projection for live Ready, Triggered, and T1-active setups so actionable harmonic context continues to extend into current chart space.

• Rebuilt the centered PRZ verdict as a two-line badge showing pattern family, Quality, direction, and lifecycle state.

• Converted the panel State value into a contrast-safe filled decision cell, making live, completed, stopped, and expired outcomes easier to distinguish.

• Reduced historical completion-marker density with a 52-bar cooldown while retaining the six-marker cap and increasing the default ATR offset.

• Reworded completion markers as BULLISH and BEARISH quality events, keeping the chart analytical rather than instructional.

• Hardened the panel rebuild path by recreating both title and question cells before merging their rows.

• Preserved Gartley, Bat, Butterfly, and Crab detection; XABCD geometry; four-factor Quality; PRZ and trade-level calculations; lifecycle chronology; reach-rate accounting; and all five alert conditions.