Design top-down source-fib projection review before nested fibs

[JohnCCarter]

Purpose

Define the next labeling/review-tool design step for the BTC-first Fibonacci research workflow.

We have agreed that the active first research track should not immediately introduce nested lower-timeframe fibs. First, the tool must support a clean top-down projection workflow:

Human 1M source fib
→ project same fib levels down to 1W / 1D / 4H
→ review how lower-timeframe candles interact with the higher-timeframe levels

Nested fibs inside the 1M/1W range are a later research track after this first projection workflow is verified.

---

Core decision

Separate the workflow into three concepts:

1. Source fib

   • Human-drawn fib on a higher timeframe, initially BTC/USD 1M.
   • This is the source of truth.

2. Projected review

   • The source fib’s price levels are projected onto lower chart timeframes.
   • Example: 1M levels shown on 1W, 1D, and 4H candles.
   • Machine logic only labels candle interaction with those projected levels, and treats every configured level equally (no prioritized levels).

3. Nested fibs

   • Local lower-timeframe fibs inside the higher-timeframe range.
   • This is intentionally deferred until source-fib projection is stable and reviewed.

---

Active phase: source-fib projection only

For the active phase, the tool should support:

BTC/USD 1M source fib
→ projected to 1W
→ projected to 1D
→ projected to 4H

The user should draw the fib once on 1M. When switching to 1W, 1D, or 4H, the tool should not require a new fib. It should read the saved 1M fib and render/project the same price levels onto the lower timeframe chart.

---

Prerequisites

• BTC/USD 1M source facit already exists — 9 log-scale monthly fibs under data/labels/human_fib/bitfinex/BTC-USD/1M/. The projection workflow consumes those as the locked source; no new 1M fib needs to be drawn for this issue.
• Lower-timeframe candle caches are present — 1W, 1D, and 4H raw caches exist under data/raw/bitfinex/BTC-USD/ (including a deep 4h/limit_20000.csv), so 1M → 1W/1D/4H projection can run offline. Re-drawing 1W/1D/4H human facit is a separate protocol track and is not required for projection review.

---

Levels model (no machine bias)

All configured fib levels are equally event-capable. The machine must not treat any level (including 0.5 or 0.618) as inherently more important.

• event_levels = all configured levels. Every level can generate events.
• boundary_levels = [0, 1] — the range edges (anchor_b / anchor_a). These are boundary levels, not internal retracement levels, but they remain event-capable.
• retracement_levels = [0.382, 0.5, 0.618, 0.786] — the internal levels.
• human_highlights = presentation/review only. Optional visual annotations (e.g. a zone from 0.5 to 0.618) created in the labeling tool and displayed in the review tool. They may drive filtering, toggling, and visual focus, but must never affect event detection, outcome logic, sampling, or level importance.

There is no primary_active_levels, no "golden zone" machine logic, and no prioritized levels in the data.

