Skill: tangweigang-jpg/talib-technical-analysis (version 0.3.3)

--- name: talib-technical-analysis description: |- 通过 Python 调用 150+ TA-Lib 技术分析指标（均线、MACD、RSI、布林带等），支持多市场金融数据的技术面量化计算。 license: Proprietary. See LICENSE.txt in project root. compatibility: Designed for Doramagic-host ecosystem (Claude Code / openclaw / Cursor). Requires Python 3.12+ with uv package manager. metadata: version: "v6.1" blueprint_id: "finance-bp-109" compiled_at: "2026-04-22T13:00:52.305302+00:00" capability_markets: "multi-market" capability_activities: "technical-analysis" sop_version: "crystal-compilation-v6.1" --- # TA-Lib 技术分析 (talib-technical-analysis) > 通过 Python 调用 150+ TA-Lib 技术分析指标（均线、MACD、RSI、布林带等），支持多市场金融数据的技术面量化计算。 ## Pipeline `data_collection -> data_storage -> factor_computation -> target_selection -> trading_execution -> visualization` ## Top Use Cases (1 total) ### TA-Lib Documentation HTML Generator (`UC-101`) Converts TA-Lib markdown documentation into styled HTML pages for web publishing, and generates Pygments syntax highlighting CSS for code examples in **Triggers**: documentation generation, html pages, pygments stylesheet **Execute trigger**: `When user intent matches intent_router.uc_entries[].positive_terms AND user uses action verb (run/execute/跑/执行/backtest/fetch/collect)` ## What I'll Ask You - Target market: A-share (default), HK, or crypto? (US stocks in ZVT are half-baked — stockus_nasdaq_AAPL exists but coverage is thin) - Data source / provider: eastmoney (free, no account), joinquant (account+paid), baostock (free, good history), akshare, or qmt (broker)? - Strategy type: MACD golden-cross, MA crossover, volume breakout, fundamental screen, or custom factor? - Time range: start_timestamp and end_timestamp for backtest period - Target entity IDs: specific stocks (stock_sh_600000) or index components (SZ1000)? ## Semantic Locks (Fatal) | ID | Rule | On Violation | |---|---|---| | `SL-01` | Execute sell orders before buy orders in every trading cycle | halt | | `SL-02` | Trading signals MUST use next-bar execution (no look-ahead) | halt | | `SL-03` | Entity IDs MUST follow format entity_type_exchange_code | halt | | `SL-04` | DataFrame index MUST be MultiIndex (entity_id, timestamp) | halt | | `SL-05` | TradingSignal MUST have EXACTLY ONE of: position_pct, order_money, order_amount | halt | | `SL-06` | filter_result column semantics: True=BUY, False=SELL, None/NaN=NO ACTION | halt | | `SL-07` | Transformer MUST run BEFORE Accumulator in factor pipeline | halt | | `SL-08` | MACD parameters locked: fast=12, slow=26, signal=9 | halt | Full lock definitions: [references/LOCKS.md](references/LOCKS.md) ## Top Anti-Patterns (15 total) - **`AP-TECHNICAL-ANALYSIS-001`**: C FFI Type Mismatch with Non-float64 Arrays - **`AP-TECHNICAL-ANALYSIS-002`**: Multidimensional Array Memory Access Violations - **`AP-TECHNICAL-ANALYSIS-003`**: Ignoring TA_RetCode Error Status from C Calls All 15 anti-patterns: [references/ANTI_PATTERNS.md](references/ANTI_PATTERNS.md) ## Evidence Quality Notice > [QUALITY NOTICE] This crystal was compiled from blueprint finance-bp-109. Evidence verify ratio = 45.1% and audit fail total = 35. Generated results may have uncaptured requirement gaps. Verify critical decisions against source files (LATEST.yaml / LATEST.jsonl). ## Reference Files | File | Contents | When to Load | |---|---|---| | [references/seed.yaml](references/seed.yaml) | V6+ 全量权威 (source-of-truth) | 有行为/决策争议时必读 | | [references/ANTI_PATTERNS.md](references/ANTI_PATTERNS.md) | 15 条跨项目反模式 | 开始实现前 | | [references/WISDOM.md](references/WISDOM.md) | 跨项目精华借鉴 | 架构决策时 | | [references/CONSTRAINTS.md](references/CONSTRAINTS.md) | domain + fatal 约束 | 规则冲突时 | | [references/USE_CASES.md](references/USE_CASES.md) | 全量 KUC-* 业务场景 | 需要完整示例时 | | [references/LOCKS.md](references/LOCKS.md) | SL-* + preconditions + hints | 生成回测/交易代码前 | | [references/COMPONENTS.md](references/COMPONENTS.md) | AST 组件地图（按 module 拆分）| 查 API 时 | --- *Compiled by Doramagic crystal-compilation-v6.1 from `finance-bp-109` blueprint at 2026-04-22T13:00:52.305302+00:00.* *See [human_summary.md](human_summary.md) for non-technical overview.*

path: human_summary.md
content: # Human Summary