Protocol-cleanup note. The active protocol previously defined primary_active_levels: [0.5, 0.618] as a golden-zone review-sampling focus (in config/*.yaml, core/config.py, research/human_review_pack.py, and the protocol docs). Per Addendum 2 this is retired in favor of human_highlights. Removing primary_active_levels from configs, schema, review sampling, and docs — and regenerating the 1M review pack without sampling bias — is part of this issue's protocol cleanup.

---

Required metadata

Human fib / projected event records must preserve enough context to avoid ambiguity:

{
  "source_fib_id": "fib_BTC-USD_1M_...",
  "source_tf": "1M",
  "chart_tf": "4h",
  "projected_from": "1M",
  "scale_mode": "log",
  "levels_profile": "tradingview_log_chamoun",
  "levels": [0, 0.382, 0.5, 0.618, 0.786, 1],
  "event_levels": [0, 0.382, 0.5, 0.618, 0.786, 1],
  "boundary_levels": [0, 1],
  "retracement_levels": [0.382, 0.5, 0.618, 0.786],
  "human_highlights": []
}

human_highlights is optional and presentation-only. Example of a populated highlight (does not change detection):

"human_highlights": [
  {
    "kind": "zone",
    "from": 0.5,
    "to": 0.618,
    "note": "visual review focus only — does not affect event detection"
  }
]

Schema naming note. Prefer the existing persisted schema fields where possible:

fib_id                  (persisted source-fib id)
projected_from_timeframe (persisted source/HTF timeframe)
timeframe               (persisted chart/LTF timeframe)

source_fib_id, source_tf, projected_from, and chart_tf above may be used as review-facing aliases if they make the review tool clearer, but do not introduce a second persistent vocabulary without an explicit schema decision. (source_tf and projected_from are the same value.)

Active BTC-first profile (matches the repo's tradingview_log_chamoun profile):

levels_profile = tradingview_log_chamoun
scale_mode     = log
levels         = [0, 0.382, 0.5, 0.618, 0.786, 1]
boundary_levels    = [0, 1]
retracement_levels = [0.382, 0.5, 0.618, 0.786]
event_levels       = all levels (no prioritization)
human_highlights   = presentation/review only
no 0.236

Legacy fibs that use 0.236 and/or linear scale belong to a separate profile and must not be mixed into tradingview_log_chamoun.

---

Review tool behavior

The review view should clearly show:

SOURCE FIB:
1M H→L or L→H

CURRENT CHART:
1W / 1D / 4H

PROJECTED LEVELS (all event-capable):
1M 0       (boundary)
1M 0.382
1M 0.5
1M 0.618
1M 0.786
1M 1       (boundary)

If the human added highlights, the review tool may visually mark them (e.g. a 0.5–0.618 zone) for review focus only. Highlights change presentation, never detection — and the machine still emits events on every level equally.

Events should be named with full context, for example:

1M 0.5 touched by 4H candle
1M 0.618 crossed by 1D candle
1M 0.382 touched by 4H candle
1M 1 touched by 1D candle

Avoid ambiguous labels such as only:

0.5 touch

Every event must make clear:

• which fib the level comes from
• which timeframe the fib was drawn on
• which chart timeframe is being reviewed
• which candle timeframe produced the interaction

Any "zone"-level summary in the review (e.g. "candles inside the 0.5–0.618 highlighted zone") is a presentation grouping derived from human_highlights only — it is not a separate machine event type and carries no priority.

---

Explicitly deferred: nested fibs

Do not implement nested lower-timeframe fibs as part of this issue.

Nested fibs should later use explicit parent metadata, for example:

{
  "fib_id": "fib_BTC-USD_1W_...",
  "source_tf": "1W",
  "parent_fib_id": "fib_BTC-USD_1M_...",
  "parent_source_tf": "1M",
  "nested_inside": "1M_range"
}

But this belongs to a later phase only after 1M projection is verified.

---

Acceptance criteria

• Tool can load a human 1M source fib and project its levels onto 1W / 1D / 4H charts.
• Review view clearly identifies source_tf, chart_tf, and projected_from.
• Events preserve full context: source fib, source timeframe, chart timeframe, ratio, price, relation.
• All configured levels (0, 0.382, 0.5, 0.618, 0.786, 1) are event-capable; the machine applies no priority or bias between them.
• 0 and 1 are recorded as boundary levels (range edges), not internal retracement levels, while remaining event-capable.
• human_highlights affect presentation/review only (filtering, toggling, visual focus) and never event detection, outcome logic, sampling, or level importance.
• primary_active_levels is removed from configs, schema, review sampling, and docs (Addendum 2 cleanup); the 1M review pack is regenerated without golden-zone sampling bias.
• Active profile is tradingview_log_chamoun (scale_mode = log, no 0.236); legacy 0.236 / linear fibs are kept under a separate profile and not mixed in.
• No nested fib implementation in this issue.
• No auto-fib.
• No trading logic.
• No edge claims.
• Human fib remains source of truth.

---

Research guardrail

This issue exists to keep the first track clean:

1M source fib → lower-TF candle interaction review

Do not mix in the later track:

1M fib + 1W nested fib + 1D nested fib + 4H events

until the first track has been visually reviewed and approved.

[JohnCCarter]

Addendum for issue #30: Keep this issue locked to the active research track: 1M source fib projection down to 1W, 1D, and 4H for lower-timeframe candle interaction review. If the discussion drifts toward nested fibs, auto-fib, strategy logic, tuning, or unrelated backtests, Claude or any coding agent should pause and ask whether to stay on issue #30 or create a separate issue. Before implementation or tests, the agent must review repo rules and confirm the active fib protocol: log scale, levels 0 / 0.382 / 0.5 / 0.618 / 0.786 / 1, primary active levels 0.5 and 0.618, no 0.236 in the active profile, human fib is source of truth, no auto-fib, and no nested fibs in this issue. Protocol first, tests second.

[JohnCCarter]

Addendum: replace the earlier idea of prime or primary active levels with human visual highlights.

Decision:

• All fib levels remain relevant.
• All fib levels can generate events.
• The machine must not treat 0.5 or 0.618 as inherently more important in the data.
• No machine bias should be introduced through prime, primary, or important level terminology.

Preferred model:

• event_levels = all configured fib levels
• human_highlights = visual or review-focused annotations only

Highlight workflow:

• Primary creation happens in the labeling tool, where the user draws the source fib and may highlight levels or zones on the chart.
• The review tool reads and displays those highlights.
• The review tool may allow adding or adjusting a highlight, but it must be saved explicitly as a human review highlight, not as machine logic.

Important rule:
Human highlights affect presentation only. They may help filtering, toggling, and visual review, but they must not change event detection, outcome logic, sampling, or level importance.

Example:

• levels: 0, 0.382, 0.5, 0.618, 0.786, 1
• event_levels: all levels above
• human_highlights: optional zones such as 0.5 to 0.618 for visual review focus only

This preserves the research principle: the user draws the map, the machine marks all candle interactions objectively, and the review tool shows the result clearly without creating hidden bias.

[JohnCCarter]

Review of #30 — source-fib projection workflow

Reviewed against the current code (research/mtf_fib_level_projection.py, labeling/human_fib.py, config/settings.yaml, the existing BTC/USD human fibs, and docs/MTF_FIB_LEVEL_PROJECTION.md). Overall: the issue is well-scoped and aligned with the repo's discipline (human fib = source of truth, no auto-fib, research-only). Most of the engine already exists. Below are the gaps, one real contradiction, and prerequisites to make the acceptance criteria reachable.

1. Most of the core already exists — extend, don't rebuild

research/mtf_fib_level_projection.py already does the heart of this issue: it loads a locked HTF human fib (load_annotation, never mutated) and projects its exact level prices onto lower-TF candles, emitting one row per interaction with fib_id, fib_level, fib_price, timeframe (the chart TF), projected_from_timeframe (the source TF), relation (above/below/touch/cross), approach_side, touch_type, and event_time. So acceptance items "load a 1M fib and project onto 1W/1D/4H" and "events preserve full context" are ~80% covered today. The genuinely new piece is a review view plus a small amount of metadata/labeling glue — not a new engine.

2. Internal contradiction: body vs. Addendum 2 (must resolve)

The body defines primary_active_levels: [0.5, 0.618], shows ACTIVE / GOLDEN labels, and lists events like 4H entered 1M golden zone. Addendum 2 explicitly reverses this: no machine bias, all levels generate events equally, and primary_active_levels is replaced by presentation-only human_highlights. The acceptance criterion "0.5 and 0.618 are treated as primary_active_levels / golden zone" directly contradicts Addendum 2.

Recommendation: update the body + that acceptance line to match Addendum 2 — drop primary_active_levels from the data model entirely; keep event_levels = all configured levels; add an optional human_highlights block that affects presentation only. A "golden zone entered" line in the review should be derived from a human highlight, never a privileged machine event class.

3. Metadata naming drift vs. existing schema

The proposed record uses source_fib_id, source_tf, chart_tf, projected_from. The code already emits fib_id, projected_from_timeframe (= the source/HTF), and timeframe (= the chart TF). Two notes:

• source_tf and projected_from are the same value (the TF the fib was drawn on) — the proposed schema is redundant there.
• To avoid schema drift, prefer aligning on the existing field names (or add source_tf/chart_tf as explicit aliases) rather than introducing a second vocabulary. New fields genuinely missing today: source_tf/chart_tf aliases, scale_mode, levels_profile, human_highlights, and a human-readable composed label (see Maskin-labeling: taggade provisoriska kandidater som inte kan bli facit #6).

4. Profile mismatch with existing data (0.236 / 0 / 1, log scale)

The active BTC profile is levels = [0, 0.382, 0.5, 0.618, 0.786, 1], no 0.236, scale_mode = log. The current code disagrees on every count:

• DEFAULT_FIB_RATIOS = (0.236, 0.382, 0.5, 0.618, 0.786, 1.0) and config/settings.yaml fib.levels = [0.236, 0.382, 0.5, 0.618, 0.786] include 0.236 and omit 0.
• Every saved BTC/USD fib (e.g. fib_BTC-USD_1w_20260108T000000.json) was written with 0.236 and no 0.
• compute_levels() is linear only (price = b + r*(a-b)). A TradingView log golden-zone fib uses price = b*(a/b)^r, so linear-derived level prices won't match what was drawn in log mode on TV.

Recommendation: introduce a named profile (e.g. tradingview_log_golden_zone) that pins levels, scale_mode=log, and the ratio set, recorded on each fib/projection record. New BTC source fibs should be created under this profile; existing 0.236-based fibs are a different profile and shouldn't be silently mixed in. Also: ratios 0 and 1 are the anchors themselves (anchor_b / anchor_a) — confirm you want endpoint interactions labeled as events too, or treat 0/1 as visual context only.

5. Prerequisites / blockers for the active phase

• No 1M source fib exists. There is no BTC/USD fib under data/labels/human_fib/bitfinex/BTC-USD/1M/ (only 1d and 1w). Since the human fib is source of truth, the 1M fib must be drawn by you before the workflow can be exercised end-to-end. This is the gating dependency for every acceptance item.
• 4H candle cache is thin. 1d/1w caches are deep; 4h is a shallow recent slice, so 1M → 4H projection needs a 4h fetch first. Note a 1M fib's leg-end (anchor_b.time) may predate the 4h cache — the detector clamps the scan start to the start of the loaded window, which is acceptable but means 4H review only covers the cached window.

6. Event naming is structured but not human-readable yet

Today's rows carry all the context fields, but there is no composed label like 1M 0.5 touched by 4H candle or 1M 0.618 crossed by 1D candle. This is a small, presentation-layer add (format {source_tf} {ratio} {relation} by {chart_tf} candle) — straightforward given the fields already present.

7. Review view — not built yet

Only interactions.jsonl and the research/human_review_* packs exist; there is no dedicated source-fib projection review view showing the SOURCE FIB / CURRENT CHART / PROJECTED LEVELS layout from the issue. Suggestion (low risk, matches the issue's text mock-up): start with a text/markdown review pack reusing the human_review_* pattern, and add a chart overlay later if the text review proves the workflow.

8. Acceptance criteria — status at a glance

• Load 1M fib, project to 1W/1D/4H — engine ready; needs the 1M fib + 4h data.
• Review view identifies source_tf/chart_tf/projected_from — needs the new view (fibengine-next: repo structure, Optuna cleanup (docs/artifacts), machine labeling #7); fields exist in the data.
• Events preserve full context — largely met; add the human-readable label (Maskin-labeling: taggade provisoriska kandidater som inte kan bli facit #6).
• 0.5/0.618 as primary_active_levels/golden zone — conflicts with Addendum 2 (Remove label-optimizing tuning; fix silent out-of-window bug; raise coverage #2); recommend rewording to human_highlights.
• Other levels visible as context — fine.
• No 0.236 in active profile — needs the profile change (Address PR review feedback (out-of-window edge cases) #4).
• No nested fib / no auto-fib / no trading logic / no edge claims / human fib = source of truth — already consistent with the repo and current code.

Summary of recommended issue edits

1. Reconcile the body + acceptance criteria with Addendum 2 (remove primary_active_levels; use event_levels = all + human_highlights).
2. Align metadata field names with the existing schema (fib_id, projected_from_timeframe, timeframe) or define explicit aliases; drop the redundant source_tf vs projected_from.
3. Define the tradingview_log_golden_zone profile (levels, scale_mode=log, log level computation) and keep it separate from the legacy 0.236 fibs.
4. Add prerequisite tasks: (a) draw the BTC/USD 1M source fib, (b) fetch 4h candles, (c) decide whether ratios 0/1 emit events.
5. Pick a review-view form (text/markdown pack recommended first).

No blocking objections to the direction — it stays cleanly on the first track (1M source fib → lower-TF candle interaction review) and defers nested fibs as intended.

---

Generated by Claude Code

[JohnCCarter]

Correction to my earlier review (stale repo mirror)

⚠️ My earlier review comment above was partly based on a stale mirror of the repository, not the current working tree (post 2026-06-09 log-scale + profile reset). Several claims were wrong. Corrections against the actual repo:

• A 1M source fib is NOT missing. There are 9 log-scale BTC/USD 1M fibs under data/labels/human_fib/bitfinex/BTC-USD/1M/. No 1M fib needs to be drawn for this issue.
• compute_levels() already supports log scale, and HumanFibAnnotation already carries scale_mode and levels_profile.
• The active ratio set is already [0.0, 0.382, 0.5, 0.618, 0.786, 1.0] (no 0.236) in DEFAULT_FIB_RATIOS and in config/settings.yaml / settings.expansion.yaml, which already set scale_mode: log and levels_profile: tradingview_log_chamoun.
• 4H candle data is NOT thin — data/raw/bitfinex/BTC-USD/4h/ has limit_8000.csv and limit_20000.csv, so 1M → 1W/1D/4H projection runs offline; no fetch is required.
• The profile name is tradingview_log_chamoun, not tradingview_log_golden_zone (which exists nowhere in the repo). The issue body has been corrected to use tradingview_log_chamoun.

What still stands from the review:

• The projection engine already exists (research/mtf_fib_level_projection.py); the net-new work is a review view + human_highlights + boundary/retracement metadata.
• The Addendum 2 conflict is real: the active protocol still defines primary_active_levels: [0.5, 0.618] (golden-zone review sampling in core/config.py, the three yaml configs, research/human_review_pack.py, and the protocol docs). Per the decision to let Addendum 2 win, primary_active_levels will be removed and the 1M review pack regenerated without sampling bias.

The issue #30 body has been updated to reflect all of the above.

[JohnCCarter]

Closing — completed and superseded by the executed BTC top-down protocol. The projection-review design was locked and built: research/source_fib_projection_review.py, source_fib_projection_chart.py, mtf_fib_level_projection.py, weekly_projection_map.py. The 1M source-fib → 1W/1D/4H projection review was exercised end-to-end (1M reaction-review cycle, all 9 source fibs reviewed through 1D + 4H). The Addendum 2 reconciliation landed (primary_active_levels retired in favour of human_highlights; active profile tradingview_log_chamoun, ratios [0,0.382,0.5,0.618,0.786,1], no 0.236). Nested fibs remain intentionally deferred as the issue specified.