> I help you build quant strategies on A-share with ZVT — from data fetch to backtest, one flow. Just tell me what you want; I'll write the code, you don't have to dig docs. (Heads up: ZVT natively supports A-share, HK, and crypto. US stocks — stockus_nasdaq_AAPL — are half-baked; don't bother for serious work.)

## What I Can Do

- **tagline**: I help you build quant strategies on A-share with ZVT — from data fetch to backtest, one flow. Just tell me what you want; I'll write the code, you don't have to dig docs. (Heads up: ZVT natively supports A-share, HK, and crypto. US stocks — stockus_nasdaq_AAPL — are half-baked; don't bother for serious work.)
- **use_cases**: ['TA-Lib Documentation HTML Generator', 'A-share MACD daily golden-cross backtest with hfq price adjustment from eastmoney', 'End-to-end ZVT pipeline: FinanceRecorder + GoodCompanyFactor + StockTrader', 'Multi-factor strategy with TargetSelector (AND mode) combining MACD + volume breakout', 'Index composition data collection (SZ1000, SZ2000) with EM recorder', 'Institutional fund holdings tracker via joinquant_fund_runner pattern', 'Custom Transformer + Accumulator factor with per-entity rolling state']

## What I Ask You

- Target market: A-share (default), HK, or crypto? (US stocks in ZVT are half-baked — stockus_nasdaq_AAPL exists but coverage is thin)
- Data source / provider: eastmoney (free, no account), joinquant (account+paid), baostock (free, good history), akshare, or qmt (broker)?
- Strategy type: MACD golden-cross, MA crossover, volume breakout, fundamental screen, or custom factor?
- Time range: start_timestamp and end_timestamp for backtest period
- Target entity IDs: specific stocks (stock_sh_600000) or index components (SZ1000)?


path: references/ANTI_PATTERNS.md
content: # Anti-Patterns (Cross-Project)

Total: **15**

## finance-bp-109--ta-lib-python (8)

### `AP-TECHNICAL-ANALYSIS-001` — C FFI Type Mismatch with Non-float64 Arrays <sub>(high)</sub>

Passing non-float64 (NPY_DOUBLE) numpy arrays to TA-Lib C functions causes memory corruption or silent incorrect calculations. The C FFI layer expects precisely float64 precision, and type mismatches propagate undetected, producing wrong indicator values that may silently corrupt trading strategies. Root cause is not validating array dtype before the C function call.

### `AP-TECHNICAL-ANALYSIS-002` — Multidimensional Array Memory Access Violations <sub>(high)</sub>

Passing multidimensional numpy arrays to TA-Lib C functions causes segmentation faults and memory access violations due to incorrect stride calculations. The C layer assumes contiguous 1-dimensional memory layouts, and higher-dimensional inputs break its internal pointer arithmetic, leading to crashes or silent memory corruption.

### `AP-TECHNICAL-ANALYSIS-003` — Ignoring TA_RetCode Error Status from C Calls <sub>(high)</sub>

When TA-Lib C functions return non-zero TA_RetCode values (indicating errors like uninitialized library, invalid parameters, or out-of-range inputs), ignoring these codes silently propagates invalid computation results. This leads to incorrect technical indicator values feeding into trading strategies without any warning, potentially causing significant financial loss.

### `AP-TECHNICAL-ANALYSIS-004` — Mismatched Array Lengths in Multi-Input Functions <sub>(high)</sub>

When calculating indicators that require multiple input arrays (e.g., open, high, low, close, volume), providing arrays of different lengths causes out-of-bounds memory access. TA-Lib iterates assuming identical sizes, and length mismatches produce garbage values or segmentation faults, corrupting the entire indicator output.

### `AP-TECHNICAL-ANALYSIS-011` — Stale Cached Outputs Without Invalidation <sub>(medium)</sub>

Caching computed indicator outputs without invalidating when inputs, parameters, or input_names change causes stale results to be returned even when underlying data has changed. This produces incorrect indicator values that silently propagate into trading strategies, leading to wrong signals based on outdated calculations.

### `AP-TECHNICAL-ANALYSIS-012` — Concurrent Access Without Thread-Local State <sub>(high)</sub>

Using shared Function instances across multiple threads without thread-local storage causes race conditions where concurrent threads share state. This leads to data corruption, incorrect results, and non-deterministic indicator values when multiple threads compute indicators simultaneously on the same instance.

### `AP-TECHNICAL-ANALYSIS-013` — Using Python Lists Instead of NumPy Arrays for Stream Functions <sub>(medium)</sub>

Stream functions require numpy.ndarray inputs due to direct C API access via PyArray_TYPE() and PyArray_FLAGS(). Passing plain Python lists or other sequences causes runtime errors because the C layer cannot access the underlying C arrays. This breaks real-time indicator calculations that expect efficient numpy buffer access.

### `AP-TECHNICAL-ANALYSIS-014` — Library Not Initialized Before C Function Calls <sub>(high)</sub>

Calling TA-Lib C functions without prior library initialization returns TA_RetCode=1 (TA_LIB_NOT_INITIALIZE), causing all function calls to fail. This is a silent failure mode that produces no output indicators, breaking batch calculation pipelines unless the initialization step is explicitly performed before any function calls.

## finance-bp-122--ta-python (7)

### `AP-TECHNICAL-ANALYSIS-005` — Time-Series Index Reindexing Breaks Alignment <sub>(high)</sub>

Reindexing or resetting the DataFrame/Series index after computing technical indicators breaks temporal alignment with original price data and other features. This causes look-ahead bias, shifts indicator values to incorrect timestamps, and corrupts time-series datasets when used in backtesting or feature engineering pipelines.

### `AP-TECHNICAL-ANALYSIS-006` — NaN/Inf/Zero Propagation Corrupts Indicator Values <sub>(high)</sub>

Failing to clean input data of NaN, infinite values, or zero prices causes cascading corruption through rolling window calculations. Division-by-zero errors on zero prices produce NaN that propagates into all subsequent indicator values, corrupting entire datasets. Invalid values also cause incorrect boolean mask classifications when compared with np.inf directly.

### `AP-TECHNICAL-ANALYSIS-007` — EMA Smoothing Parameter Divergence from TA Standards <sub>(medium)</sub>

Using pandas adjust=True (the default) for ewm() when implementing EMA-based indicators produces Yahoo Finance variant smoothing instead of standard recursive exponential smoothing per technical analysis textbooks. This causes different signal thresholds and divergence from widely-accepted indicator calculations, leading to inconsistent trading signals.

### `AP-TECHNICAL-ANALYSIS-008` — False Claims: Indicator Calculation as Trading Signal <sub>(high)</sub>

Presenting technical indicator values as real-time trading signals or guaranteed future performance misleads users about the tool's capabilities. The library calculates historical indicators from OHLCV data; claiming these as trading signals leads to improper trading decisions. Backtest results also do not guarantee future performance due to look-ahead bias and market regime changes.

### `AP-TECHNICAL-ANALYSIS-009` — Functional vs OOP API Implementation Divergence <sub>(medium)</sub>

When both functional wrappers (e.g., rsi()) and OOP classes (e.g., RSIIndicator) are provided, diverging implementations produce different indicator values for the same inputs. This causes confusion, test failures, and breaks user code that expects consistent behavior across APIs. The functional wrapper must delegate to the class implementation to ensure equivalence.

### `AP-TECHNICAL-ANALYSIS-010` — Bollinger Bands Using Sample Std Deviation <sub>(medium)</sub>

Using pandas default ddof=1 (sample standard deviation) for Bollinger Bands produces wider bands than John Bollinger's original specification, which uses population standard deviation. This causes overestimation of volatility, incorrect trading signal thresholds, and divergence from the canonical indicator calculation that traders expect.

### `AP-TECHNICAL-ANALYSIS-015` — Stateful Wrapper Functions Leak State Across Calls <sub>(medium)</sub>

When functional wrapper functions retain internal state between calls, different input series contaminate each other's results through data leakage. This produces incorrect indicator values when the same wrapper function is called sequentially with different data, as cached state from previous calls affects new computations.


path: references/COMPONENTS.md
content: # Component Capability Map

**Project**: finance-bp-109--ta-lib-python
**Scan date**: 2026-04-22
**Stats**: {'total_files': 6, 'total_classes': 23, 'total_functions': 0, 'total_stages': 6}

## Modules (6)

- [c_library_binding_layer](components/c_library_binding_layer.md): 2 classes
- [function_api_(batch)](components/function_api_-batch.md): 4 classes
- [stream_api_(incremental)](components/stream_api_-incremental.md): 4 classes
- [abstract_api_(stateful)](components/abstract_api_-stateful.md): 7 classes
- [series_support_layer](components/series_support_layer.md): 2 classes
- [code_generation](components/code_generation.md): 4 classes


path: references/CONSTRAINTS.md
content: # Constraints

## preservation_manifest

```yaml
required_objects:
  business_decisions_count: 104
  fatal_constraints_count: 27
  non_fatal_constraints_count: 147
  use_cases_count: 1
  semantic_locks_count: 12
  preconditions_count: 4
  evidence_quality_rules_count: 2
  traceback_scenarios_count: 5

```


path: references/LOCKS.md
content: # Semantic Locks + Preconditions

## Semantic Locks (12)

### `SL-01` <sub>(on_violation: fatal)</sub>
Execute sell orders before buy orders in every trading cycle

### `SL-02` <sub>(on_violation: fatal)</sub>
Trading signals MUST use next-bar execution (no look-ahead)

### `SL-03` <sub>(on_violation: fatal)</sub>
Entity IDs MUST follow format entity_type_exchange_code

### `SL-04` <sub>(on_violation: fatal)</sub>
DataFrame index MUST be MultiIndex (entity_id, timestamp)

### `SL-05` <sub>(on_violation: fatal)</sub>
TradingSignal MUST have EXACTLY ONE of: position_pct, order_money, order_amount

### `SL-06` <sub>(on_violation: fatal)</sub>
filter_result column semantics: True=BUY, False=SELL, None/NaN=NO ACTION

### `SL-07` <sub>(on_violation: fatal)</sub>
Transformer MUST run BEFORE Accumulator in factor pipeline

### `SL-08` <sub>(on_violation: fatal)</sub>
MACD parameters locked: fast=12, slow=26, signal=9

### `SL-09` <sub>(on_violation: warning)</sub>
Default transaction costs: buy_cost=0.001, sell_cost=0.001, slippage=0.001

### `SL-10` <sub>(on_violation: fatal)</sub>
A-share equity trading is T+1 (no same-day close of buy positions)

### `SL-11` <sub>(on_violation: fatal)</sub>
Recorder subclass MUST define provider AND data_schema class attributes

### `SL-12` <sub>(on_violation: fatal)</sub>
Factor result_df MUST contain either 'filter_result' OR 'score_result' column

## Preconditions (4)

- **`PC-01`**: `python3 -c 'import zvt; print(zvt.__version__)'` → on_fail: Run: python3 -m pip install zvt then re-run: python3 -m zvt.init_dirs to initialize data directories
- **`PC-02`**: `python3 -c "from zvt.api.kdata import get_kdata; df = get_kdata(entity_ids=['stock_sh_600000'], limit=1); assert df is not None and len(df) > 0, 'No kdata found'"` → on_fail: Run recorder first: python3 -m zvt.recorders.em.em_stock_kdata_recorder --entity_ids stock_sh_600000 (replace with your target entity IDs)
- **`PC-03`**: `python3 -c "import os; from pathlib import Path; zvt_home = Path(os.environ.get('ZVT_HOME', Path.home() / '.zvt')); assert zvt_home.exists(), f'ZVT home not found: {zvt_home}'"` → on_fail: Run: python3 -m zvt.init_dirs
- **`PC-04`**: `python3 -c "import os, tempfile; from pathlib import Path; zvt_home = Path(os.environ.get('ZVT_HOME', Path.home() / '.zvt')); test_f = zvt_home / '.write_test'; test_f.touch(); test_f.unlink()"` → on_fail: Check directory permissions: chmod u+w ~/.zvt or set ZVT_HOME environment variable to a writable location


path: references/USE_CASES.md
content: # Known Use Cases (KUC)

Total: **1**

## `KUC-101`
**Source**: `docs/generate_html_pages.py`

Converts TA-Lib markdown documentation into styled HTML pages for web publishing, and generates Pygments syntax highlighting CSS for code examples in documentation.


path: references/WISDOM.md
content: # Cross-Project Wisdom

Total: **9**

## `CW-TECHNICAL-ANALYSIS-001` — Explicit Input Validation Before Computation
**From**: finance-bp-109--ta-lib-python, finance-bp-122--ta-python · **Applicable to**: technical-analysis

Both projects require rigorous pre-computation validation: dtype checking (float64 for C FFI, numeric for pandas), dimension checking (1D arrays for C layer), and length validation. This defensive pattern prevents silent failures and memory corruption. Apply this pattern whenever interfacing with external C libraries or computing indicators on potentially malformed input data.

## `CW-TECHNICAL-ANALYSIS-002` — Index Preservation Throughout Indicator Pipeline
**From**: finance-bp-109--ta-lib-python, finance-bp-122--ta-python · **Applicable to**: technical-analysis

Preserving the original DataFrame/Series index without reindexing or reset is critical for temporal alignment. When constructing output Series, use index=self._close.index to maintain alignment with price data. This prevents look-ahead bias and ensures downstream features correctly reference their corresponding timestamps.

## `CW-TECHNICAL-ANALYSIS-003` — Data Cleaning Before Indicator Computation
**From**: finance-bp-122--ta-python · **Applicable to**: technical-analysis

Indicators like RSI, MACD, and Bollinger Bands produce incorrect results when fed NaN, inf, or zero values. Remove rows with zero prices (to prevent division-by-zero), filter out infinite values using the exp(709) threshold as the maximum float64, and apply dropna to DataFrames before passing to indicator functions. This ensures clean propagation through rolling window calculations.

## `CW-TECHNICAL-ANALYSIS-004` — Error Code Propagation from C to Python Layer
**From**: finance-bp-109--ta-lib-python · **Applicable to**: technical-analysis

Always call _ta_check_success and raise exceptions on non-zero TA_RetCode return values from C function calls. This pattern ensures that errors like uninitialized library, invalid parameters, or out-of-range inputs propagate as proper Python exceptions instead of silently producing garbage values. Never ignore return codes from the underlying C library.

## `CW-TECHNICAL-ANALYSIS-005` — Thread-Local Storage for Concurrent Indicator Access
**From**: finance-bp-109--ta-lib-python · **Applicable to**: technical-analysis

When the same Function instance may be accessed from multiple threads, use thread-local storage to maintain isolated state per thread. This prevents race conditions, state corruption, and non-deterministic results when concurrent threads compute indicators simultaneously. The pattern is essential for any multi-threaded trading system or async processing pipeline.

## `CW-TECHNICAL-ANALYSIS-006` — Functional Wrapper Delegates to OOP Implementation
**From**: finance-bp-122--ta-python · **Applicable to**: technical-analysis

Functional wrapper functions like rsi() and ema_indicator() should instantiate the corresponding Indicator class and call its result method, not reimplement logic. This ensures OOP and functional APIs produce identical outputs. Any divergence causes test failures and breaks user code that switches between API styles. Validate equivalence in test suites.

## `CW-TECHNICAL-ANALYSIS-007` — Standard TA Textbook Parameters for EMA Calculations
**From**: finance-bp-122--ta-python · **Applicable to**: technical-analysis

When implementing EMA-based indicators, use adjust=False in pandas ewm() to match standard recursive exponential smoothing from technical analysis textbooks, not the Yahoo Finance variant. Also use ddof=0 for Bollinger Bands standard deviation per the original specification. Deviations produce different signal thresholds that diverge from what traders expect.

## `CW-TECHNICAL-ANALYSIS-008` — Cache Invalidation on Any Input Change
**From**: finance-bp-109--ta-lib-python · **Applicable to**: technical-analysis

Set outputs_valid flag to False whenever inputs, parameters, or input_names change. This pattern prevents returning stale cached outputs when underlying data or parameters have been modified. Implement proper cache invalidation to ensure computed indicators always reflect the current state.

## `CW-TECHNICAL-ANALYSIS-009` — Library Initialization Before First Use
**From**: finance-bp-109--ta-lib-python, finance-bp-122--ta-python · **Applicable to**: technical-analysis

Explicitly initialize the TA-Lib C library before any function calls. Without initialization, all function calls fail with TA_RetCode=1 (TA_LIB_NOT_INITIALIZE). This is a critical setup step that must be performed once before the indicator computation pipeline begins, typically at application startup or when first loading the library.


path: references/components/abstract_api_-stateful.md
content: # abstract_api_(stateful) (7 classes)

## `Function.__call__`
`abstract_api_(stateful)/function-call.py:0`

## `Function.set_input_arrays`
`abstract_api_(stateful)/function-set-input-arrays.py:0`

## `SMA.invoke`
`abstract_api_(stateful)/sma-invoke.py:0`

## `BBANDS.invoke`
`abstract_api_(stateful)/bbands-invoke.py:0`

## `STOCH.invoke`
`abstract_api_(stateful)/stoch-invoke.py:0`

## `Input data type`
`abstract_api_(stateful)/input-data-type.py:0`

## `Input price series`
`abstract_api_(stateful)/input-price-series.py:0`


path: references/components/c_library_binding_layer.md
content: # c_library_binding_layer (2 classes)

## `TA_RetCode enum access`
`c_library_binding_layer/ta-retcode-enum-access.py:0`

## `Array validation`
`c_library_binding_layer/array-validation.py:0`


path: references/components/code_generation.md
content: # code_generation (4 classes)

## `generate_func.execute`
`code_generation/generate-func-execute.py:0`

## `generate_stream.execute`
`code_generation/generate-stream-execute.py:0`

## `generate_abstract_stub.execute`
`code_generation/generate-abstract-stub-execute.py:0`

## `Name transformation rules`
`code_generation/name-transformation-rules.py:0`


path: references/components/function_api_-batch.md
content: # function_api_(batch) (4 classes)

## `SMA.compute`
`function_api_(batch)/sma-compute.py:0`

## `BBANDS.compute`
`function_api_(batch)/bbands-compute.py:0`

## `ADX.compute`
`function_api_(batch)/adx-compute.py:0`

## `Lookback padding`
`function_api_(batch)/lookback-padding.py:0`


path: references/components/series_support_layer.md
content: # series_support_layer (2 classes)

## `_wrapper.decorate`
`series_support_layer/wrapper-decorate.py:0`

## `Series type detection`
`series_support_layer/series-type-detection.py:0`


path: references/components/stream_api_-incremental.md
content: # stream_api_(incremental) (4 classes)

## `stream_MOM.execute`
`stream_api_(incremental)/stream-mom-execute.py:0`

## `stream_CDL3BLACKCROWS.execute`
`stream_api_(incremental)/stream-cdl3blackcrows-execute.py:0`

## `stream_SMA.execute`
`stream_api_(incremental)/stream-sma-execute.py:0`

## `Streaming state`
`stream_api_(incremental)/streaming-state.py:0`


path: references/seed.yaml
content: meta:
  id: finance-bp-109-v5.3
  version: v6.1
  blueprint_id: finance-bp-109
  sop_version: crystal-compilation-v6.1
  source_language: en
  compiled_at: '2026-04-22T13:00:52.305302+00:00'
  target_host: openclaw
  authoritative_artifact:
    primary: seed.yaml
    non_authoritative_derivatives:
    - SKILL.md (host-generated summary, may lag)
    - HEARTBEAT.md (host telemetry)
    - memory/*.md (host conversational memory)
    rule: On any behavioral decision (preconditions check, OV assertion, EQ rule firing, spec_lock verification), agents MUST
      re-read seed.yaml. Derivatives are for UI display only and may be out-of-date.
  execution_protocol:
    install_trigger:
    - Execute resources.host_adapter.install_recipes[] in declared order
    - Verify each package with import check before proceeding
    execute_trigger: When user intent matches intent_router.uc_entries[].positive_terms AND user uses action verb (run/execute/跑/执行/backtest/fetch/collect)
    on_execute:
    - Reload seed.yaml (do not rely on SKILL.md or cached summaries)
    - Run preconditions[] in declared order; halt on first fatal failure with on_fail message to user
    - Enter context_state_machine.CA1_MEMORY_CHECKED state
    - Evaluate evidence_quality.enforcement_rules[]; prepend user_disclosure_template
    - Translate user_facing_fields to user locale per locale_contract
    - "[V6 READING ORDER]\nThis crystal contains the following V6 layers. Before answering any business question, the host\
      \ MUST read them in order:\n  1. anti_patterns[] — cross-project anti-patterns (with AP-* ids)\n  2. cross_project_wisdom[]\
      \ — cross-project wisdom (with CW-* ids)\n  3. domain_constraints_injected[] — domain constraints (SHARED-* ids)\n \
      \ 4. known_use_cases[] — concrete business scenarios (KUC-* ids)\n  5. component_capability_map — AST component map\
      \ (by module)\n\nWhen answering user questions, proactively cite relevant AP-*/CW-*/SHARED-*/KUC-* ids with source text.\
      \ Examples: T+1 rules -> cite SHARED-* constraint; model comparison -> warn via AP-*; follow-holdings strategy -> cite\
      \ KUC-* with example file."
    workspace_resolution:
      scripts_path: '{host_workspace}/scripts/'
      skills_path: '{host_workspace}/skills/'
      trace_path: '{host_workspace}/.trace/'
  capability_tags:
    markets:
    - multi-market
    activities:
    - technical-analysis
  upgraded_from: finance-bp-109-v1.seed.yaml
  upgraded_at: '2026-04-22T13:20:29.426886+00:00'
  v6_inputs:
    ast_mind_map: knowledge/sources/finance/finance-bp-109--ta-lib-python/v6_inputs/ast_mind_map.yaml
    anti_patterns: null
    cross_project_wisdom: null
    examples_kuc: knowledge/sources/finance/finance-bp-109--ta-lib-python/v6_inputs/examples_kuc.yaml
    shared_pools_dir: knowledge/sources/finance/_shared
anti_patterns:
- id: AP-TECHNICAL-ANALYSIS-001
  title: C FFI Type Mismatch with Non-float64 Arrays
  description: Passing non-float64 (NPY_DOUBLE) numpy arrays to TA-Lib C functions causes memory corruption or silent incorrect
    calculations. The C FFI layer expects precisely float64 precision, and type mismatches propagate undetected, producing
    wrong indicator values that may silently corrupt trading strategies. Root cause is not validating array dtype before the
    C function call.
  project_source: finance-bp-109--ta-lib-python
  severity: high
  applicable_to_tags:
    markets:
    - multi-market
    activities:
    - technical-analysis
  _source_file: anti-patterns/technical-analysis.yaml
- id: AP-TECHNICAL-ANALYSIS-002
  title: Multidimensional Array Memory Access Violations
  description: Passing multidimensional numpy arrays to TA-Lib C functions causes segmentation faults and memory access violations
    due to incorrect stride calculations. The C layer assumes contiguous 1-dimensional memory layouts, and higher-dimensional
    inputs break its internal pointer arithmetic, leading to crashes or silent memory corruption.
  project_source: finance-bp-109--ta-lib-python
  severity: high
  applicable_to_tags:
    markets:
    - multi-market
    activities:
    - technical-analysis
  _source_file: anti-patterns/technical-analysis.yaml
- id: AP-TECHNICAL-ANALYSIS-003
  title: Ignoring TA_RetCode Error Status from C Calls
  description: When TA-Lib C functions return non-zero TA_RetCode values (indicating errors like uninitialized library, invalid
    parameters, or out-of-range inputs), ignoring these codes silently propagates invalid computation results. This leads
    to incorrect technical indicator values feeding into trading strategies without any warning, potentially causing significant
    financial loss.
  project_source: finance-bp-109--ta-lib-python
  severity: high
  applicable_to_tags:
    markets:
    - multi-market
    activities:
    - technical-analysis
  _source_file: anti-patterns/technical-analysis.yaml
- id: AP-TECHNICAL-ANALYSIS-004
  title: Mismatched Array Lengths in Multi-Input Functions
  description: When calculating indicators that require multiple input arrays (e.g., open, high, low, close, volume), providing
    arrays of different lengths causes out-of-bounds memory access. TA-Lib iterates assuming identical sizes, and length mismatches
    produce garbage values or segmentation faults, corrupting the entire indicator output.
  project_source: finance-bp-109--ta-lib-python
  severity: high
  applicable_to_tags:
    markets:
    - multi-market
    activities:
    - technical-analysis
  _source_file: anti-patterns/technical-analysis.yaml
- id: AP-TECHNICAL-ANALYSIS-005
  title: Time-Series Index Reindexing Breaks Alignment
  description: Reindexing or resetting the DataFrame/Series index after computing technical indicators breaks temporal alignment
    with original price data and other features. This causes look-ahead bias, shifts indicator values to incorrect timestamps,
    and corrupts time-series datasets when used in backtesting or feature engineering pipelines.
  project_source: finance-bp-122--ta-python
  severity: high
  applicable_to_tags:
    markets:
    - multi-market
    activities:
    - technical-analysis
  _source_file: anti-patterns/technical-analysis.yaml
- id: AP-TECHNICAL-ANALYSIS-006
  title: NaN/Inf/Zero Propagation Corrupts Indicator Values
  description: Failing to clean input data of NaN, infinite values, or zero prices causes cascading corruption through rolling
    window calculations. Division-by-zero errors on zero prices produce NaN that propagates into all subsequent indicator
    values, corrupting entire datasets. Invalid values also cause incorrect boolean mask classifications when compared with
    np.inf directly.
  project_source: finance-bp-122--ta-python
  severity: high
  applicable_to_tags:
    markets:
    - multi-market
    activities:
    - technical-analysis
  _source_file: anti-patterns/technical-analysis.yaml
- id: AP-TECHNICAL-ANALYSIS-007
  title: EMA Smoothing Parameter Divergence from TA Standards
  description: Using pandas adjust=True (the default) for ewm() when implementing EMA-based indicators produces Yahoo Finance
    variant smoothing instead of standard recursive exponential smoothing per technical analysis textbooks. This causes different
    signal thresholds and divergence from widely-accepted indicator calculations, leading to inconsistent trading signals.
  project_source: finance-bp-122--ta-python
  severity: medium
  applicable_to_tags:
    markets:
    - multi-market
    activities:
    - technical-analysis
  _source_file: anti-patterns/technical-analysis.yaml
- id: AP-TECHNICAL-ANALYSIS-008
  title: 'False Claims: Indicator Calculation as Trading Signal'
  description: Presenting technical indicator values as real-time trading signals or guaranteed future performance misleads
    users about the tool's capabilities. The library calculates historical indicators from OHLCV data; claiming these as trading
    signals leads to improper trading decisions. Backtest results also do not guarantee future performance due to look-ahead
    bias and market regime changes.
  project_source: finance-bp-122--ta-python
  severity: high
  applicable_to_tags:
    markets:
    - multi-market
    activities:
    - technical-analysis
  _source_file: anti-patterns/technical-analysis.yaml
- id: AP-TECHNICAL-ANALYSIS-009
  title: Functional vs OOP API Implementation Divergence
  description: When both functional wrappers (e.g., rsi()) and OOP classes (e.g., RSIIndicator) are provided, diverging implementations
    produce different indicator values for the same inputs. This causes confusion, test failures, and breaks user code that
    expects consistent behavior across APIs. The functional wrapper must delegate to the class implementation to ensure equivalence.
  project_source: finance-bp-122--ta-python
  severity: medium
  applicable_to_tags:
    markets:
    - multi-market
    activities:
    - technical-analysis
  _source_file: anti-patterns/technical-analysis.yaml
- id: AP-TECHNICAL-ANALYSIS-010
  title: Bollinger Bands Using Sample Std Deviation
  description: Using pandas default ddof=1 (sample standard deviation) for Bollinger Bands produces wider bands than John
    Bollinger's original specification, which uses population standard deviation. This causes overestimation of volatility,
    incorrect trading signal thresholds, and divergence from the canonical indicator calculation that traders expect.
  project_source: finance-bp-122--ta-python
  severity: medium
  applicable_to_tags:
    markets:
    - multi-market
    activities:
    - technical-analysis
  _source_file: anti-patterns/technical-analysis.yaml
- id: AP-TECHNICAL-ANALYSIS-011
  title: Stale Cached Outputs Without Invalidation
  description: Caching computed indicator outputs without invalidating when inputs, parameters, or input_names change causes
    stale results to be returned even when underlying data has changed. This produces incorrect indicator values that silently
    propagate into trading strategies, leading to wrong signals based on outdated calculations.
  project_source: finance-bp-109--ta-lib-python
  severity: medium
  applicable_to_tags:
    markets:
    - multi-market
    activities:
    - technical-analysis
  _source_file: anti-patterns/technical-analysis.yaml
- id: AP-TECHNICAL-ANALYSIS-012
  title: Concurrent Access Without Thread-Local State
  description: Using shared Function instances across multiple threads without thread-local storage causes race conditions
    where concurrent threads share state. This leads to data corruption, incorrect results, and non-deterministic indicator
    values when multiple threads compute indicators simultaneously on the same instance.
  project_source: finance-bp-109--ta-lib-python
  severity: high
  applicable_to_tags:
    markets:
    - multi-market
    activities:
    - technical-analysis
  _source_file: anti-patterns/technical-analysis.yaml
- id: AP-TECHNICAL-ANALYSIS-013
  title: Using Python Lists Instead of NumPy Arrays for Stream Functions
  description: Stream functions require numpy.ndarray inputs due to direct C API access via PyArray_TYPE() and PyArray_FLAGS().
    Passing plain Python lists or other sequences causes runtime errors because the C layer cannot access the underlying C
    arrays. This breaks real-time indicator calculations that expect efficient numpy buffer access.
  project_source: finance-bp-109--ta-lib-python
  severity: medium
  applicable_to_tags:
    markets:
    - multi-market
    activities:
    - technical-analysis
  _source_file: anti-patterns/technical-analysis.yaml
- id: AP-TECHNICAL-ANALYSIS-014
  title: Library Not Initialized Before C Function Calls
  description: Calling TA-Lib C functions without prior library initialization returns TA_RetCode=1 (TA_LIB_NOT_INITIALIZE),
    causing all function calls to fail. This is a silent failure mode that produces no output indicators, breaking batch calculation
    pipelines unless the initialization step is explicitly performed before any function calls.
  project_source: finance-bp-109--ta-lib-python
  severity: high
  applicable_to_tags:
    markets:
    - multi-market
    activities:
    - technical-analysis
  _source_file: anti-patterns/technical-analysis.yaml
- id: AP-TECHNICAL-ANALYSIS-015
  title: Stateful Wrapper Functions Leak State Across Calls
  description: When functional wrapper functions retain internal state between calls, different input series contaminate each
    other's results through data leakage. This produces incorrect indicator values when the same wrapper function is called
    sequentially with different data, as cached state from previous calls affects new computations.
  project_source: finance-bp-122--ta-python
  severity: medium
  applicable_to_tags:
    markets:
    - multi-market
    activities:
    - technical-analysis
  _source_file: anti-patterns/technical-analysis.yaml
cross_project_wisdom:
- wisdom_id: CW-TECHNICAL-ANALYSIS-001
  source_project: finance-bp-109--ta-lib-python, finance-bp-122--ta-python
  pattern_name: Explicit Input Validation Before Computation
  description: 'Both projects require rigorous pre-computation validation: dtype checking (float64 for C FFI, numeric for
    pandas), dimension checking (1D arrays for C layer), and length validation. This defensive pattern prevents silent failures
    and memory corruption. Apply this pattern whenever interfacing with external C libraries or computing indicators on potentially
    malformed input data.'
  applicable_to_activity: technical-analysis
  _source_file: cross-project-wisdom/technical-analysis.yaml
- wisdom_id: CW-TECHNICAL-ANALYSIS-002
  source_project: finance-bp-109--ta-lib-python, finance-bp-122--ta-python
  pattern_name: Index Preservation Throughout Indicator Pipeline
  description: Preserving the original DataFrame/Series index without reindexing or reset is critical for temporal alignment.
    When constructing output Series, use index=self._close.index to maintain alignment with price data. This prevents look-ahead
    bias and ensures downstream features correctly reference their corresponding timestamps.
  applicable_to_activity: technical-analysis
  _source_file: cross-project-wisdom/technical-analysis.yaml
- wisdom_id: CW-TECHNICAL-ANALYSIS-003
  source_project: finance-bp-122--ta-python
  pattern_name: Data Cleaning Before Indicator Computation
  description: Indicators like RSI, MACD, and Bollinger Bands produce incorrect results when fed NaN, inf, or zero values.
    Remove rows with zero prices (to prevent division-by-zero), filter out infinite values using the exp(709) threshold as
    the maximum float64, and apply dropna to DataFrames before passing to indicator functions. This ensures clean propagation
    through rolling window calculations.
  applicable_to_activity: technical-analysis
  _source_file: cross-project-wisdom/technical-analysis.yaml
- wisdom_id: CW-TECHNICAL-ANALYSIS-004
  source_project: finance-bp-109--ta-lib-python
  pattern_name: Error Code Propagation from C to Python Layer
  description: Always call _ta_check_success and raise exceptions on non-zero TA_RetCode return values from C function calls.
    This pattern ensures that errors like uninitialized library, invalid parameters, or out-of-range inputs propagate as proper
    Python exceptions instead of silently producing garbage values. Never ignore return codes from the underlying C library.
  applicable_to_activity: technical-analysis
  _source_file: cross-project-wisdom/technical-analysis.yaml
- wisdom_id: CW-TECHNICAL-ANALYSIS-005
  source_project: finance-bp-109--ta-lib-python
  pattern_name: Thread-Local Storage for Concurrent Indicator Access
  description: When the same Function instance may be accessed from multiple threads, use thread-local storage to maintain
    isolated state per thread. This prevents race conditions, state corruption, and non-deterministic results when concurrent
    threads compute indicators simultaneously. The pattern is essential for any multi-threaded trading system or async processing
    pipeline.
  applicable_to_activity: technical-analysis
  _source_file: cross-project-wisdom/technical-analysis.yaml
- wisdom_id: CW-TECHNICAL-ANALYSIS-006
  source_project: finance-bp-122--ta-python
  pattern_name: Functional Wrapper Delegates to OOP Implementation
  description: Functional wrapper functions like rsi() and ema_indicator() should instantiate the corresponding Indicator
    class and call its result method, not reimplement logic. This ensures OOP and functional APIs produce identical outputs.
    Any divergence causes test failures and breaks user code that switches between API styles. Validate equivalence in test
    suites.
  applicable_to_activity: technical-analysis
  _source_file: cross-project-wisdom/technical-analysis.yaml
- wisdom_id: CW-TECHNICAL-ANALYSIS-007
  source_project: finance-bp-122--ta-python
  pattern_name: Standard TA Textbook Parameters for EMA Calculations
  description: When implementing EMA-based indicators, use adjust=False in pandas ewm() to match standard recursive exponential
    smoothing from technical analysis textbooks, not the Yahoo Finance variant. Also use ddof=0 for Bollinger Bands standard
    deviation per the original specification. Deviations produce different signal thresholds that diverge from what traders
    expect.
  applicable_to_activity: technical-analysis
  _source_file: cross-project-wisdom/technical-analysis.yaml
- wisdom_id: CW-TECHNICAL-ANALYSIS-008
  source_project: finance-bp-109--ta-lib-python
  pattern_name: Cache Invalidation on Any Input Change
  description: Set outputs_valid flag to False whenever inputs, parameters, or input_names change. This pattern prevents returning
    stale cached outputs when underlying data or parameters have been modified. Implement proper cache invalidation to ensure
    computed indicators always reflect the current state.
  applicable_to_activity: technical-analysis
  _source_file: cross-project-wisdom/technical-analysis.yaml
- wisdom_id: CW-TECHNICAL-ANALYSIS-009
  source_project: finance-bp-109--ta-lib-python, finance-bp-122--ta-python
  pattern_name: Library Initialization Before First Use
  description: Explicitly initialize the TA-Lib C library before any function calls. Without initialization, all function
    calls fail with TA_RetCode=1 (TA_LIB_NOT_INITIALIZE). This is a critical setup step that must be performed once before
    the indicator computation pipeline begins, typically at application startup or when first loading the library.
  applicable_to_activity: technical-analysis
  _source_file: cross-project-wisdom/technical-analysis.yaml
domain_constraints_injected: []
resources_injected: {}
known_use_cases:
- kuc_id: KUC-101
  source_file: docs/generate_html_pages.py
  business_problem: Converts TA-Lib markdown documentation into styled HTML pages for web publishing, and generates Pygments
    syntax highlighting CSS for code examples in documentation.
  intent_keywords:
  - documentation generation
  - html pages
  - pygments stylesheet
  - markdown to html
  - code highlighting
  stage: reporting
  data_domain: mixed
  type: reporting
component_capability_map:
  project: finance-bp-109--ta-lib-python
  scan_date: '2026-04-22'
  stats:
    total_files: 6
    total_classes: 23
    total_functions: 0
    total_stages: 6
  modules:
    c_library_binding_layer:
      class_count: 2
      stage_id: c_wrapper
      stage_order: 1
      responsibility: 'Provides low-level Cython bindings to the underlying TA-Lib C library with function signatures auto-generated
        from ta_func.h header files. WHY: Avoids SWIG overhead for 2-4x performance improvement over original Python bindings.'
      classes:
      - name: TA_RetCode enum access
        file: c_library_binding_layer/ta-retcode-enum-access.py
        line: 0
        kind: required_method
        signature: ''
      - name: Array validation
        file: c_library_binding_layer/array-validation.py
        line: 0
        kind: replaceable_point
      design_decision_count: 4
    function_api_(batch):
      class_count: 4
      stage_id: func_api
      stage_order: 2
      responsibility: 'Provides stateless, direct function calls for batch processing entire indicator over input arrays.
        WHY: Simple API for一次性 computation without state management, suitable for backtesting and batch analysis.'
      classes:
      - name: SMA.compute
        file: function_api_(batch)/sma-compute.py
        line: 0
        kind: required_method
        signature: ''
      - name: BBANDS.compute
        file: function_api_(batch)/bbands-compute.py
        line: 0
        kind: required_method
        signature: ''
      - name: ADX.compute
        file: function_api_(batch)/adx-compute.py
        line: 0
        kind: required_method
        signature: ''
      - name: Lookback padding
        file: function_api_(batch)/lookback-padding.py
        line: 0
        kind: replaceable_point
      design_decision_count: 4
    stream_api_(incremental):
      class_count: 4
      stage_id: stream_api
      stage_order: 3
      responsibility: 'Provides streaming functions that return single scalar values for real-time/online computation. WHY:
        For live trading systems where data arrives incrementally and only latest indicator value matters.'
      classes:
      - name: stream_MOM.execute
        file: stream_api_(incremental)/stream-mom-execute.py
        line: 0
        kind: required_method
        signature: ''
      - name: stream_CDL3BLACKCROWS.execute
        file: stream_api_(incremental)/stream-cdl3blackcrows-execute.py
        line: 0
        kind: required_method
        signature: ''
      - name: stream_SMA.execute
        file: stream_api_(incremental)/stream-sma-execute.py
        line: 0
        kind: required_method
        signature: ''
      - name: Streaming state
        file: stream_api_(incremental)/streaming-state.py
        line: 0
        kind: replaceable_point
      design_decision_count: 3
    abstract_api_(stateful):
      class_count: 7
      stage_id: abstract_api
      stage_order: 4
      responsibility: 'Object-oriented wrapper providing stateful Function instances with unified interface for setting inputs,
        parameters, and retrieving results. WHY: Simplifies complex functions like STOCH with multiple inputs/outputs and
        enables reusable function instances with caching.'
      classes:
      - name: Function.__call__
        file: abstract_api_(stateful)/function-call.py
        line: 0
        kind: required_method
        signature: ''
      - name: Function.set_input_arrays
        file: abstract_api_(stateful)/function-set-input-arrays.py
        line: 0
        kind: required_method
        signature: ''
      - name: SMA.invoke
        file: abstract_api_(stateful)/sma-invoke.py
        line: 0
        kind: required_method
        signature: ''
      - name: BBANDS.invoke
        file: abstract_api_(stateful)/bbands-invoke.py
        line: 0
        kind: required_method
        signature: ''
      - name: STOCH.invoke
        file: abstract_api_(stateful)/stoch-invoke.py
        line: 0
        kind: required_method
        signature: ''
      - name: Input data type
        file: abstract_api_(stateful)/input-data-type.py
        line: 0
        kind: replaceable_point
      - name: Input price series
        file: abstract_api_(stateful)/input-price-series.py
        line: 0
        kind: replaceable_point
      design_decision_count: 6
    series_support_layer:
      class_count: 2
      stage_id: series_wrapper
      stage_order: 5
      responsibility: 'Wraps each public functions to accept pandas/polars Series and return matching types. WHY: Users prefer
        working with labeled Series/DataFrames for financial data; automatic conversion improves usability without sacrificing
        performance.'
      classes:
      - name: _wrapper.decorate
        file: series_support_layer/wrapper-decorate.py
        line: 0
        kind: required_method
        signature: ''
      - name: Series type detection
        file: series_support_layer/series-type-detection.py
        line: 0
        kind: replaceable_point
      design_decision_count: 4
    code_generation:
      class_count: 4
      stage_id: code_generation
      stage_order: 6
      responsibility: 'Generates Cython code for _func.pxi and _stream.pxi from ta_func.h header file. WHY: 150+ functions;
        manual maintenance would be error-prone and tedious; ensures consistency with upstream TA-Lib changes.'
      classes:
      - name: generate_func.execute
        file: code_generation/generate-func-execute.py
        line: 0
        kind: required_method
        signature: ''
      - name: generate_stream.execute
        file: code_generation/generate-stream-execute.py
        line: 0
        kind: required_method
        signature: ''
      - name: generate_abstract_stub.execute
        file: code_generation/generate-abstract-stub-execute.py
        line: 0
        kind: required_method
        signature: ''
      - name: Name transformation rules
        file: code_generation/name-transformation-rules.py
        line: 0
        kind: replaceable_point
      design_decision_count: 4
  data_flow_hints: []
locale_contract:
  source_language: en
  user_facing_fields:
  - human_summary.what_i_can_do.tagline
  - human_summary.what_i_can_do.use_cases[]
  - human_summary.what_i_auto_fetch[]
  - human_summary.what_i_ask_you[]
  - evidence_quality.user_disclosure_template
  - post_install_notice.message_template.positioning
  - post_install_notice.message_template.capability_catalog.groups[].name
  - post_install_notice.message_template.capability_catalog.groups[].description
  - post_install_notice.message_template.capability_catalog.groups[].ucs[].name
  - post_install_notice.message_template.capability_catalog.groups[].ucs[].short_description
  - post_install_notice.message_template.call_to_action
  - post_install_notice.message_template.featured_entries[].beginner_prompt
  - post_install_notice.message_template.more_info_hint
  - preconditions[].description
  - preconditions[].on_fail
  - intent_router.uc_entries[].name
  - intent_router.uc_entries[].ambiguity_question
  - architecture.pipeline
  - architecture.stages[].narrative.does_what
  - architecture.stages[].narrative.key_decisions
  - architecture.stages[].narrative.common_pitfalls
  - constraints.fatal[].consequence
  - constraints.regular[].consequence
  - output_validator.assertions[].failure_message
  - acceptance.hard_gates[].on_fail
  - skill_crystallization.action
  locale_detection_order:
  - explicit_user_declaration
  - first_message_language
  - system_locale
  translation_enforcement:
    trigger: on_first_user_message
    action: Render user_facing_fields in detected locale, preserving all IDs (BD-/SL-/UC-/finance-C-) and code identifiers
      verbatim
    violation_code: LOCALE-01
    violation_signal: User receives untranslated English Human Summary when detected locale != en
evidence_quality:
  declared:
    evidence_coverage_ratio: 1.0
    evidence_verify_ratio: 0.45054945054945056
    evidence_invalid: 50
    evidence_verified: 41
    evidence_auto_fixed: 0
    audit_coverage: 45/45 (100%)
    audit_pass_rate: 0/45 (0%)
    audit_fail_total: 35
    audit_finance_universal:
      pass: 0
      warn: 5
      fail: 15
    audit_subdomain_totals:
      pass: 0
      warn: 5
      fail: 20
  enforcement_rules:
  - id: EQ-01
    trigger: declared.evidence_verify_ratio < 0.5
    action: MUST invoke traceback lookup for all cited BD-IDs in output before emitting business code — read LATEST.yaml sections
      for each BD referenced
    violation_code: EQ-01-V
    violation_signal: Generated script references BD-IDs but no tool_call to read LATEST.yaml preceded code generation
  user_disclosure_template: '[QUALITY NOTICE] This crystal was compiled from blueprint finance-bp-109. Evidence verify ratio
    = 45.1% and audit fail total = 35. Generated results may have uncaptured requirement gaps. Verify critical decisions against
    source files (LATEST.yaml / LATEST.jsonl).'
traceback:
  source_files:
    blueprint: LATEST.yaml
    constraints: LATEST.jsonl
  mandatory_lookup_scenarios:
  - id: TB-01
    condition: Two constraints have apparently conflicting enforcement rules
    lookup_target: LATEST.jsonl — find both constraint IDs, compare `consequence` + `evidence_refs` to determine priority
  - id: TB-02
    condition: A business decision rationale is unclear or disputed
    lookup_target: LATEST.yaml — locate BD-ID under business_decisions, read `rationale` + `alternative_considered` fields
  - id: TB-03
    condition: evidence_invalid > 0 in evidence_quality.declared
    lookup_target: LATEST.yaml _enrich_meta — cross-check specific BD `evidence_refs` fields for invalid markers
  - id: TB-04
    condition: User asks where a rule comes from
    lookup_target: LATEST.jsonl — find constraint by ID, read `confidence.evidence_refs` for source file + line number
  - id: TB-05
    condition: Generated code does not match expected ZVT API behavior
    lookup_target: LATEST.yaml stages[].required_methods — verify method signature and evidence locator in source code
  degraded_lookup:
    no_fs_access: 'Ask the user to paste the relevant LATEST.yaml section or LATEST.jsonl lines for the BD-/finance-C- IDs
      in question. Crystal ID: finance-bp-109-v5.0.'
trace_schema:
  event_types:
  - precondition_check
  - spec_lock_check
  - evidence_rule_fired
  - evidence_rule_skipped
  - locale_translation_emitted
  - hard_gate_passed
  - hard_gate_failed
  - skill_emitted
  - false_completion_claim
preconditions:
- id: PC-01
  description: zvt package installed and importable
  check_command: python3 -c 'import zvt; print(zvt.__version__)'
  on_fail: 'Run: python3 -m pip install zvt  then re-run: python3 -m zvt.init_dirs to initialize data directories'
  severity: fatal
- id: PC-02
  description: K-data exists for target entities (required before backtesting)
  check_command: python3 -c "from zvt.api.kdata import get_kdata; df = get_kdata(entity_ids=['stock_sh_600000'], limit=1);
    assert df is not None and len(df) > 0, 'No kdata found'"
  on_fail: 'Run recorder first: python3 -m zvt.recorders.em.em_stock_kdata_recorder --entity_ids stock_sh_600000  (replace
    with your target entity IDs)'
  severity: fatal
  applies_to_uc:
  - UC-101
- id: PC-03
  description: ZVT data directory initialized (~/.zvt or ZVT_HOME)
  check_command: 'python3 -c "import os; from pathlib import Path; zvt_home = Path(os.environ.get(''ZVT_HOME'', Path.home()
    / ''.zvt'')); assert zvt_home.exists(), f''ZVT home not found: {zvt_home}''"'
  on_fail: 'Run: python3 -m zvt.init_dirs'
  severity: fatal
- id: PC-04
  description: SQLite write permission for ZVT data directory
  check_command: python3 -c "import os, tempfile; from pathlib import Path; zvt_home = Path(os.environ.get('ZVT_HOME', Path.home()
    / '.zvt')); test_f = zvt_home / '.write_test'; test_f.touch(); test_f.unlink()"
  on_fail: 'Check directory permissions: chmod u+w ~/.zvt  or set ZVT_HOME environment variable to a writable location'
  severity: warn
intent_router:
  uc_entries:
  - uc_id: UC-101
    name: TA-Lib Documentation HTML Generator
    positive_terms:
    - documentation generation
    - html pages
    - pygments stylesheet
    - markdown to html
    - code highlighting
    data_domain: mixed
    negative_terms:
    - trading strategy
    - backtesting
    - factor computation
    - market data
    - stock screening
    - live trading
    ambiguity_question: Are you looking to generate documentation/build pages, or are you trying to implement or analyze trading
      strategies?
context_state_machine:
  states:
  - id: CA1_MEMORY_CHECKED
    entry: Task started
    exit: All memory queries attempted and recorded; memory_unavailable set if failed
    timeout: 30s — skip memory, mark memory_unavailable=true, proceed to CA2
  - id: CA2_GAPS_FILLED
    entry: CA1 complete
    exit: 'All FATAL-priority required inputs answered: target market (A-share/HK/US), data source, time range, strategy type'
    timeout: NOT skippable — FATAL inputs MUST be user-answered before proceeding
  - id: CA3_PATH_SELECTED
    entry: CA2 complete
    exit: intent_router matched single use case with confidence gap > 20% over next candidate, no data_domain ambiguity
    timeout: Trigger ambiguity_question for top-2 candidates, await user selection
  - id: CA4_EXECUTING
    entry: CA3 complete + user explicit confirmation received
    exit: All hard gates G1-Gn passed and output files written
    timeout: NOT skippable — user confirmation of execution path required
  enforcement: Code generation is PROHIBITED before CA4_EXECUTING. Any regression to earlier state MUST be announced to user.
    buy/sell ordering SL-01 check runs at CA4 entry.
spec_lock_registry:
  semantic_locks:
  - id: SL-01
    description: Execute sell orders before buy orders in every trading cycle
    locked_value: sell() called before buy() in each Trader.run() iteration
    violation_is: fatal
    source_bd_ids:
    - BD-018
  - id: SL-02
    description: Trading signals MUST use next-bar execution (no look-ahead)
    locked_value: due_timestamp = happen_timestamp + level.to_second()
    violation_is: fatal
    source_bd_ids:
    - BD-014
    - BD-025
  - id: SL-03
    description: Entity IDs MUST follow format entity_type_exchange_code
    locked_value: stock_sh_600000 | stockhk_hk_0700 | stockus_nasdaq_AAPL
    violation_is: fatal
    source_bd_ids: []
  - id: SL-04
    description: DataFrame index MUST be MultiIndex (entity_id, timestamp)
    locked_value: df.index.names == ['entity_id', 'timestamp']
    violation_is: fatal
    source_bd_ids: []
  - id: SL-05
    description: 'TradingSignal MUST have EXACTLY ONE of: position_pct, order_money, order_amount'
    locked_value: XOR enforcement in trading/__init__.py:68
    violation_is: fatal
    source_bd_ids: []
  - id: SL-06
    description: 'filter_result column semantics: True=BUY, False=SELL, None/NaN=NO ACTION'
    locked_value: factor.py:475 order_type_flag mapping
    violation_is: fatal
    source_bd_ids: []
  - id: SL-07
    description: Transformer MUST run BEFORE Accumulator in factor pipeline
    locked_value: 'compute_result(): transform at :403 before accumulator at :409'
    violation_is: fatal
    source_bd_ids: []
  - id: SL-08
    description: 'MACD parameters locked: fast=12, slow=26, signal=9'
    locked_value: factors/algorithm.py:30 macd(slow=26, fast=12, n=9)
    violation_is: fatal
    source_bd_ids:
    - BD-036
  - id: SL-09
    description: 'Default transaction costs: buy_cost=0.001, sell_cost=0.001, slippage=0.001'
    locked_value: sim_account.py:25 SimAccountService default costs
    violation_is: warning
    source_bd_ids:
    - BD-029
  - id: SL-10
    description: A-share equity trading is T+1 (no same-day close of buy positions)
    locked_value: sim_account.available_long filters by trading_t
    violation_is: fatal
    source_bd_ids: []
  - id: SL-11
    description: Recorder subclass MUST define provider AND data_schema class attributes
    locked_value: contract/recorder.py:71 Meta; register_schema decorator
    violation_is: fatal
    source_bd_ids: []
  - id: SL-12
    description: Factor result_df MUST contain either 'filter_result' OR 'score_result' column
    locked_value: result_df.columns.intersection({'filter_result', 'score_result'}) non-empty
    violation_is: fatal
    source_bd_ids: []
  implementation_hints:
  - id: IH-01
    hint: 'Use AdjustType enum exactly: qfq (pre-adjust), hfq (post-adjust), bfq (none) — contract/__init__.py:121'
  - id: IH-02
    hint: For A-share kdata, default to hfq for long-term analysis (dividend-adjusted) — trader.py:538 StockTrader
  - id: IH-03
    hint: SQLite connection MUST use check_same_thread=False for multi-threaded recorders
  - id: IH-04
    hint: Accumulator state serialization uses JSON with custom encoder/decoder hooks — contract/base_service.py
  - id: IH-05
    hint: Factor.level MUST match TargetSelector.level (enforced at add_factor) — factors/target_selector.py:84
preservation_manifest:
  required_objects:
    business_decisions_count: 104
    fatal_constraints_count: 27
    non_fatal_constraints_count: 147
    use_cases_count: 1
    semantic_locks_count: 12
    preconditions_count: 4
    evidence_quality_rules_count: 2
    traceback_scenarios_count: 5
architecture:
  pipeline: data_collection -> data_storage -> factor_computation -> target_selection -> trading_execution -> visualization
  stages:
  - id: data_collection
    narrative:
      does_what: TimeSeriesDataRecorder and FixedCycleDataRecorder fetch OHLCV and fundamental data from providers (eastmoney,
        joinquant, baostock, akshare) and persist domain objects (Stock1dKdata, BalanceSheet) to SQLite via df_to_db().
      key_decisions: BD-002 chose evaluate_start_end_size_timestamps for incremental fetch (not full refresh) because comparing
        to get_latest_saved_record avoids redundant API calls; BD-003 chose get_data_map field transformation to keep domain
        schema provider-agnostic.
      common_pitfalls: 'Don''t forget SL-11: Recorder subclass MUST declare both provider and data_schema class attributes
        else initialization fails with assertion error; finance-C-001 fatal violation.'
    business_decisions: []
  - id: data_storage
    narrative:
      does_what: StorageBackend persists DataFrames to per-provider SQLite databases at {data_path}/{provider}/{provider}_{db_name}.db
        using path templates from _get_path_template; Mixin.record_data and Mixin.query_data provide uniform read/write interface.
      key_decisions: BD-004 chose StorageBackend abstraction (not hardcoded SQLite) to allow future cloud storage swap; BD-006
        derives db_name from data_schema __tablename__ for per-domain database isolation.
      common_pitfalls: SL-04 violation (wrong DataFrame index) causes factor pipeline failures downstream; always ensure df.index.names
        == ['entity_id', 'timestamp'] before calling record_data.
    business_decisions: []
  - id: factor_computation
    narrative:
      does_what: Factor.compute() applies Transformer (stateless, e.g. MacdTransformer) then Accumulator (stateful, e.g. MaStatsAccumulator)
        to produce filter_result or score_result columns; EntityStateService persists per-entity rolling state across batches.
      key_decisions: BD-007 chose Factor inheriting DataReader for composable data access; SL-08 locks MACD at (fast=12, slow=26,
        n=9) — chose standard Appel parameters not adaptive because interpretability matters for practitioners.
      common_pitfalls: 'SL-07: Transformer MUST run before Accumulator — swapping order causes NaN propagation; SL-12: result_df
        must contain filter_result OR score_result column or TargetSelector silently drops all signals.'
    business_decisions: []
  - id: target_selection
    narrative:
      does_what: TargetSelector.add_factor() registers Factor instances; get_targets() returns entity_ids passing threshold
        filter at a specific timestamp, enabling point-in-time historical backtesting without look-ahead.
      key_decisions: BD-012 chose registrable factor list (not hardcoded) for runtime customization; BD-013 chose timestamp-specific
        filtering not current-only because backtests need historical point-in-time correctness.
      common_pitfalls: Factor.level MUST match TargetSelector.level (IH-05); mismatched levels cause silent empty target lists
        that look like no signals but are actually level-mismatch bugs.
    business_decisions: []
  - id: trading_execution
    narrative:
      does_what: Trader.run() calls sell() before buy() each cycle, generates TradingSignals with due_timestamp = happen_timestamp
        + level.to_second() for next-bar execution, and applies on_profit_control() for stop-loss/take-profit before regular
        target selection.
      key_decisions: SL-01 locks sell-before-buy order because available_long check in sim_account depends on it — chose this
        over symmetric ordering to prevent implicit leverage; BD-039 chose long=AND/short=OR multi-level logic to reflect
        risk asymmetry.
      common_pitfalls: 'SL-02 violation (immediate execution instead of next-bar) introduces look-ahead bias and makes backtest
        results unreproducible in live trading; SL-10: A-share T+1 constraint — backtesting without it overstates returns.'
    business_decisions: []
  - id: visualization
    narrative:
      does_what: Drawer.draw() combines kline main chart with factor overlays and Rect annotations for entry/exit signals
        using Plotly; Drawable interface on Factor enables consistent chart rendering across data types.
      key_decisions: BD-019 chose drawer_rects subclass override for custom annotations not hardcoded markers — allows traders
        to define entry/exit visuals without modifying base drawing logic.
      common_pitfalls: draw_result=True by default (BD-055) is fine for development but set draw_result=False in production/headless
        environments to avoid Plotly server startup overhead.
    business_decisions: []
  - id: cross_cutting_concerns
    narrative:
      does_what: 'Invariants and utilities that span multiple pipeline stages — collected from 30 source groups: abstract_api(5),
        architecture(1), c_wrapper(6), calculation(1), code_generation(3), compatibility(1), and 24 more.'
      key_decisions: 104 BDs merged here because they apply to more than one main stage (e.g. algorithm helpers, default value
        choices, ordering contracts, error handling). Agent should inspect individual BD summaries and link back to affected
        main stages via shared IDs.
      common_pitfalls: Cross-cutting concerns frequently surface as bugs when changes to one main stage unintentionally break
        another. Check constraints referencing these BDs and verify invariants still hold after any stage-local modification.
    business_decisions:
    - id: BD-010
      type: B
      summary: Thread-local storage per Function instance
    - id: BD-011
      type: B
      summary: Output caching via outputs_valid dirty flag
    - id: BD-012
      type: B/BA
      summary: Price series default mapping via __INPUT_PRICE_SERIES_DEFAULTS
    - id: BD-013
      type: BA
      summary: Subclassable set_input_arrays for custom data types
    - id: BD-014
      type: B
      summary: Parameter validation with explicit type checking
    - id: BD-022
      type: B
      summary: Use Cython instead of SWIG for Python bindings to TA-Lib C library
    - id: BD-001
      type: B
      summary: Cython chosen over SWIG for Python bindings
    - id: BD-002
      type: B
      summary: Array type validation at API boundary
    - id: BD-003
      type: B/BA
      summary: Integer default sentinel maps to TA_INTEGER_DEFAULT (-2^31)
    - id: BD-004
      type: BA
      summary: Auto-generated Python bindings from ta_func.h header
    - id: BD-GAP-001
      type: B
      summary: 'Missing: /N/A:** 15 ()'
    - id: BD-GAP-002
      type: RC
      summary: 'Missing: Add precision limitations section to README documenting that each calculations use float64 (C double)
        and are unsuitable for fixed income pricing, currency handling, or any use case requiring'
    - id: BD-054
      type: B
      summary: Return lookback = timeperiod-1 for SMA, computed dynamically per parameters
    - id: BD-019
      type: BA
      summary: Build-time C header parsing for code generation
    - id: BD-020
      type: B/BA
      summary: Pythonic name transformation for C parameter names
    - id: BD-021
      type: B
      summary: Filter non-indicator functions from code generation
    - id: BD-051
      type: B/RC
      summary: Use Python 2/3 compatible exception handling for optional imports
    - id: BD-029
      type: B/BA
      summary: Provide set_unstable_period() to configure convergence behavior of adaptive indicators
    - id: BD-030
      type: B
      summary: Provide set_compatibility() to match other TA library behaviors (0=TA-Lib, 1=S&A)
    - id: BD-044
      type: B/BA
      summary: Support candle settings customization for pattern recognition
    - id: BD-080
      type: BA
      summary: Default price series mapping hardcodes 'close' as default for each price-based functions
    - id: BD-085
      type: DK/B
      summary: Lookback period pre-filled with NaN values in output arrays before calculation
    - id: BD-087
      type: BA
      summary: Input array length equality enforced before any calculation via check_length* functions
    - id: BD-088
      type: DK
      summary: Function name normalization to uppercase - 'sma' and 'SMA' both work identically
    - id: BD-092
      type: BA
      summary: 'Double-precision enforcement: input arrays must be NPY_DOUBLE type and C-contiguous'
    - id: BD-040
      type: B/BA
      summary: Default price input for single-price functions is 'close' series
    - id: BD-046
      type: B/BA
      summary: Define default timeperiod=14 for RSI, timeperiod=30 for many MAs
    - id: BD-005
      type: B
      summary: NaN padding for lookback period in batch functions
    - id: BD-006
      type: B/BA
      summary: 'Index convention: endIdx as length-1 (zero-based last element)'
    - id: BD-007
      type: B/BA
      summary: No implicit input defaults - each price arrays required
    - id: BD-032
      type: B
      summary: Provide both Function API (stateless) and Abstract API (stateful) interfaces
    - id: BD-042
      type: B/BA
      summary: Define function name lookup as case-insensitive (uppercase internally)
    - id: BD-048
      type: B/BA
      summary: Allow setting input price series via price='open' kwarg in Abstract API
    - id: BD-028
      type: B
      summary: Define 9 moving average types (SMA, EMA, WMA, DEMA, TEMA, TRIMA, KAMA, MAMA, T3)
    - id: BD-035
      type: B
      summary: Provide streaming versions (stream_*) of each 161 functions for incremental processing
    - id: BD-038
      type: B/RC
      summary: Implement 61 candlestick pattern recognition functions (CDL*)
    - id: BD-052
      type: B
      summary: Support variable period MAVP function with minperiod/maxperiod bounds
    - id: BD-095
      type: B/BA
      summary: 'INTERACTION: BD-010 (Thread-local storage) × BD-074 (Deep copy for thread safety) → Thread safety strategy
        contradiction'
    - id: BD-096
      type: BA
      summary: 'INTERACTION: BD-091 (Generated code from C headers) × BD-004 (Auto-generated Python bindings) × BD-019 (Build-time
        C header parsing) → Risk cascade on build pipeline'
    - id: BD-097
      type: B
      summary: 'INTERACTION: BD-092 (NPY_DOUBLE and C-contiguous requirement) × BD-015 (Lazy dependency detection) → Performance
        risk in DataFrame path'
    - id: BD-098
      type: BA
      summary: 'INTERACTION: BD-085 (NaN pre-fill for lookback) × BD-090 (NaN propagation differs from pandas) → Behavioral
        surprise risk cascade'
    - id: BD-099
      type: B/BA
      summary: 'INTERACTION: BD-081 (Import-time singleton init) × BD-093 (Unstable period ordering) × BD-029 (set_unstable_period)
        → Hidden state dependency in configuration'
    - id: BD-100
      type: B/BA
      summary: 'INTERACTION: BD-087 (Array length validation) × BD-084 (Output type preservation) → Validation failure prevents
        type preservation'
    - id: BD-101
      type: B
      summary: 'INTERACTION: BD-016 (Polars/pandas mutual exclusion) × BD-037 (Raise exception on mixing) → Confirmed redundant
        constraint with ambiguous scope'
    - id: BD-102
      type: BA/DK
      summary: 'INTERACTION: BD-054 (Dynamic lookback computation) × BD-006 (endIdx as length-1 convention) → Risk cascade
        on index boundary calculations'
    - id: BD-043
      type: B/BA
      summary: Use make_double_array() to pre-fill output arrays with NaN up to lookback
    - id: BD-089
      type: DK/B
      summary: MA_Type implemented as singleton class instance not Python Enum
    - id: BD-024
      type: B
      summary: Wrap each TA-Lib functions to support pandas.Series and polars.Series input
    - id: BD-025
      type: B
      summary: Convert each input data to float64 numpy arrays before calling C functions
    - id: BD-055
      type: B
      summary: Support pandas.DataFrame column access by name in Abstract API
    - id: BD-081
      type: RC
      summary: Import-time singleton initialization with atexit shutdown required before any function calls
    - id: BD-083
      type: T
      summary: Polars and Pandas cannot be mixed - mutual exclusion enforced at runtime
    - id: BD-090
      type: BA
      summary: NaN handling propagates to end of output in TA-Lib (different from pandas rolling)
    - id: BD-023
      type: B/BA
      summary: Initialize TA-Lib on module import and register shutdown on process exit
    - id: BD-049
      type: B
      summary: Use @wraps decorator on wrapper to preserve function metadata
    - id: BD-056
      type: B
      summary: Define TA_FUNC_FLAGS including 'Function has an unstable period'
    - id: BD-039
      type: B
      summary: Use int32 for integer outputs (patterns, indices) to reduce memory
    - id: BD-086
      type: B/BA
      summary: Parameter state restoration after __call__ ensures no permanent state change per invocation
    - id: BD-093
      type: T
      summary: Unstable period setting must precede indicator calculation for effect
    - id: BD-031
      type: B/RC
      summary: 'Organize 161 functions into 10 groups: Overlap, Momentum, Volume, Volatility, Pattern, etc.'
    - id: BD-026
      type: B/BA
      summary: Return Series/DataFrame when input is Series/DataFrame (preserve type)
    - id: BD-027
      type: B/BA
      summary: Use NaN to fill lookback period in output arrays
    - id: BD-034
      type: B/BA
      summary: Store lookback period NaN values as 0 in integer output arrays
    - id: BD-041
      type: B/RC
      summary: Preserve pandas index when converting back to Series output
    - id: BD-050
      type: B
      summary: Check for streaming result by testing if first result lacks __len__
    - id: BD-082
      type: B
      summary: Thread-local storage used in Abstract Function for per-thread state isolation
    - id: BD-084
      type: BA
      summary: 'Output type preservation pattern: DataFrame→DataFrame, Series→Series, ndarray→ndarray'
    - id: BD-091
      type: T
      summary: 'Generated code pattern: _func.pxi and _stream.pxi auto-generated from C headers'
    - id: BD-015
      type: BA
      summary: Lazy optional dependency detection for pandas and polars
    - id: BD-016
      type: B
      summary: 'Mutual exclusion: cannot mix polars and pandas in single call'
    - id: BD-017
      type: B/DK
      summary: Preserve pandas index through computation
    - id: BD-018
      type: B
      summary: Identity passthrough wrapper when no pandas/polars available
    - id: BD-008
      type: B
      summary: Single scalar output for stream/incremental processing
    - id: BD-009
      type: BA
      summary: Unified function signatures between batch and stream APIs
    - id: BD-094
      type: T
      summary: tools/generate_abstract_stub.py creates type stubs using runtime introspection
    - id: BD-057
      type: B
      summary: Float64 conversion for pandas/polars Series before calling C library
    - id: BD-058
      type: B/BA
      summary: Default SMA parameters for Stochastic Oscillator slowK
    - id: BD-059
      type: B/BA
      summary: Default SMA parameters for Stochastic Oscillator slowD
    - id: BD-060
      type: B/BA
      summary: EMA-based Bollinger Bands parameters
    - id: BD-061
      type: B/BA
      summary: Default RSI timeperiod for Stochastic RSI info
    - id: BD-062
      type: B
      summary: MAVP variable period range configuration
    - id: BD-063
      type: B/BA
      summary: Default SMA timeperiod for MAVP min/max bounds
    - id: BD-064
      type: B/DK
      summary: MIN/MAX sliding window timeperiod
    - id: BD-065
      type: B/DK
      summary: Momentum timeperiod for rate-of-change calculation
    - id: BD-066
      type: B
      summary: EMA smoothing parameters for STOCHRSI fastD
    - id: BD-067
      type: B/BA
      summary: STOCHRSI default parameters for RSI and Stochastic
    - id: BD-068
      type: B/DK
      summary: EMA timeperiod for double smoothing test
    - id: BD-069
      type: B
      summary: RSI Wilder smoothing timeperiod
    - id: BD-070
      type: B/BA
      summary: Set compatibility mode to 0 (default) vs 1
    - id: BD-071
      type: B
      summary: Set unstable period for EMA convergence
    - id: BD-072
      type: B/DK
      summary: TEMA triple exponential smoothing timeperiod
    - id: BD-073
      type: B/DK
      summary: ATR true range calculation timeperiod
    - id: BD-074
      type: B
      summary: Deep copy for thread-safe data manipulation
    - id: BD-075
      type: B/BA
      summary: BBANDS default Bollinger Bands parameters
    - id: BD-076
      type: B/BA
      summary: Candlestick CDL3BLACKCROWS pattern detection
    - id: BD-077
      type: B/DK
      summary: MAXINDEX rolling maximum position index
    - id: BD-078
      type: B/BA
      summary: Expected number of TA-Lib functions
    - id: BD-079
      type: B
      summary: NaN propagation for missing values
    - id: BD-045
      type: B
      summary: Test with Ford Motor Company 2012 stock data as fixture
    - id: BD-033
      type: B
      summary: Use threading.local() for per-thread state in Abstract Function class
    - id: BD-053
      type: B
      summary: Allow concurrent thread access via thread-local storage in Abstract API
    - id: BD-036
      type: B
      summary: Validate input arrays are float64 type and C-contiguous before processing
    - id: BD-037
      type: B
      summary: Raise exception when mixing polars and pandas inputs
    - id: BD-047
      type: B
      summary: Raise TypeError for invalid parameter types (float for int parameter)
resources:
  packages:
  - name: numpy
    version_pin: latest
  - name: TA-Lib C library (libta-lib / ta-lib-static)
    version_pin: latest
  - name: Cython
    version_pin: latest
  - name: build
    version_pin: latest
  - name: pandas
    version_pin: latest
  - name: polars
    version_pin: latest
  - name: pytest
    version_pin: latest
  - name: setuptools
    version_pin: latest
  - name: wheel
    version_pin: latest
  - name: cibuildwheel
    version_pin: latest
  strategy_scaffold:
    entry_point_name: run_backtest
    output_path: result.csv
    execution_mode: backtest
    conditional_entry_points:
      backtest:
        entry_point_name: run_backtest
        output_path: result.csv
      collector:
        entry_point_name: run_collector
        output_path: result.json
      factor:
        entry_point_name: run_factor
        output_path: result.parquet
      training:
        entry_point_name: run_training
        output_path: result.json
      serving:
        entry_point_name: run_server
        output_path: result.json
      research:
        entry_point_name: run_research
        output_path: result.json
    tail_template: "# === DO NOT MODIFY BELOW THIS LINE ===\nif __name__ == \"__main__\":\n    result = run_backtest()  #\
      \ implement above\n    from validate import enforce_validation\n    enforce_validation(result, output_path=\"{workspace}/result.csv\"\
      )\n# === END DO NOT MODIFY ==="
  host_adapter:
    target: openclaw
    timeout_seconds: 1800
    shell_operator_restriction: 'exec tool intercepts && / ; / | — never chain: ''pip install X && python Y''. Use separate
      exec calls.'
    install_recipes:
    - python3 -m pip install numpy
    - python3 -m pip install TA-Lib C library (libta-lib / ta-lib-static)
    - python3 -m pip install Cython
    - python3 -m pip install zvt
    credential_injection: JoinQuant/QMT credentials require user-side '!' prefix shell login. Never hardcode credentials in
      generated scripts.
    path_resolution: '{workspace} resolves to ~/.openclaw/workspace/doramagic at execution time.'
    file_io_tooling: Use openclaw 'write' tool for .py/.sql files; 'exec' tool for python3 /absolute/path/script.py (absolute
      paths only).
constraints:
  fatal:
  - id: finance-C-001
    when: When calling check_array on input numpy arrays before C function invocation
    action: validate array dtype is NPY_DOUBLE (float64) and raise Exception for non-double arrays
    severity: fatal
    kind: domain_rule
    modality: must
    consequence: Passing non-float64 arrays to TA-Lib C functions causes memory corruption or incorrect calculations due to
      type mismatch in the C FFI layer
    stage_ids:
    - c_wrapper
  - id: finance-C-002
    when: When validating input array dimensions before C function calls
    action: enforce input arrays have exactly 1 dimension (ndim == 1)
    severity: fatal
    kind: domain_rule
    modality: must
    consequence: Multidimensional arrays passed to TA-Lib C functions cause memory access violations and segmentation faults
      due to incorrect stride calculations
    stage_ids:
    - c_wrapper
  - id: finance-C-003
    when: When checking TA_RetCode return values from C function calls
    action: call _ta_check_success and raise Exception on non-zero (failure) return codes
    severity: fatal
    kind: domain_rule
    modality: must
    consequence: Ignoring TA_RetCode errors silently propagates invalid computation results, leading to incorrect technical
      indicator values in trading strategies
    stage_ids:
    - c_wrapper
  - id: finance-C-004
    when: When validating array lengths for multi-input functions
    action: check each input arrays have identical length and raise Exception on mismatch
    severity: fatal
    kind: domain_rule
    modality: must
    consequence: Mismatched array lengths cause out-of-bounds memory access when TA-Lib iterates over arrays of different
      sizes
    stage_ids:
    - c_wrapper
  - id: finance-C-016
    when: When implementing batch indicator calculations using the func API
    action: Verify each input price arrays have float64 dtype (NPY_DOUBLE)
    severity: fatal
    kind: domain_rule
    modality: must
    consequence: Integer dtype input arrays cause runtime exceptions in the underlying TA-Lib C library, as demonstrated in
      test_func.py:17-20 where func.MOM(a1) raises Exception when a1 is np.arange(10, dtype=int)
    stage_ids:
    - func_api
  - id: finance-C-017
    when: When implementing batch indicator calculations using the func API
    action: Verify each input arrays are 1-dimensional
    severity: fatal
    kind: domain_rule
    modality: must
    consequence: Multi-dimensional arrays cause runtime exceptions, as real.ndim != 1 raises an exception in the check_array
      function
    stage_ids:
    - func_api
  - id: finance-C-018
    when: When implementing batch indicator calculations with multiple price inputs
    action: Verify each input price arrays have identical lengths
    severity: fatal
    kind: domain_rule
    modality: must
    consequence: Mismatched array lengths cause runtime exceptions, breaking the batch calculation pipeline as verified in
      test_func.py:23-33
    stage_ids:
    - func_api
  - id: finance-C-019
    when: When implementing batch indicator calculations using the func API
    action: Provide each required price arrays explicitly without relying on defaults
    severity: fatal
    kind: architecture_guardrail
    modality: must
    consequence: The func API has no default values for price arrays; all required arrays must be provided as positional or
      keyword arguments
    stage_ids:
    - func_api
  - id: finance-C-027
    when: When implementing batch indicator calculations using the func API
    action: Call the TA-Lib C library initialization before any function calls
    severity: fatal
    kind: resource_boundary
    modality: must
    consequence: Without initialization, TA_RetCode=1 (TA_LIB_NOT_INITIALIZE) is returned, causing all function calls to fail
    stage_ids:
    - func_api
  - id: finance-C-029
    when: When implementing stream function inputs
    action: pass numpy arrays with dtype=float64 (NPY_DOUBLE) to stream functions
    severity: fatal
    kind: domain_rule
    modality: must
    consequence: Stream functions raise 'input array type is not double' exception when passed non-double precision arrays,
      causing data loss or incorrect calculations in financial indicators
    stage_ids:
    - stream_api
  - id: finance-C-030
    when: When implementing stream function inputs
    action: pass 1-dimensional numpy arrays to stream functions
    severity: fatal
    kind: domain_rule
    modality: must
    consequence: Stream functions raise 'input array has wrong dimensions' exception when passed multi-dimensional arrays,
      breaking real-time indicator calculations
    stage_ids:
    - stream_api
  - id: finance-C-031
    when: When implementing stream functions with multiple price inputs
    action: pass input arrays of identical length to stream functions
    severity: fatal
    kind: domain_rule
    modality: must
    consequence: Stream functions raise 'input array lengths are different' exception when arrays mismatch, causing incorrect
      indicator values
    stage_ids:
    - stream_api
  - id: finance-C-034
    when: When calling stream functions
    action: use numpy.ndarray inputs (not plain Python lists or other sequences)
    severity: fatal
    kind: resource_boundary
    modality: must
    consequence: Stream functions require numpy arrays due to direct C API access via PyArray_TYPE() and PyArray_FLAGS(),
      causing runtime errors with non-array inputs
    stage_ids:
    - stream_api
  - id: finance-C-046
    when: When using the same Function instance across multiple threads
    action: use thread-local storage to maintain isolated state per thread
    severity: fatal
    kind: architecture_guardrail
    modality: must
    consequence: Without thread-local storage, concurrent threads would share state causing race conditions, incorrect results,
      and data corruption
    stage_ids:
    - abstract_api
  - id: finance-C-048
    when: When invalidating cached outputs
    action: set outputs_valid flag to False whenever inputs, parameters, or input_names change
    severity: fatal
    kind: architecture_guardrail
    modality: must
    consequence: Stale cached outputs would be returned even when underlying data or parameters have changed, producing incorrect
      results
    stage_ids:
    - abstract_api
  - id: finance-C-058
    when: When retrieving outputs from Function
    action: convert pandas.Series and polars.Series to numpy arrays before passing to TALIB
    severity: fatal
    kind: domain_rule
    modality: must
    consequence: Native pandas/polars Series objects would cause type errors in TALIB C function calls expecting numpy arrays
    stage_ids:
    - abstract_api
  - id: finance-C-059
    when: When implementing SMA or other TA-Lib functions to accept pandas Series input
    action: Return pandas.Series with the same index preserved from the input Series
    severity: fatal
    kind: domain_rule
    modality: must
    consequence: Breaking pandas index preservation causes downstream code to lose temporal alignment, leading to incorrect
      backtest results and misaligned signal generation
    stage_ids:
    - series_wrapper
  - id: finance-C-060
    when: When converting pandas or polars Series to numpy arrays for TA-Lib processing
    action: Apply astype(float) to the converted numpy array to verify numeric compatibility
    severity: fatal
    kind: domain_rule
    modality: must
    consequence: TA-Lib C library requires float64 input; non-float arrays cause segmentation faults or incorrect calculations
      in technical indicators
    stage_ids:
    - series_wrapper
  - id: finance-C-062
    when: When both polars Series and pandas Series are detected in function arguments
    action: Mix polars and pandas types in the same function call
    severity: fatal
    kind: domain_rule
    modality: must_not
    consequence: Mixed type processing creates ambiguity in output type selection and index handling, causing TypeError or
      incorrect result types in downstream code
    stage_ids:
    - series_wrapper
  - id: finance-C-069
    when: When generating Cython function bindings for TA-Lib
    action: Use double precision (NPY_DOUBLE) for each numeric array type checks
    severity: fatal
    kind: domain_rule
    modality: must
    consequence: Using float32 or other numeric types causes memory corruption and incorrect calculation results since TA-Lib
      internally uses double precision
    stage_ids:
    - code_generation
  - id: finance-C-070
    when: When validating input arrays in generated Cython functions
    action: Check that input arrays are C-contiguous and convert if necessary
    severity: fatal
    kind: domain_rule
    modality: must
    consequence: Non-C-contiguous arrays cause pointer arithmetic errors when accessing data pointers, leading to segmentation
      faults or corrupted output
    stage_ids:
    - code_generation
  - id: finance-C-075
    when: When regenerating code bindings
    action: Require ta-lib/ta_func.h header file to exist in one of the configured include paths
    severity: fatal
    kind: resource_boundary
    modality: must
    consequence: Code generation fails silently or produces incomplete bindings without the header file, breaking the build
      process
    stage_ids:
    - code_generation
  - id: finance-C-105
    when: When implementing or writing code that calls TA-Lib functions with multiple price arrays
    action: Verify each input price arrays have identical lengths — the Cython wrapper enforces length equality via check_length*
      functions
    severity: fatal
    kind: domain_rule
    modality: must
    consequence: Array length mismatch raises Exception('input array lengths are different'), causing function calls to fail
      with misleading error messages
  - id: finance-C-112
    when: When presenting or reporting TA-Lib indicator calculations to users or making capability claims
    action: Claim that TA-Lib technical indicators predict future prices, trends, or market movements — TA-Lib is a historical
      calculation library that computes past values from price data
    severity: fatal
    kind: claim_boundary
    modality: must_not
    consequence: Users allocate capital based on false prediction claims, experiencing financial loss when historical indicator
      patterns fail to predict future market behavior
  - id: finance-C-115
    when: When presenting or reporting TA-Lib indicator values as equivalent to real-time trading signals
    action: Claim that TA-Lib indicator outputs alone constitute trading signals — TA-Lib computes mathematical values from
      price data, requiring additional strategy logic, risk management, and execution handling to generate actionable signals
    severity: fatal
    kind: claim_boundary
    modality: must_not
    consequence: Users implement systems that generate trades based solely on indicator values without proper validation,
      risk controls, or execution logic, leading to uncontrolled losses
  - id: finance-C-120
    when: When importing the TA-Lib Python module
    action: Verify _ta_initialize() is called automatically at import time and atexit.register() is used to register shutdown
      handlers; any code that bypasses the import mechanism must manually call _ta_initialize() before invoking indicator
      functions
    severity: fatal
    kind: domain_rule
    modality: must
    consequence: Calling TA-Lib functions before initialization causes segmentation faults or undefined behavior; the C extension
      library requires internal state setup via _ta_initialize() to function correctly
    derived_from_bd_id: BD-081
  - id: finance-C-173
    when: When implementing or refactoring thread-safe data handling in TA-Lib multi-threaded usage
    action: Deep copy input data before any manipulation to verify each thread operates on an independent copy — do not remove
      or replace deep copying with alternative synchronization that assumes shared-data safety
    severity: fatal
    kind: architecture_guardrail
    modality: must
    consequence: Removing deep copy causes race conditions when multiple threads access shared data structures, leading to
      corrupted intermediate calculations and non-deterministic backtest results across runs
    derived_from_bd_id: BD-074
  regular:
  - id: finance-C-005
    when: When initializing the TA-Lib Python wrapper
    action: call _ta_initialize() on import and _ta_shutdown() on process exit via atexit
    severity: high
    kind: architecture_guardrail
    modality: must
    consequence: Without proper initialization, TA-Lib C library functions return TA_LIB_NOT_INITIALIZE errors, producing
      all-NaN outputs
    stage_ids:
    - c_wrapper
  - id: finance-C-006
    when: When implementing Cython functions that call TA-Lib C library
    action: apply @boundscheck(False) and @wraparound(False) decorators to disable Python safety checks
    severity: high
    kind: architecture_guardrail
    modality: must
    consequence: Without these decorators, every array access incurs Python bounds-checking overhead, negating the 2-4x performance
      benefit of Cython over SWIG
    stage_ids:
    - c_wrapper
  - id: finance-C-007
    when: When using integer optional parameters in TA-Lib function bindings
    action: use -2**31 (TA_INTEGER_DEFAULT) as the default sentinel value for optional integer parameters
    severity: high
    kind: domain_rule
    modality: must
    consequence: Using incorrect default values causes TA-Lib to use wrong default periods, producing incorrect technical
      indicator outputs
    stage_ids:
    - c_wrapper
  - id: finance-C-008
    when: When checking for contiguous memory layout of input arrays
    action: auto-convert non-contiguous arrays to C-contiguous via PyArray_GETCONTIGUOUS
    severity: high
    kind: architecture_guardrail
    modality: must
    consequence: Non-contiguous arrays cause incorrect data access patterns in C functions, producing wrong indicator values
      or segmentation faults
    stage_ids:
    - c_wrapper
  - id: finance-C-009
    when: When building the TA-Lib Python wrapper from source
    action: verify TA-Lib C library is installed before running setup.py or pip install
    severity: high
    kind: resource_boundary
    modality: must
    consequence: Build fails with 'Cannot find ta-lib library' warning or unresolved symbol linker errors without the underlying
      C library
    stage_ids:
    - c_wrapper
  - id: finance-C-010
    when: When building the TA-Lib Python wrapper
    action: use Cython to generate .c files, or use pre-generated .c files if Cython is unavailable
    severity: medium
    kind: resource_boundary
    modality: must
    consequence: Without Cython during build, the extension module cannot be compiled, breaking the entire package installation
    stage_ids:
    - c_wrapper
  - id: finance-C-011
    when: When specifying numpy version for TA-Lib compatibility
    action: use numpy<2 for TA-Lib 0.4.x branches and numpy>=2 for TA-Lib 0.5.x+ branches
    severity: high
    kind: resource_boundary
    modality: must
    consequence: Using incompatible numpy version causes build failures or runtime crashes due to removed deprecated C APIs
      in numpy 2.0+
    stage_ids:
    - c_wrapper
  - id: finance-C-012
    when: When checking if TA-Lib wrapper import succeeds
    action: verify package imports without errors and __ta_version__ is accessible
    severity: high
    kind: operational_lesson
    modality: must
    consequence: Import failure indicates missing C library, build errors, or ABI incompatibilities preventing the entire
      technical analysis functionality
    stage_ids:
    - c_wrapper
  - id: finance-C-013
    when: When building on Windows platforms
    action: use ta-lib-static as the library name instead of ta-lib on Windows
    severity: high
    kind: resource_boundary
    modality: must
    consequence: Incorrect library name causes linker errors 'unresolved external symbol' for all TA-Lib functions on Windows
      builds
    stage_ids:
    - c_wrapper
  - id: finance-C-014
    when: When working with TA-Lib function output arrays
    action: initialize output arrays with NaN for lookback period and zeros for integer outputs
    severity: high
    kind: domain_rule
    modality: must
    consequence: Uninitialized output arrays contain garbage values that corrupt technical indicator calculations in the lookback
      period
    stage_ids:
    - c_wrapper
  - id: finance-C-015
    when: When handling NaN values in input price arrays
    action: find first valid (non-NaN) index via check_begidx functions to determine start of computation
    severity: medium
    kind: domain_rule
    modality: must
    consequence: TA-Lib handles NaN values unexpectedly - it propagates NaNs to end of output rather than skipping them like
      pandas rolling mean
    stage_ids:
    - c_wrapper
  - id: finance-C-020
    when: When implementing batch indicator calculations using the func API
    action: Fill the lookback period with NaN values to maintain output array length equal to input
    severity: high
    kind: architecture_guardrail
    modality: must
    consequence: Without NaN padding in the lookback period, output arrays would have different lengths than input arrays,
      breaking vectorized operations and alignment
    stage_ids:
    - func_api
  - id: finance-C-021
    when: When implementing batch indicator calculations for multi-output functions
    action: Return a tuple of arrays for functions like BBANDS (upperband, middleband, lowerband)
    severity: high
    kind: architecture_guardrail
    modality: must
    consequence: Multi-output functions must return all outputs as a tuple; dropping outputs loses critical indicator data
    stage_ids:
    - func_api
  - id: finance-C-022
    when: When using unstable period functions (ADX, CMO, RSI, EMA, etc.)
    action: Call set_unstable_period() before invoking the function if non-default behavior is required
    severity: high
    kind: operational_lesson
    modality: must
    consequence: Functions with unstable periods produce different results depending on the unstable period setting, leading
      to inconsistent or unexpected indicator values
    stage_ids:
    - func_api
  - id: finance-C-023
    when: When implementing batch indicator calculations using the func API
    action: Expect pandas-style rolling window NaN handling (where NaN in input only affects lookback period)
    severity: high
    kind: domain_rule
    modality: must_not
    consequence: TA-Lib propagates NaN values to the end of output arrays, unlike pandas rolling mean which only has NaN in
      the lookback period; this causes unexpected output shapes when input contains NaN
    stage_ids:
    - func_api
  - id: finance-C-024
    when: When implementing batch indicator calculations using the func API
    action: Convert input arrays to C-contiguous memory layout if they are not already
    severity: medium
    kind: operational_lesson
    modality: must
    consequence: Non-contiguous input arrays are silently converted by PyArray_GETCONTIGUOUS, but explicit conversion prevents
      repeated memory copies during batch processing
    stage_ids:
    - func_api
  - id: finance-C-025
    when: When using the func API for batch processing
    action: Claim that output arrays contain valid values in the lookback period
    severity: high
    kind: claim_boundary
    modality: must_not
    consequence: The lookback period is filled with NaN (for double outputs) or 0 (for integer outputs); presenting these
      as valid indicator values is factually incorrect
    stage_ids:
    - func_api
  - id: finance-C-026
    when: When using the func API for batch processing
    action: Claim real-time or streaming capabilities for this batch processing API
    severity: medium
    kind: claim_boundary
    modality: must_not
    consequence: The func API processes entire arrays in batch mode; it does not provide single-value updates like the stream
      API (talib.stream.SMA)
    stage_ids:
    - func_api
  - id: finance-C-028
    when: When specifying timeperiod or nbdev parameters to func API functions
    action: Provide explicit positive integer values, not relying on the sentinel default -2**31
    severity: medium
    kind: resource_boundary
    modality: must
    consequence: The default value -2**31 is a sentinel that may cause unexpected behavior; explicit values ensure correct
      lookback calculation
    stage_ids:
    - func_api
  - id: finance-C-032
    when: When passing data to stream functions
    action: handle NaN return values when insufficient data is available for the timeperiod
    severity: high
    kind: domain_rule
    modality: must
    consequence: Stream functions return NaN when input data length is less than the required timeperiod, causing invalid
      financial calculations if not checked
    stage_ids:
    - stream_api
  - id: finance-C-033
    when: When using stream functions for real-time computation
    action: reprocess entire input array on each call (no internal state persistence)
    severity: high
    kind: resource_boundary
    modality: must
    consequence: Stream functions do not maintain internal state between calls, requiring full array reprocessing each time
      and negating 'streaming' performance benefits
    stage_ids:
    - stream_api
  - id: finance-C-035
    when: When implementing streaming indicator updates
    action: claim true real-time streaming when stream functions process full arrays
    severity: high
    kind: claim_boundary
    modality: must_not
    consequence: Describing stream API as 'real-time streaming' is misleading since each call processes the entire input array,
      not incremental updates
    stage_ids:
    - stream_api
  - id: finance-C-036
    when: When comparing batch and stream function results
    action: verify stream output equals the last element of batch output array
    severity: high
    kind: domain_rule
    modality: must
    consequence: The stream function's scalar output MUST equal the final element of the batch function's array output, otherwise
      financial strategy signals will be incorrect
    stage_ids:
    - stream_api
  - id: finance-C-037
    when: When implementing stream functions with integer parameters
    action: use TA_INTEGER_DEFAULT (-2**31) for unspecified integer parameters
    severity: medium
    kind: architecture_guardrail
    modality: must
    consequence: Integer parameters without explicit values use -2**31 as sentinel, and passing this value directly causes
      undefined TA-Lib behavior
    stage_ids:
    - stream_api
  - id: finance-C-038
    when: When implementing stream functions with floating-point parameters
    action: use TA_REAL_DEFAULT (-4e37) for unspecified real parameters
    severity: medium
    kind: architecture_guardrail
    modality: must
    consequence: Real parameters without explicit values use -4e37 as sentinel, and passing this value directly causes undefined
      TA-Lib behavior
    stage_ids:
    - stream_api
  - id: finance-C-039
    when: When calling TA-Lib C functions from stream API
    action: check return codes and raise exceptions on TA library errors
    severity: high
    kind: architecture_guardrail
    modality: must
    consequence: Unchecked TA_RetCode values can mask critical errors like library not initialized, bad parameters, or allocation
      failures
    stage_ids:
    - stream_api
  - id: finance-C-040
    when: When using the streaming API
    action: use the experimental stream API for production trading systems without validation
    severity: high
    kind: operational_lesson
    modality: must_not
    consequence: The streaming API is marked experimental in CHANGELOG and lacks state persistence for true incremental computation,
      risking production trading failures
    stage_ids:
    - stream_api
  - id: finance-C-041
    when: When implementing custom stream functions
    action: apply @boundscheck(False) and @wraparound(False) decorators
    severity: medium
    kind: architecture_guardrail
    modality: must
    consequence: Missing Cython decorators causes significant performance degradation for real-time financial calculations
      due to bounds checking overhead
    stage_ids:
    - stream_api
  - id: finance-C-042
    when: When converting batch function parameters to stream parameters
    action: use identical parameter names and types for easy switching between APIs
    severity: high
    kind: architecture_guardrail
    modality: must
    consequence: Parameter mismatches between batch and stream functions cause incorrect indicator calculations when developers
      switch between APIs
    stage_ids:
    - stream_api
  - id: finance-C-043
    when: When initializing a Function instance without specifying price series
    action: default to using 'close' prices for the 'price' input parameter
    severity: high
    kind: domain_rule
    modality: must
    consequence: Indicator calculations will use the wrong price series, producing incorrect technical analysis values that
      do not match expected results
    stage_ids:
    - abstract_api
  - id: finance-C-044
    when: When providing invalid parameter types to Function
    action: raise TypeError with descriptive message showing expected and actual types
    severity: high
    kind: domain_rule
    modality: must
    consequence: Invalid parameter types may silently produce incorrect results or cause undefined behavior in TA-Lib calculations
    stage_ids:
    - abstract_api
  - id: finance-C-045
    when: When creating Function instances with function names
    action: normalize function names to uppercase for case-insensitive lookup
    severity: medium
    kind: domain_rule
    modality: must
    consequence: Case-sensitive function name lookup would break API usability, as users commonly use lowercase function names
    stage_ids:
    - abstract_api
  - id: finance-C-047
    when: When Function inputs and parameters remain unchanged between calls
    action: cache outputs and skip recomputation to improve performance
    severity: medium
    kind: architecture_guardrail
    modality: must
    consequence: Repeated calculations with identical inputs would unnecessarily recompute results, degrading performance
      in tight loops
    stage_ids:
    - abstract_api
  - id: finance-C-049
    when: When calling __call__ with function parameters
    action: restore opt_input values and input_names after the call to preserve Function state
    severity: high
    kind: architecture_guardrail
    modality: must
    consequence: State changes from temporary calls would persist, causing subsequent uses of the Function instance to use
      wrong parameters
    stage_ids:
    - abstract_api
  - id: finance-C-050
    when: When input arrays are missing required keys
    action: raise Exception listing each missing required data keys
    severity: high
    kind: domain_rule
    modality: must
    consequence: Silent failure or partial computation with missing data would produce undefined or incorrect indicator values
    stage_ids:
    - abstract_api
  - id: finance-C-051
    when: When providing price arguments to Function.__call__
    action: validate the number of price arguments matches expected count
    severity: high
    kind: domain_rule
    modality: must
    consequence: Wrong number of price arguments would cause index errors or compute indicators on wrong price series
    stage_ids:
    - abstract_api
  - id: finance-C-052
    when: When input data type is pandas.DataFrame or polars.DataFrame
    action: return output as the same DataFrame type with specified column names and index
    severity: high
    kind: claim_boundary
    modality: must
    consequence: Mismatched output types would break downstream code expecting consistent DataFrame interface and index alignment
    stage_ids:
    - abstract_api
  - id: finance-C-053
    when: When abstract API is used for backtesting or strategy development
    action: claim that backtest results equal expected live trading performance
    severity: high
    kind: claim_boundary
    modality: must_not
    consequence: Backtest results do not account for slippage, market impact, execution delays, or changing market conditions
      that affect live trading
    stage_ids:
    - abstract_api
  - id: finance-C-054
    when: When the TA-Lib Python wrapper is used
    action: claim real-time trading capability for this library
    severity: medium
    kind: claim_boundary
    modality: must_not
    consequence: This is a technical analysis indicator library for historical data computation, not a live trading execution
      system
    stage_ids:
    - abstract_api
  - id: finance-C-055
    when: When setting input_arrays
    action: verify each arrays have the same length
    severity: high
    kind: domain_rule
    modality: must
    consequence: Array length mismatches would cause index errors or silent data truncation in TA-Lib calculations
    stage_ids:
    - abstract_api
  - id: finance-C-056
    when: When extending Function class for custom data types
    action: call the parent set_input_arrays method first and return True/False appropriately
    severity: medium
    kind: architecture_guardrail
    modality: must
    consequence: Improper subclassing would break input validation and cause silent failures or incorrect calculations
    stage_ids:
    - abstract_api
  - id: finance-C-057
    when: When accessing input_arrays property for polars.DataFrame
    action: use clone() instead of copy() for polars DataFrames
    severity: high
    kind: domain_rule
    modality: must
    consequence: Using copy() on polars DataFrames would cause runtime errors as polars uses clone() for copying
    stage_ids:
    - abstract_api
  - id: finance-C-061
    when: When detecting input Series type for appropriate conversion handling
    action: Check both positional args and keyword args for Series type using isinstance
    severity: high
    kind: architecture_guardrail
    modality: must
    consequence: Missing keyword argument check causes functions called with Series as keyword argument to bypass conversion,
      passing Series objects to TA-Lib C library which expects numpy arrays
    stage_ids:
    - series_wrapper
  - id: finance-C-063
    when: When neither pandas nor polars is available in the runtime environment
    action: Use identity wrapper that returns functions unchanged without type checking overhead
    severity: medium
    kind: resource_boundary
    modality: must
    consequence: Without identity wrapper fallback, every TA-Lib function call incurs unnecessary isinstance checks for None
      types, degrading performance for numpy-only users
    stage_ids:
    - series_wrapper
  - id: finance-C-064
    when: When handling optional dependencies pandas and polars for lazy loading
    action: Catch ModuleNotFoundError and only set Series types to None for known missing modules
    severity: high
    kind: domain_rule
    modality: must
    consequence: Silent import failure for broken but installed pandas/polars masks real module errors, causing cryptic failures
      in TA-Lib function calls
    stage_ids:
    - series_wrapper
  - id: finance-C-065
    when: When TA-Lib functions return streaming results (non-array outputs)
    action: Return streaming results directly without Series wrapping to preserve streaming interface
    severity: high
    kind: architecture_guardrail
    modality: must
    consequence: Wrapping streaming results as Series breaks the streaming API contract, causing TypeError in code expecting
      scalar or iterator results
    stage_ids:
    - series_wrapper
  - id: finance-C-066
    when: When wrapping polars Series output from TA-Lib function results
    action: Wrap numpy array results as polars.Series without passing index parameter
    severity: high
    kind: domain_rule
    modality: must
    consequence: Passing index to polars.Series constructor causes TypeError since polars does not support named index like
      pandas; results are correctly converted without index
    stage_ids:
    - series_wrapper
  - id: finance-C-067
    when: When TA-Lib function returns tuple results for multi-output indicators
    action: Wrap each element of tuple result as a separate Series preserving the common index
    severity: high
    kind: architecture_guardrail
    modality: must
    consequence: Returning tuple of arrays instead of Series breaks type consistency; downstream code expecting Series with
      proper index alignment fails with shape or index errors
    stage_ids:
    - series_wrapper
  - id: finance-C-068
    when: When using polars or pandas Series with MAVP function requiring period arrays
    action: Extract index from the price Series input, not from the period array argument
    severity: high
    kind: architecture_guardrail
    modality: must
    consequence: Using period array index causes misalignment with price data; the output must align with price timestamps,
      not period values
    stage_ids:
    - series_wrapper
  - id: finance-C-071
    when: When generating function signatures from C headers
    action: Skip TA_Set* and TA_Restore* configuration functions to keep only public indicator functions
    severity: high
    kind: domain_rule
    modality: must
    consequence: Including configuration functions creates bindings that conflict with the abstract API, causing runtime errors
      when users attempt to configure TA-Lib settings
    stage_ids:
    - code_generation
  - id: finance-C-072
    when: When regenerating _func.pxi after upstream TA-Lib changes
    action: Verify that __TA_FUNCTION_NAMES__ contains at least 150 function names
    severity: high
    kind: architecture_guardrail
    modality: must
    consequence: Missing functions in __TA_FUNCTION_NAMES__ causes AttributeError when users try to call those indicators,
      breaking the public API
    stage_ids:
    - code_generation
  - id: finance-C-073
    when: When parsing C header file signatures
    action: Strip float-only functions (TA_S_*) to avoid generating bindings for deprecated interfaces
    severity: high
    kind: domain_rule
    modality: must
    consequence: Float-only functions use different calling conventions and cause type mismatches when bound to double-based
      Python arrays
    stage_ids:
    - code_generation
  - id: finance-C-074
    when: When generating function lookback calculations
    action: Calculate lookback as 'begidx + lib.{FuncName}_Lookback(options)' to determine proper result array padding
    severity: high
    kind: architecture_guardrail
    modality: must
    consequence: Incorrect lookback causes output arrays to be misaligned with input arrays, resulting in NaN values in wrong
      positions or index errors
    stage_ids:
    - code_generation
  - id: finance-C-076
    when: When discovering TA-Lib header files across platforms
    action: Check platform-specific paths including /usr/include, /usr/local/include, /opt/local/include, and /opt/homebrew/include
    severity: high
    kind: resource_boundary
    modality: must
    consequence: Omitting platform-specific paths causes header discovery to fail on different operating systems, preventing
      code generation
    stage_ids:
    - code_generation
  - id: finance-C-077
    when: When running 'make generate' to regenerate bindings
    action: Verify both Python talib package and C TA-Lib library are installed
    severity: high
    kind: resource_boundary
    modality: must
    consequence: Regeneration fails with import errors or header not found errors if dependencies are missing
    stage_ids:
    - code_generation
  - id: finance-C-078
    when: When cleaning up C variable names to Pythonic names
    action: Strip 'in' prefix for input variables and 'optIn' prefix for optional parameters
    severity: high
    kind: architecture_guardrail
    modality: must
    consequence: Inconsistent naming causes TypeError when calling functions with keyword arguments that don't match the generated
      signatures
    stage_ids:
    - code_generation
  - id: finance-C-079
    when: When generating type stubs from runtime introspection
    action: Use NDArray[np.float64] for each function inputs and outputs
    severity: medium
    kind: architecture_guardrail
    modality: must
    consequence: Type stubs with incorrect array dtypes cause mypy/pyright to report false positives about type mismatches
    stage_ids:
    - code_generation
  - id: finance-C-080
    when: When regenerating _func.pxi and _stream.pxi
    action: Output files must be redirected to their respective locations using shell redirection
    severity: high
    kind: operational_lesson
    modality: must
    consequence: Writing to stdout instead of redirecting causes generated code to be lost and build failures
    stage_ids:
    - code_generation
  - id: finance-C-081
    when: When making manual edits to generated _func.pxi file
    action: Edit _func.pxi directly since it will be overwritten on next generation
    severity: medium
    kind: operational_lesson
    modality: must_not
    consequence: Direct edits are lost during regeneration, causing confusion and wasted development effort
    stage_ids:
    - code_generation
  - id: finance-C-082
    when: When developing new indicator functions in underlying TA-Lib
    action: Install TA-Lib from git source to have headers available for code generation
    severity: medium
    kind: operational_lesson
    modality: must
    consequence: Binary TA-Lib installations may not include development headers needed for code generation
    stage_ids:
    - code_generation
  - id: finance-C-083
    when: When running code generation for TA-Lib
    action: Modify the generator scripts (generate_func.py, generate_stream.py) without understanding the ta_func.h structure
    severity: medium
    kind: rationalization_guard
    modality: should_not
    consequence: Incorrect parser modifications cause function signatures to be malformed, leading to Cython compilation errors
    stage_ids:
    - code_generation
  - id: finance-C-084
    when: When TA-Lib adds new indicator functions in upstream
    action: Regenerate _func.pxi and _stream.pxi to add bindings for new functions
    severity: high
    kind: operational_lesson
    modality: must
    consequence: Missing bindings for new TA-Lib functions causes AttributeError when users try to use them
    stage_ids:
    - code_generation
  - id: finance-C-085
    when: When generating INDEX-type functions that output indices
    action: Add index offset adjustment loop after function call to convert internal indices to absolute positions
    severity: high
    kind: architecture_guardrail
    modality: must
    consequence: INDEX functions return relative indices that must be adjusted by begidx, otherwise returned indices are incorrect
    stage_ids:
    - code_generation
  - id: finance-C-086
    when: When generating stream functions (stream_*)
    action: Name functions with 'stream_' prefix to distinguish from batch functions
    severity: high
    kind: architecture_guardrail
    modality: must
    consequence: Conflicting names between batch and stream functions cause import errors or wrong function resolution
    stage_ids:
    - code_generation
  - id: finance-C-087
    when: When implementing user_code that passes pandas/polars Series to TA-Lib
    action: pass float64-compatible Series values that can be converted to contiguous numpy arrays
    severity: high
    kind: domain_rule
    modality: must
    consequence: TypeError raised when Series dtype cannot be cast to float64, or MemoryError during non-contiguous array
      copy operations for large datasets
  - id: finance-C-088
    when: When implementing user_code that mixes pandas and polars inputs
    action: mix pandas and polars Series/DataFrame in the same function call
    severity: high
    kind: domain_rule
    modality: must_not
    consequence: Exception raised with message 'Cannot mix polars and pandas', causing the entire function call to fail
  - id: finance-C-089
    when: When implementing series_wrapper that extracts numpy arrays from Series
    action: preserve the original pandas index for downstream return value wrapping
    severity: medium
    kind: architecture_guardrail
    modality: must
    consequence: Index mismatch causes pandas alignment errors when result Series index does not match original input index
  - id: finance-C-090
    when: When implementing series_wrapper that converts pandas/polars inputs to numpy
    action: convert input arrays to float64 dtype before passing to func_api
    severity: high
    kind: domain_rule
    modality: must
    consequence: TypeError raised by func_api check_array() when input dtype is not NPY_DOUBLE, causing indicator calculation
      to fail
  - id: finance-C-091
    when: When implementing series_wrapper that passes data to func_api
    action: verify each input arrays have identical length values
    severity: high
    kind: domain_rule
    modality: must
    consequence: Exception raised with 'input array lengths are different', causing the function to fail before any calculation
  - id: finance-C-092
    when: When implementing series_wrapper that passes dict/DataFrame to abstract_api
    action: provide each required price series keys (open, high, low, close, volume as needed by the specific function)
    severity: high
    kind: domain_rule
    modality: must
    consequence: Exception raised with 'input_arrays parameter missing required data key', preventing function execution
  - id: finance-C-093
    when: When implementing abstract_api that extracts arrays from dict/DataFrame
    action: convert extracted pandas/polars Series to float64 numpy arrays before passing to func_api
    severity: high
    kind: domain_rule
    modality: must
    consequence: TypeError or incorrect calculation results when Series with non-float64 dtype is passed to TA-Lib C function
  - id: finance-C-094
    when: When implementing abstract_api that passes data to func_api
    action: verify each price series arrays in the input dict have identical length
    severity: high
    kind: domain_rule
    modality: must
    consequence: Exception raised at runtime when length validation fails inside func_api, with 'input array lengths are different'
  - id: finance-C-095
    when: When implementing func_api that passes arrays to c_wrapper
    action: convert input arrays to C-contiguous memory layout if not already contiguous
    severity: medium
    kind: resource_boundary
    modality: must
    consequence: Silent automatic conversion causes memory copy overhead; for streaming/large datasets this creates significant
      performance degradation
  - id: finance-C-096
    when: When implementing c_wrapper that passes data to func_api
    action: pad output arrays with NaN values for the lookback period (first lookback elements)
    severity: high
    kind: domain_rule
    modality: must
    consequence: Financial indicators show incorrect values when lookback NaN padding is missing, causing wrong trading signals
      and financial losses
  - id: finance-C-097
    when: When implementing c_wrapper that returns results to func_api
    action: propagate TA_RetCode error codes and raise Python exceptions for non-zero return values
    severity: high
    kind: architecture_guardrail
    modality: must
    consequence: Silent failure or incorrect results when TA-Lib C library returns error code that is not converted to exception
  - id: finance-C-098
    when: When implementing c_wrapper that processes inputs from func_api
    action: compute beginning index (begidx) by finding first non-NaN value across each input arrays
    severity: high
    kind: domain_rule
    modality: must
    consequence: Incorrect indicator values when NaN detection fails, causing misaligned outputs and wrong trading decisions
  - id: finance-C-099
    when: When implementing abstract_api that passes results to series_wrapper
    action: return results matching the input type (polars.DataFrame returns polars.DataFrame, pandas.DataFrame returns pandas.DataFrame)
    severity: medium
    kind: architecture_guardrail
    modality: must
    consequence: TypeError when downstream code expects specific return type but receives numpy array instead of DataFrame/Series
  - id: finance-C-100
    when: When implementing series_wrapper that returns pandas Series to user_code
    action: wrap numpy results in pandas Series preserving the original input index
    severity: medium
    kind: architecture_guardrail
    modality: must
    consequence: Index misalignment in result Series causes pandas alignment issues and incorrect data analysis in downstream
      code
  - id: finance-C-101
    when: When implementing series_wrapper that returns polars Series to user_code
    action: wrap numpy results in polars Series without explicit index (polars has no built-in index)
    severity: medium
    kind: architecture_guardrail
    modality: must
    consequence: Incorrect data association when polars Series is created with misaligned data compared to expected row positions
  - id: finance-C-102
    when: When implementing c_wrapper that processes stream inputs from func_api
    action: return scalar values (float64) instead of arrays for streaming API calls
    severity: medium
    kind: resource_boundary
    modality: must
    consequence: TypeError when stream result (scalar) is treated as array, or incorrect value extraction from single-element
      array
  - id: finance-C-103
    when: When implementing abstract_api that validates DataFrame input columns
    action: check that each required column names exist in the input DataFrame (not just that dict keys exist)
    severity: high
    kind: domain_rule
    modality: must
    consequence: KeyError raised when accessing missing DataFrame column, causing function to fail for valid dict inputs
  - id: finance-C-104
    when: When implementing or writing code that calls TA-Lib functions
    action: Pass input arrays with NPY_DOUBLE (float64) dtype — the Cython wrapper rejects non-float64 arrays at the boundary
    severity: high
    kind: domain_rule
    modality: must
    consequence: Input array type validation raises Exception('input array type is not double'), causing function calls to
      fail silently or throw unexpected errors
  - id: finance-C-106
    when: When implementing or writing code that passes arrays to TA-Lib functions
    action: Verify input arrays are C-contiguous — non-contiguous arrays are silently converted by calling PyArray_GETCONTIGUOUS
    severity: medium
    kind: domain_rule
    modality: must
    consequence: Non-contiguous arrays trigger internal conversion overhead on every call, degrading performance especially
      for streaming/realtime use cases
  - id: finance-C-107
    when: When implementing or writing code that processes financial time series with missing values
    action: Assume TA-Lib NaN propagation behavior matches pandas rolling calculations — the underlying C library propagates
      NaN to end of output, unlike pandas which outputs values until lookback gap
    severity: high
    kind: resource_boundary
    modality: must_not
    consequence: NaN handling differences cause indicator values to differ from pandas-native rolling calculations, leading
      to incorrect strategy signals and financial loss
  - id: finance-C-108
    when: When implementing or writing code that processes financial time series with leading NaN values
    action: Expect the lookback period of each indicator to be filled with NaN — the wrapper pre-fills lookback positions
      with NaN to indicate insufficient data for calculation
    severity: medium
    kind: domain_rule
    modality: must
    consequence: Misunderstanding lookback NaN handling leads to off-by-one errors in signal generation, causing premature
      or delayed trading decisions
  - id: finance-C-109
    when: When implementing or writing code using the Abstract API in multithreaded applications
    action: Rely on thread-local storage in the Function class — each thread gets isolated state via threading.local(), ensuring
      safe concurrent use without explicit locking
    severity: high
    kind: architecture_guardrail
    modality: must
    consequence: Without thread-local isolation, shared Function state causes race conditions where parameters from one thread
      corrupt calculations in another thread, producing incorrect indicator values
  - id: finance-C-110
    when: When implementing or writing code that mixes Polars and Pandas in the same TA-Lib function call
    action: Pass both Polars and Pandas objects to a single TA-Lib function — the wrapper explicitly raises Exception('Cannot
      mix polars and pandas') when both types are detected
    severity: high
    kind: domain_rule
    modality: must_not
    consequence: Mixed Polars/Pandas inputs trigger explicit Exception, halting execution and requiring refactoring of data
      pipeline
  - id: finance-C-111
    when: When implementing or writing code using the Abstract API's Function class __call__ method
    action: Expect parameter state to be restored after each call — the wrapper explicitly saves and restores opt_input values
      and input_names, ensuring stateless per-invocation behavior
    severity: high
    kind: architecture_guardrail
    modality: must
    consequence: Without state restoration, subsequent calls with different parameters would carry over unintended parameter
      values, producing incorrect calculations
  - id: finance-C-113
    when: When implementing or deploying TA-Lib in environments without C compilation toolchain
    action: Claim TA-Lib can run in pure Python environments without C compiler, NumPy, or the underlying TA-Lib C library
      — the wrapper is a Cython-based binding that requires compiled dependencies
    severity: high
    kind: claim_boundary
    modality: must_not
    consequence: Users attempt installation in unsupported environments, experiencing build failures, missing symbol errors,
      or degraded functionality
  - id: finance-C-114
    when: When implementing or deploying TA-Lib in embedded systems or minimal Python environments
    action: Claim TA-Lib can run without NumPy — the Cython wrapper uses NumPy C API (np.import_array, PyArray_* functions)
      and converts each input to float64 ndarrays
    severity: high
    kind: claim_boundary
    modality: must_not
    consequence: Users attempt deployment on NumPy-less platforms, encountering ImportError or AttributeError when calling
      any TA-Lib function
  - id: finance-C-116
    when: When comparing TA-Lib indicator calculations with pandas-native rolling calculations
    action: Claim TA-Lib produces identical results to pandas rolling calculations — NaN propagation behavior differs fundamentally
      between the C library and pandas implementation
    severity: high
    kind: claim_boundary
    modality: must_not
    consequence: Users expect interchangeability between TA-Lib and pandas rolling functions, receiving unexpected NaN values
      that break downstream logic and cause incorrect calculations
  - id: finance-C-117
    when: When implementing or writing code that sets integer parameters in TA-Lib functions
    action: Use -2**31 (or equivalent TA_INTEGER_DEFAULT) for optional integer parameters that should use library defaults
      — this sentinel value maps to the C library's default behavior
    severity: medium
    kind: domain_rule
    modality: must
    consequence: Omitting the -2**31 sentinel or using incorrect integer values causes the C library to use undefined parameter
      states, producing unpredictable indicator outputs
  - id: finance-C-118
    when: When implementing or writing code that processes output from TA-Lib functions
    action: Expect output type to match input type — DataFrame→DataFrame, Series→Series, ndarray→ndarray — the wrapper preserves
      container type through the calculation pipeline
    severity: medium
    kind: architecture_guardrail
    modality: must
    consequence: Incorrect expectations about output container type leads to type errors or incorrect data handling in downstream
      processing
  - id: finance-C-119
    when: When implementing or writing code that imports the TA-Lib Python package
    action: Rely on automatic TA-Lib C library initialization at import time — _ta_initialize() is called in talib/__init__.py
      at module load and _ta_shutdown() is registered via atexit for clean termination
    severity: high
    kind: architecture_guardrail
    modality: must
    consequence: Attempting to call TA-Lib functions before import completes or after process shutdown causes undefined behavior
      or segmentation faults
  - id: finance-C-121
    when: When implementing integer parameter handling in TA-Lib Python bindings
    action: Map Python None or missing optional integers to TA_INTEGER_DEFAULT constant (-2^31) as defined by the TA-Lib C
      library; do not use arbitrary sentinel values like 0, -1, or Python None directly in C calculations
    severity: high
    kind: domain_rule
    modality: must
    consequence: Using incorrect sentinel values causes the underlying C library to receive invalid parameters, producing
      wrong indicator values or silent data corruption that propagates to trading decisions
    derived_from_bd_id: BD-003
  - id: finance-C-122
    when: When calculating indicators that depend on dynamic lookback periods (e.g., SMA, EMA, RSI with varying timeperiod
      parameters)
    action: Verify lookback computation correctly accounts for endIdx as length-1 convention; verify the number of NaN values
      prepended matches the dynamic lookback derived from parameters (e.g., timeperiod=200 requires 199 prior bars lookback);
      validate output array length equals input length and valid results start at correct index
    severity: high
    kind: operational_lesson
    modality: must
    consequence: Off-by-one errors in lookback calculation cause output arrays with wrong length, incorrect NaN count in lookback
      period, and valid results starting at wrong index; for high-period indicators like SMA(200), this propagates to significant
      data misalignment in backtesting and live trading
    derived_from_bd_id: BD-102
  - id: finance-C-123
    when: When processing input data arrays with NaN values or generating output arrays for TA-Lib indicators
    action: Pre-fill output arrays with NaN values for the lookback period before calculation; do not assume output arrays
      contain valid data for the first N elements where N equals the dynamic lookback period
    severity: medium
    kind: domain_rule
    modality: must
    consequence: Using uninitialized output arrays or assuming valid values in the lookback period causes incorrect indicator
      values and silent data corruption that propagates to strategy calculations
    derived_from_bd_id: BD-085
  - id: finance-C-124
    when: When implementing candlestick pattern recognition in technical analysis
    action: Implement each 61 standard TA-Lib candlestick patterns (CDL* functions) covering both single-candle patterns (doji,
      hammer, engulfing) and multi-candle patterns (morning star, three white soldiers) — the complete taxonomy is mandatory
    severity: high
    kind: domain_rule
    modality: must
    consequence: Partial pattern implementation creates false claims of comprehensive technical analysis, as traders relying
      on missing patterns will have gaps in their automated strategy coverage compared to industry-standard TA-Lib
    derived_from_bd_id: BD-038
  - id: finance-C-125
    when: When implementing or refactoring concurrent execution of shared Function instances
    action: Use threading.local() for stateful computation buffers to isolate per-thread state; do NOT remove thread-local
      storage or replace with shared mutable state
    severity: high
    kind: architecture_guardrail
    modality: must
    consequence: Removing thread-local storage causes data races when multiple threads share Function instances concurrently;
      computed indicators from one thread bleed into another, producing incorrect signals and corrupting backtest results
    derived_from_bd_id: BD-010
  - id: finance-C-126
    when: When using abstract API parameters 'price', 'price0', 'price1' etc. without explicit column specification
    action: Verify that __INPUT_PRICE_SERIES_DEFAULTS mapping (price->close, price0->high, price1->low, etc.) matches the
      actual DataFrame column names; if columns differ, explicitly specify the correct column name
    severity: medium
    kind: operational_lesson
    modality: should
    consequence: Relying on default mappings when DataFrame columns don't follow standard naming silently computes indicators
      on wrong price series, producing invalid trading signals that appear correct
    derived_from_bd_id: BD-012
  - id: finance-C-127
    when: When passing parameters to TA-Lib function wrappers
    action: Use Pythonic parameter names (e.g., timeperiod, high, low) when available; verify that camelCase C parameter names
      are correctly transformed to snake_case if using raw parameter dictionaries
    severity: medium
    kind: operational_lesson
    modality: should
    consequence: Using untransformed C parameter names like optInTimePeriod or inHigh causes TypeError exceptions or silently
      wrong parameter values, breaking indicator calculations in live strategies
    derived_from_bd_id: BD-020
  - id: finance-C-128
    when: When importing optional dependencies (pandas, polars) in the framework
    action: Use try/except ImportError with Python 2/3 compatible exception handling syntax to gracefully handle missing optional
      dependencies; do not let missing optional libraries prevent import of core functionality
    severity: high
    kind: operational_lesson
    modality: must
    consequence: Missing optional dependencies cause ImportError exceptions that prevent the entire module from loading, blocking
      access to core TA-Lib functionality even when optional DataFrame features are not used
    derived_from_bd_id: BD-051
  - id: finance-C-129
    when: When integrating custom DataFrame implementations (non-pandas/polars) with the abstract API
    action: Subclass Function and override set_input_arrays to handle conversion from custom data types to numpy arrays; do
      not assume each data types are automatically supported
    severity: medium
    kind: operational_lesson
    modality: should
    consequence: Using custom DataFrame types without proper set_input_arrays override causes TypeError or incorrect array
      conversion, producing wrong indicator values that silently corrupt strategy logic
    derived_from_bd_id: BD-013
  - id: finance-C-130
    when: When initializing the framework in environments with missing pandas/polars
    action: Assume pandas or polars is installed at import time; use lazy detection (check availability only when calling
      DataFrame-dependent methods) to allow core functionality to work without optional dependencies
    severity: high
    kind: operational_lesson
    modality: must_not
    consequence: Eagerly importing optional dependencies causes immediate failure when neither pandas nor polars is installed,
      preventing use of core indicator calculation functions that don't require DataFrames
    derived_from_bd_id: BD-015
  - id: finance-C-131
    when: When implementing or modifying Python bindings for the TA-Lib C library
    action: Use Cython to generate Python C extensions for TA-Lib C library integration — maintain near-native performance
      and Python API ergonomics; do not replace with SWIG or other binding mechanisms
    severity: high
    kind: architecture_guardrail
    modality: must
    consequence: Switching from Cython to SWIG introduces wrapper complexity, poorer numpy array integration, and potential
      memory access issues that could cause incorrect calculation results or performance degradation
    derived_from_bd_id: BD-022
  - id: finance-C-132
    when: When generating the Python API surface from source code
    action: Filter out TA_Set*, TA_Restore*, and other internal functions from generated code — include only public technical
      indicator functions to keep API surface clean and focused
    severity: medium
    kind: domain_rule
    modality: must
    consequence: Including internal functions in the public API causes confusion, potential misuse of unverified functions,
      and API surface pollution that complicates documentation and user onboarding
    derived_from_bd_id: BD-021
  - id: finance-C-133
    when: When configuring adaptive indicators (KAMA, MAMA, etc.) in backtesting
    action: Explicitly call set_unstable_period() to configure convergence behavior based on parameter selection and risk
      tolerance — do not rely on framework defaults for adaptive indicators
    severity: high
    kind: domain_rule
    modality: must
    consequence: Failing to configure set_unstable_period causes convergence warnings to be suppressed silently, leading to
      incorrect indicator values that distort strategy logic and produce backtest results incompatible with live trading
    derived_from_bd_id: BD-029
  - id: finance-C-134
    when: When processing integer output arrays from pattern recognition and price transform functions
    action: Interpret lookback period positions as zero (0) rather than NaN in int32 output arrays — zero signals 'no valid
      pattern found' while non-zero values indicate 'pattern at position N'
    severity: high
    kind: domain_rule
    modality: must
    consequence: Misinterpreting zero as a valid pattern position causes incorrect pattern recognition results, leading to
      false trading signals that execute trades on non-existent patterns and produce unreproducible strategy behavior
    derived_from_bd_id: BD-034
  - id: finance-C-135
    when: When calling single-price technical indicator functions without explicit price input
    action: Default to 'close' price series for single-price functions (RSI, MACD, etc.) when no price input is specified
      — use Abstract API default inputs configuration for the close series
    severity: high
    kind: domain_rule
    modality: must
    consequence: Using non-close prices as defaults causes indicators to calculate on the wrong price series, producing incorrect
      strategy signals that lead to trades at wrong times and significant financial losses
    derived_from_bd_id: BD-040
  - id: finance-C-136
    when: When implementing or migrating code that uses TA-Lib indicator functions
    action: Assume TA-Lib NaN handling behaves like pandas rolling operations — TA-Lib propagates NaN values to the end of
      output while pandas recovers after a window of valid values; handle NaN values explicitly at the end of series
    severity: high
    kind: domain_rule
    modality: must_not
    consequence: Assuming pandas-like NaN recovery causes silent result distortion where TA-Lib outputs NaN for the entire
      remaining series while pandas code expects recovery, leading to strategies that work in development but fail in production
    derived_from_bd_id: BD-090
  - id: finance-C-137
    when: When preparing input arrays for TA-Lib function calls
    action: Convert input arrays to float64 dtype (NPY_DOUBLE) and verify C-contiguous memory layout before passing to TA-Lib
      functions — use np.ascontiguousarray() if needed
    severity: medium
    kind: domain_rule
    modality: must
    consequence: Passing non-double-precision or non-C-contiguous arrays causes silent type conversion at call time, adding
      memory copies and potential precision loss that distorts calculation results in ways that are difficult to debug
    derived_from_bd_id: BD-092
  - id: finance-C-138
    when: When implementing concurrent access to Abstract Function instances across multiple threads
    action: Use thread-local storage (threading.local()) to maintain independent state per thread — do not remove threading.local()
      usage or replace with shared state patterns that allow instances to be shared safely
    severity: high
    kind: domain_rule
    modality: must
    consequence: Without thread-local storage, concurrent threads sharing Abstract Function instances experience race conditions
      where one thread's parameter state overwrites another's, causing silent data corruption in multi-strategy applications
    derived_from_bd_id: BD-053
  - id: finance-C-139
    when: When implementing lookback period calculation for moving average and similar indicators
    action: Compute lookback dynamically as timeperiod-1 per parameters — do not use hardcoded lookback values or fixed lookup
      tables that cannot capture parameter-dependent lookback
    severity: high
    kind: domain_rule
    modality: must
    consequence: Hardcoded lookback values produce incorrect indicator results for non-default timeperiods, causing strategies
      to use signals from incorrect historical windows and leading to trading losses
    derived_from_bd_id: BD-054
  - id: finance-C-140
    when: When implementing input parameter handling for Abstract API functions that accept DataFrames
    action: Support DataFrame column access by name using input_name parameters — do not change to positional-only argument
      handling that requires users to remember column order
    severity: high
    kind: domain_rule
    modality: must
    consequence: Switching to positional-only column access breaks existing user code that relies on named column specification,
      requiring widespread refactoring and causing breaking API changes
    derived_from_bd_id: BD-055
  - id: finance-C-141
    when: When implementing indicator function metadata and flags
    action: Expose TA_FUNC_FLAGS including the 'unstable period' flag for KAMA, MAMA, ADX, ATR indicators — do not remove
      or hide convergence period information that indicates when indicator results become reliable
    severity: medium
    kind: domain_rule
    modality: must
    consequence: Hiding the unstable period flag causes strategies to use indicator results before convergence completes,
      producing unreliable signals during warmup periods that degrade strategy performance silently
    derived_from_bd_id: BD-056
  - id: finance-C-142
    when: When implementing data type conversion for input arrays before calling TA-Lib C library functions
    action: Convert pandas/polars Series to Float64 before calling TA-Lib C library — do not use Float32 for memory efficiency
      as it causes precision loss in price calculations
    severity: high
    kind: domain_rule
    modality: must
    consequence: Using Float32 precision causes precision loss in financial price calculations, producing incorrect indicator
      values that lead to faulty trading signals and financial losses in live trading
    derived_from_bd_id: BD-057
  - id: finance-C-143
    when: When validating TA-Lib library installation completeness
    action: Verify that the function count matches the expected count to detect incomplete TA-Lib installations early — do
      not skip function count validation as it allows broken installations to go undetected
    severity: medium
    kind: operational_lesson
    modality: should
    consequence: Skipping function count validation allows incomplete TA-Lib installations to go undetected until specific
      functions are called, causing cryptic runtime errors during live trading when missing functions are accessed
    derived_from_bd_id: BD-078
  - id: finance-C-144
    when: When implementing __call__ method for Abstract Function class
    action: Restore parameter state (opt_input values, input_names) after each function call completes — do not allow per-call
      parameter changes to persist across invocations
    severity: high
    kind: domain_rule
    modality: must
    consequence: Without parameter state restoration after each call, subsequent invocations inherit modified parameters from
      previous calls, causing silent parameter bleed where strategies use wrong indicator configurations
    derived_from_bd_id: BD-086
  - id: finance-C-145
    when: When designing thread-safe access patterns for shared Abstract Function instances across multiple threads
    action: Do not assume thread-local storage alone provides complete thread safety — deep copy of input data is required
      when sharing instances across threads to prevent data corruption from shared array access
    severity: high
    kind: architecture_guardrail
    modality: must
    consequence: Relying only on thread-local storage while sharing input data causes subtle data corruption as threads may
      simultaneously read and write shared arrays, producing incorrect indicator values in concurrent multi-strategy applications
    derived_from_bd_id: BD-095
  - id: finance-C-146
    when: When configuring unstable periods using set_unstable_period() with thread-local Abstract Function instances
    action: Verify set_unstable_period() is called after thread-local isolation is established and before each thread's indicator
      calculations — do not configure unstable periods on shared state before threading operations begin
    severity: medium
    kind: operational_lesson
    modality: must
    consequence: Configuring unstable periods before thread-local isolation causes inconsistent convergence behavior across
      threads, with some threads using incorrect warmup periods and producing unreliable indicator values
    derived_from_bd_id: BD-099
  - id: finance-C-147
    when: When integrating TA-Lib functions into typed data pipelines where downstream code expects consistent DataFrame or
      Series output types
    action: Handle validation errors gracefully to preserve output type consistency — implement fallback or typed error responses
      instead of raising exceptions for length validation failures that break pipeline flow
    severity: medium
    kind: operational_lesson
    modality: should
    consequence: Validation failures raising exceptions breaks typed pipeline integration where downstream code expects consistent
      DataFrame or Series outputs, causing pipeline failures even for recoverable input errors
    derived_from_bd_id: BD-100
  - id: finance-C-148
    when: When modifying the TA-Lib initialization lifecycle
    action: Replace automatic initialization on import with lazy initialization — the C library must be initialized exactly
      once per process before any function calls
    severity: medium
    kind: operational_lesson
    modality: should_not
    consequence: Switching to lazy initialization shifts initialization costs to the first function call and may cause cryptic
      C-level errors if TA-Lib functions are called before the library is ready, breaking user expectations in backtesting
      workflows
    derived_from_bd_id: BD-023
  - id: finance-C-149
    when: When implementing TA-Lib wrapper functions
    action: Accept pandas.Series and polars.Series inputs directly, detect input types transparently, and extract arrays internally
      — raising clear errors for mixed input types
    severity: high
    kind: domain_rule
    modality: must
    consequence: Without DataFrame input support, users must manually extract numpy arrays before each function call, introducing
      boilerplate and increasing the risk of type mismatch errors in quantitative research workflows
    derived_from_bd_id: BD-024
  - id: finance-C-150
    when: When processing input data before calling TA-Lib C functions
    action: Convert each input data to float64 numpy arrays with C-contiguous memory layout before passing to C functions
    severity: high
    kind: domain_rule
    modality: must
    consequence: Using float32 or integer arrays causes memory misalignment with C ABI requirements, leading to segmentation
      faults or silent precision loss in technical indicator calculations
    derived_from_bd_id: BD-025
  - id: finance-C-151
    when: When implementing the TA-Lib Python API
    action: Provide both Function API (stateless) and Abstract API (stateful) interfaces, sharing the same underlying C implementation
      for correctness and performance
    severity: high
    kind: architecture_guardrail
    modality: must
    consequence: Removing either the stateless or stateful API breaks existing user workflows — batch research relies on stateless
      calls while live trading relies on stateful streaming interfaces
    derived_from_bd_id: BD-032
  - id: finance-C-152
    when: When implementing or refactoring function name lookup logic in the TA-Lib Python wrapper
    action: Normalize each function names to uppercase internally while accepting any casing from users (case-insensitive
      lookup)
    severity: high
    kind: domain_rule
    modality: must
    consequence: Breaking case-insensitive function name lookup causes existing code using 'rsi', 'RSI', or 'Rsi' to fail
      with function not found errors, making the wrapper incompatible with user expectations
    derived_from_bd_id: BD-042
  - id: finance-C-153
    when: When implementing output array initialization in the Python wrapper for technical indicator functions
    action: Use make_double_array() to pre-fill output arrays with NaN up to the lookback period, deferring sentinel value
      initialization to the wrapper layer
    severity: high
    kind: domain_rule
    modality: must
    consequence: Skipping NaN pre-fill causes lookback period to contain uninitialized garbage values instead of proper NaN
      sentinels, leading to incorrect calculations and silent data corruption in backtesting strategies
    derived_from_bd_id: BD-043
  - id: finance-C-154
    when: When implementing or adjusting technical indicator default parameters
    action: Change the default timeperiod=14 for RSI (Wilder's original) or timeperiod=30 for common MAs without explicit
      documentation — these defaults encode industry-standard conventions
    severity: medium
    kind: operational_lesson
    modality: must_not
    consequence: Modifying default timeperiod values causes strategies to use non-standard parameters that alter indicator
      responsiveness and smoothness, leading to backtest-live divergence when live trading uses broker defaults
    derived_from_bd_id: BD-046
  - id: finance-C-155
    when: When migrating pandas-based rolling statistics code to TA-Lib functions
    action: Verify that TA-Lib NaN propagation behavior matches strategy expectations — TA-Lib propagates NaN to end of series
      while pandas may recover after sufficient valid data in window
    severity: high
    kind: operational_lesson
    modality: must
    consequence: Users expecting pandas-like NaN recovery after sufficient valid data will encounter unexpected NaN regions
      throughout the TA-Lib output series, causing silent calculation errors in strategies that rely on rolling statistics
      recovering from missing data
    derived_from_bd_id: BD-098
  - id: finance-C-156
    when: When using the Stochastic Oscillator indicator with default parameters
    action: Change the slowK default smoothing period from 3-period SMA without explicit testing and justification — the default
      minimizes signal noise while maintaining responsiveness for overbought/oversold detection
    severity: medium
    kind: operational_lesson
    modality: should_not
    consequence: Modifying the slowK default period alters the indicator's smoothing characteristics; a longer period increases
      lag and may miss timely entry/exit points while a shorter period increases noise and generates false trading signals
    derived_from_bd_id: BD-058
  - id: finance-C-157
    when: When using the Stochastic Oscillator indicator with default parameters
    action: Change the slowD default smoothing period from 3-period SMA without explicit testing and justification — the double-smoothing
      creates the signal line for buy/sell crossovers
    severity: medium
    kind: operational_lesson
    modality: should_not
    consequence: Modifying the slowD default period alters the crossover signal characteristics; changing to a shorter period
      increases false signals while a longer period increases lag in momentum trading decisions
    derived_from_bd_id: BD-059
  - id: finance-C-158
    when: When configuring Bollinger Bands with default parameters
    action: Change the default 20-period MA window or 2 standard deviation multiplier without explicit testing and justification
      — the multiplier of 2 captures approximately 95% of price action under normal distribution
    severity: medium
    kind: operational_lesson
    modality: should_not
    consequence: Modifying the standard deviation multiplier changes the volatility envelope width; 1.5x creates tighter bands
      causing more false mean reversion signals while 3.0x focuses only on extreme movements, missing valid trading opportunities
    derived_from_bd_id: BD-060
  - id: finance-C-159
    when: When configuring Stochastic RSI indicator with default parameters
    action: Change the default 14-period timeperiod without explicit testing and justification — the period aligns with traditional
      RSI conventions for a two-week trading cycle
    severity: medium
    kind: operational_lesson
    modality: should_not
    consequence: Modifying the Stochastic RSI period changes momentum sensitivity; shorter periods increase responsiveness
      but also increase noise while longer periods smooth fluctuations and may delay valid signals in momentum-based strategies
    derived_from_bd_id: BD-061
  - id: finance-C-160
    when: When implementing or refactoring Abstract Function classes that maintain internal state
    action: Use threading.local() for per-thread state isolation — each thread must maintain independent state arrays without
      sharing or locking
    severity: high
    kind: architecture_guardrail
    modality: must
    consequence: Without threading.local() isolation, concurrent threads sharing Abstract Function state will cause race conditions
      on internal state arrays, producing incorrect indicator values and non-deterministic backtest results
    derived_from_bd_id: BD-033
  - id: finance-C-161
    when: When implementing indicator functions for real-time trading scenarios
    action: Provide streaming versions (stream_*) of each function that support incremental O(1) per-tick updates — do not
      rely solely on batch processing that requires O(n) full recalculation on each new bar
    severity: high
    kind: architecture_guardrail
    modality: must
    consequence: Without streaming variants, real-time trading systems face O(n) recalculation cost per tick, causing unacceptable
      latency spikes that make low-latency strategy execution impossible
    derived_from_bd_id: BD-035
  - id: finance-C-162
    when: When validating input arrays before passing to low-level indicator calculations
    action: Validate that input arrays are float64 dtype and C-contiguous memory layout before processing — reject non-compliant
      inputs with clear Python error messages
    severity: high
    kind: domain_rule
    modality: must
    consequence: Without float64 and C-contiguous validation, invalid inputs reach C-level libraries causing segmentation
      faults or undefined behavior with cryptic stack traces instead of actionable error messages
    derived_from_bd_id: BD-036
  - id: finance-C-163
    when: When processing DataFrame inputs in calculation functions
    action: Raise an explicit exception when polars and pandas DataFrames are mixed in the same calculation — do not allow
      implicit conversion between DataFrame types
    severity: high
    kind: domain_rule
    modality: must
    consequence: Without explicit exception handling, mixing polars and pandas inputs produces ambiguous results due to different
      index semantics and type systems, leading to silent data corruption in calculation outputs
    derived_from_bd_id: BD-037
  - id: finance-C-164
    when: When implementing MAVP (Moving Average Variable Period) calculations with invalid period values
    action: Use default SMA timeperiod values as fallback when periods exceed valid ranges — must not raise exceptions or
      change to other fallback behaviors
    severity: high
    kind: domain_rule
    modality: must
    consequence: Changing the fallback behavior from default SMA timeperiod to exceptions breaks existing code that relies
      on graceful degradation, causing silent failures in variable-period moving average calculations
    derived_from_bd_id: BD-063
  - id: finance-C-165
    when: When using STOCHRSI (Stochastic RSI) indicator in momentum-based overbought/oversold analysis
    action: Use the default RSI and Stochastic parameters that align with traditional technical analysis conventions — must
      not use non-standard parameter values
    severity: high
    kind: domain_rule
    modality: must
    consequence: Using non-standard STOCHRSI parameters causes the indicator to produce momentum signals that deviate from
      market conventions, making comparison with other traders' analysis unreliable and potentially causing incorrect trading
      decisions
    derived_from_bd_id: BD-067
  - id: finance-C-166
    when: When configuring TA-Lib compatibility mode for indicator calculations
    action: Set compatibility mode to 0 (default TA-Lib calculation behavior) — must not set to mode 1 or other alternative
      calculation methods
    severity: high
    kind: domain_rule
    modality: must
    consequence: Setting compatibility mode to non-zero values causes TA-Lib functions to produce slightly different results
      for edge cases, breaking consistency with standard TA-Lib behavior and causing backtest-live discrepancies
    derived_from_bd_id: BD-070
  - id: finance-C-167
    when: When calculating Bollinger Bands (BBANDS) for trend visualization and signal generation
    action: Verify that BBANDS uses default parameters of 20-period MA and 2 standard deviations — these standard values verify
      cross-platform comparison consistency
    severity: medium
    kind: operational_lesson
    modality: should
    consequence: Using non-standard Bollinger Band parameters makes comparison with other traders' analysis difficult and
      reduces the indicator's utility as a market-standard tool, potentially causing misalignment in trading strategies
    derived_from_bd_id: BD-075
  - id: finance-C-168
    when: When implementing Three Black Crows (CDL3BLACKCROWS) candlestick pattern detection for bearish reversal signals
    action: Use the specific price relationship thresholds defined by the pattern detection logic — must not adjust thresholds
      to be more stringent or looser without explicit user configuration
    severity: high
    kind: domain_rule
    modality: must
    consequence: Altering CDL3BLACKCROWS detection thresholds changes the timing and frequency of bearish reversal signals,
      causing strategies to either miss valid reversal patterns or generate excessive false signals
    derived_from_bd_id: BD-076
  - id: finance-C-169
    when: When implementing parameter validation for wrapper functions that accept numeric arguments
    action: Raise TypeError immediately for type mismatches when float values are passed to integer parameters (e.g., 14.5
      for timeperiod=14) — do not silently truncate or coerce values
    severity: high
    kind: domain_rule
    modality: must
    consequence: Silent type coercion changes user intent without warning, causing subtle calculation errors in RSI, moving
      averages, and other indicator computations that are difficult to trace in production
    derived_from_bd_id: BD-047
  - id: finance-C-170
    when: When implementing wrapper functions that delegate to C/Cython implementations
    action: Use @wraps decorator or equivalent mechanism to preserve function metadata (name, docstring, annotations) from
      the underlying implementation
    severity: high
    kind: architecture_guardrail
    modality: must
    consequence: Without metadata preservation, function introspection, documentation generation, and IDE autocompletion fail,
      breaking Python tooling expectations and reducing developer productivity
    derived_from_bd_id: BD-049
  - id: finance-C-171
    when: When handling return values from wrapper functions that support both batch and streaming modes
    action: Detect streaming results by checking if the first result lacks __len__ attribute — use duck-typing to distinguish
      single scalar values from arrays/Series
    severity: high
    kind: domain_rule
    modality: must
    consequence: Incorrect type detection causes TypeError or silent data corruption when streaming scalar values are incorrectly
      treated as batch arrays or vice versa in downstream processing
    derived_from_bd_id: BD-050
  - id: finance-C-174
    when: When implementing the DataFrame input path for TA-Lib function calls
    action: Explicitly detect non-NPY_DOUBLE or non-C-contiguous arrays before calling C functions; if conversion is required,
      document the O(n) performance cost and warn users in high-frequency trading scenarios
    severity: high
    kind: architecture_guardrail
    modality: must
    consequence: Without explicit detection and warning, the multi-step DataFrame conversion (extract ndarray, convert to
      float64, make C-contiguous) creates hidden O(n) performance cost that causes unpredictable latency spikes in high-frequency
      trading with large arrays
    derived_from_bd_id: BD-097
  - id: finance-C-175
    when: When auditing coverage and maintaining mutual exclusion constraints between polars and pandas
    action: Consolidate BD-016 and BD-037 into a single canonical business decision to eliminate redundant maintenance risk;
      define scope unambiguously (single call vs session-level)
    severity: medium
    kind: operational_lesson
    modality: should
    consequence: Redundant constraints with ambiguous scope create maintenance risk where exception messages or behavior may
      diverge between two BDs, causing inconsistent enforcement of mutual exclusion rules
    derived_from_bd_id: BD-101
output_validator:
  assertions:
  - id: OV-01
    check_predicate: all(p in inspect.getsource(zvt.factors.algorithm.macd) for p in ['slow=26', 'fast=12', 'n=9'])
    failure_message: 'FATAL: MACD params drifted from (fast=12, slow=26, n=9) — SL-08 violation, non-reproducible signals'
    business_meaning: Standard MACD parameters are a semantic lock; drift makes results incomparable with industry-standard
      indicators and non-reproducible.
    source_ids:
    - SL-08
    - BD-036
  - id: OV-02
    check_predicate: result.get('total_trades', 0) > 0 or result.get('explicit_zero_trade_ack') is True
    failure_message: Zero trades executed — likely missing pre-fetched data (see PC-02) or over-restrictive filters
    business_meaning: A backtest with zero trades is not a valid result; either data is missing or the strategy never triggered.
      Structural non-emptiness check is insufficient — we need business confirmation.
    source_ids:
    - SL-01
    - finance-C-073
  - id: OV-03
    check_predicate: result.get('annual_return') is None or abs(float(result['annual_return'])) <= 5.0
    failure_message: 'FATAL: |annual_return| > 500% — likely look-ahead bias or data error'
    business_meaning: Annual returns exceeding 500% are physically implausible for A-share strategies; indicates look-ahead
      bias or corrupt data.
    source_ids: []
  - id: OV-04
    check_predicate: result.get('holding_change_pct') is None or abs(float(result['holding_change_pct'])) <= 1.0
    failure_message: 'FATAL: |holding_change_pct| > 100% — physically impossible'
    business_meaning: Holding change percentage cannot exceed 100%; violation indicates position accounting error.
    source_ids:
    - BD-029
  - id: OV-05
    check_predicate: result.get('max_drawdown') is None or abs(float(result['max_drawdown'])) <= 1.0
    failure_message: 'FATAL: |max_drawdown| > 100% — impossible for non-leveraged account'
    business_meaning: Maximum drawdown cannot exceed 100% without leverage; violation indicates calculation error or look-ahead
      bias.
    source_ids: []
  - id: OV-06
    check_predicate: not (hasattr(result, 'trade_log') and result.trade_log and any(result.trade_log[i].action == 'sell' and
      i+1 < len(result.trade_log) and result.trade_log[i+1].action == 'buy' and result.trade_log[i].timestamp == result.trade_log[i+1].timestamp
      for i in range(len(result.trade_log)-1)))
    failure_message: 'FATAL: buy-before-sell detected in same cycle — SL-01 violation, creates implicit leverage'
    business_meaning: SL-01 requires sell() before buy() in each cycle; violation means available_long was not updated before
      buying, risking duplicate positions.
    source_ids:
    - SL-01
  scaffold:
    validate_py_path: '{workspace}/validate.py'
    tail_block: "# === DO NOT MODIFY BELOW THIS LINE ===\nif __name__ == \"__main__\":\n    result = run_backtest()\n    from\
      \ validate import enforce_validation\n    enforce_validation(result, output_path=\"{workspace}/result.csv\")\n# ===\
      \ END DO NOT MODIFY ==="
  enforcement_protocol: 1. Never edit validate.py. 2. Never delete the DO NOT MODIFY tail block from the main script. 3. Never
    wrap enforce_validation() in try/except. 4. Never rewrite result write logic — it MUST go through enforce_validation.
    5. If validate.py raises ImportError, fix the dependency, do not remove the call.
acceptance:
  hard_gates:
  - id: G1
    check: '{workspace}/result.csv exists AND file size > 0'
    on_fail: Strategy did not produce output; check run_backtest() return value and enforce_validation() call
  - id: G2
    check: '{workspace}/result.csv.validation_passed marker file exists'
    on_fail: Validation did not complete; review validate.py output and fix assertion failures
  - id: G3
    check: 'Main script contains literal: from validate import enforce_validation'
    on_fail: Validation chain stripped; re-add the import in the DO NOT MODIFY block
  - id: G4
    check: 'Main script contains literal: # === DO NOT MODIFY BELOW THIS LINE ==='
    on_fail: Validation fence removed; regenerate DO NOT MODIFY tail block
  - id: G5
    check: 'result.csv has at least 1 row: pandas.read_csv(result.csv).shape[0] >= 1'
    on_fail: Empty result; check if trade_log is non-empty and factors generated signals. Confirm PC-02 (k-data exists) passed.
  - id: G6
    check: 'If MACD strategy: source contains ''slow=26'' AND ''fast=12'' AND ''n=9'' in algorithm call'
    on_fail: MACD params drifted from SL-08 lock; restore standard (12, 26, 9)
  - id: G7
    check: 'For data pipeline tasks: result.csv contains ''entity_id'' and ''timestamp'' fields'
    on_fail: Missing required columns; check Mixin.query_data return schema and DataFrame MultiIndex reset_index() before
      writing
  - id: G8
    check: 'OV-03 passes: abs(annual_return) <= 5.0 (500%)'
    on_fail: Physical plausibility check failed; investigate look-ahead bias or data corruption in input kdata
  soft_gates:
  - id: SG-01
    rubric: 'Strategy narrative consistency: user intent aligns with generated strategy.py logic. dim_a: signal direction
      (buy/sell) matches intent [1-5, pass>=4]; dim_b: frequency (daily/intraday) aligns [1-5, pass>=4]; dim_c: risk controls
      match user intent [1-5, pass>=4].'
  - id: SG-02
    rubric: 'Factor combination quality. dim_a: no highly correlated factor duplication [1-5, pass>=4]; dim_b: multi-period
      alignment correct [1-5, pass>=4]; dim_c: liquidity filter present for A-share [1-5, pass>=4].'
  - id: SG-03
    rubric: 'Data source selection appropriateness. dim_a: coverage sufficient for target entities [1-5, pass>=4]; dim_b:
      provider latency acceptable for strategy frequency [1-5, pass>=4]; dim_c: no unauthorized provider used without credentials
      [1-5, pass>=4].'
skill_crystallization:
  trigger: all_hard_gates_passed AND user_opt_out_skill_saving != true
  output_path_template: '{workspace}/../skills/{slug}.skill'
  slug_template: '{blueprint_id_short}-{uc_id_lower}'
  captured_fields:
  - name
  - intent_keywords
  - entry_point_script
  - validate_script
  - fatal_constraints
  - spec_locks
  - preconditions
  - install_recipes
  - human_summary_translated
  action: 'After all Hard Gates PASS, resolve slug via slug_template using the executed UC, then write the .skill YAML file
    at output_path_template. Notify user in their detected locale: ''Skill saved as {slug}.skill — next time say one of {sample_triggers}
    from the matched UC to invoke directly.'''
  violation_signal: All hard gates passed but no .skill file exists at expected path
  skill_file_schema:
    name: finance-bp-109 / TA-Lib Documentation HTML Generator
    version: v5.3
    intent_keywords:
    - documentation generation
    - html pages
    - pygments stylesheet
    - markdown to html
    - code highlighting
    entry_point: run_backtest
    fatal_guards:
    - SL-01
    - SL-02
    - SL-03
    - SL-04
    - SL-05
    - SL-06
    - SL-07
    - SL-08
    - SL-10
    - SL-11
    - SL-12
    spec_locks:
    - SL-01
    - SL-02
    - SL-03
    - SL-04
    - SL-05
    - SL-06
    - SL-07
    - SL-08
    - SL-09
    - SL-10
    - SL-11
    - SL-12
    preconditions:
    - PC-01
    - PC-02
    - PC-03
    - PC-04
post_install_notice:
  trigger: skill_installation_complete
  message_template:
    positioning: I help you build quant strategies on A-share with ZVT — from data fetch to backtest, one flow.
    capability_catalog:
      group_strategy:
        source: auto_grouped
        strategy_reason: no candidate field had 2-7 distinct values; all capabilities collapsed into single group
      groups:
      - group_id: all
        name: All Capabilities
        description: ''
        emoji: 📦
        uc_count: 1
        ucs:
        - uc_id: UC-101
          name: TA-Lib Documentation HTML Generator
          short_description: 'Converts TA-Lib markdown documentation into styled HTML pages for web publishing, and generates
            Pygments syntax highlighting CSS for code examples in '
          sample_triggers:
          - documentation generation
          - html pages
          - pygments stylesheet
    call_to_action: Tell me which one you want to try.
    featured_entries:
    - uc_id: UC-101
      beginner_prompt: Try ta-lib documentation html generator
      auto_selected: true
    - uc_id: UC-100
      beginner_prompt: Try capability UC-100
      auto_selected: true
    - uc_id: UC-101
      beginner_prompt: Try capability UC-101
      auto_selected: true
    more_info_hint: Ask me 'what else can you do?' to see all 1 capabilities.
  locale_rendering:
    instruction: On skill_installation_complete, translate ALL user-facing strings (positioning + capability_catalog.groups[].name
      + capability_catalog.groups[].description + capability_catalog.groups[].ucs[].short_description + call_to_action + featured_entries[].beginner_prompt
      + more_info_hint) into detected user locale per locale_contract. Preserve UC-IDs, group_id, emoji, and sample_triggers
      verbatim.
    preserve_verbatim:
    - UC-IDs
    - group_id
    - emoji
    - sample_triggers
    - technical_class_names
  enforcement:
    action: 'Host agent MUST send composed message to user as the FIRST user-facing response after skill_installation_complete
      event. Message MUST contain: positioning, capability_catalog (rendered as markdown tables per group), 3 featured_entries,
      call_to_action, and more_info_hint.'
    violation_code: PIN-01
    violation_signal: First user-facing message post-install does not contain the full capability_catalog (all UCs grouped)
      OR skips featured_entries OR skips call_to_action.
human_summary:
  persona: Doraemon
  what_i_can_do:
    tagline: 'I help you build quant strategies on A-share with ZVT — from data fetch to backtest, one flow. Just tell me
      what you want; I''ll write the code, you don''t have to dig docs. (Heads up: ZVT natively supports A-share, HK, and
      crypto. US stocks — stockus_nasdaq_AAPL — are half-baked; don''t bother for serious work.)'
    use_cases:
    - TA-Lib Documentation HTML Generator
    - A-share MACD daily golden-cross backtest with hfq price adjustment from eastmoney
    - 'End-to-end ZVT pipeline: FinanceRecorder + GoodCompanyFactor + StockTrader'
    - Multi-factor strategy with TargetSelector (AND mode) combining MACD + volume breakout
    - Index composition data collection (SZ1000, SZ2000) with EM recorder
    - Institutional fund holdings tracker via joinquant_fund_runner pattern
    - Custom Transformer + Accumulator factor with per-entity rolling state
  what_i_auto_fetch:
  - ZVT stage pipeline structure (data_collection → visualization) from LATEST.yaml
  - Semantic locks (SL-01 through SL-12) — especially sell-before-buy ordering and MACD params
  - Fatal constraints (finance-C-*) relevant to your target strategy type
  - 'Default parameters: MACD(12,26,9), hfq adjustment, buy_cost=0.001, base_capital=1M CNY'
  - Entity ID format (stock_sh_600000) and DataFrame MultiIndex convention
  - Provider-specific recorder class names and required class attributes
  what_i_ask_you:
  - 'Target market: A-share (default), HK, or crypto? (US stocks in ZVT are half-baked — stockus_nasdaq_AAPL exists but coverage
    is thin)'
  - 'Data source / provider: eastmoney (free, no account), joinquant (account+paid), baostock (free, good history), akshare,
    or qmt (broker)?'
  - 'Strategy type: MACD golden-cross, MA crossover, volume breakout, fundamental screen, or custom factor?'
  - 'Time range: start_timestamp and end_timestamp for backtest period'
  - 'Target entity IDs: specific stocks (stock_sh_600000) or index components (SZ1000)?'
  locale_rendering:
    instruction: On first user contact, translate all fields above into detected user locale while preserving Doraemon persona
      (direct, frank, mildly snarky, knows limits).
    preserve_verbatim:
    - BD-IDs
    - SL-IDs
    - UC-IDs
    - finance-C-IDs
    - class_names
    - function_names
    - file_paths
    - numeric_thresholds


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector:  ()