xingwudao/open-xquant/build-strategy-spec

Phase Path Containment Preflight

Before any phase artifact read, write, directory creation, command, or handoff, run this preflight completely and block on any failure:

1. Read .open-xquant/workspace.yaml. Resolve version_root from

paths.versions_dir, using versions only when that key is absent. Require version_root to be a safe workspace-relative path: reject an absolute path or any .. path segment, resolve it canonically with symlinks, and require the result to stay inside the workspace.

1. Read current.json. For normal phase work, set expected_version_id to

current.json.active_version; it must exist. Only a contract that explicitly owns cross-version inspection may instead set expected_version_id from the referenced version id for that historical read. This exception never permits active-version work to consume another version.

1. Set the intended version directory to

<version_root>/<expected_version_id>/ and resolve it canonically. Require the intended version directory to remain inside the canonical version root and workspace; otherwise treat it as a symlink escape. Read version_manifest.json only from that exact directory. The manifest version_id must equal expected_version_id; for normal phase work it therefore must also equal current.json.active_version.

1. Before using each required phase_paths value, require a non-empty

workspace-relative string. Reject an absolute path and any .. path segment. Resolve <workspace>/<phase_path> canonically, including existing symlink ancestors even when the leaf will be created, and require the target to be the intended version directory or a descendant of it. A symlink escape outside that directory is invalid.

1. On any identity or path failure, stop before phase artifact reads, writes,

directory creation, commands, or handoffs. Do not normalize an unsafe path into acceptance and do not fall back to a default phase path.

Block examples when expected_version_id is v001 include strategy_store/v001/../v002/04_spec_build, strategy_store/v002/04_spec_build, /tmp/04_spec_build, and strategy_store/v001/escape/04_spec_build when escape is a symlink whose target is outside the intended version directory. An allowed custom nested phase path is strategy_store/v001/custom/phases/04_spec_build when its canonical target remains under the intended version directory.

For a new-version bootstrap, only manage-strategy-version may proceed before the new manifest exists or the new id becomes active. It must apply the same workspace-relative, traversal, canonical-containment, and symlink checks to every constructed phase path before directory creation, then write a matching manifest before publishing current.json last.

Version Path Resolution

Before using any <phase_paths.*> or <version_root> placeholder, read .open-xquant/workspace.yaml. Resolve version_root from paths.versions_dir; use versions only when that key is absent. Require a safe relative path whose resolved target stays inside the workspace. Then read <version_root>/<version_id>/version_manifest.json and use its exact phase_paths entry for each phase. For example, a configured root of research_versions must resolve the spec-build phase to research_versions/v003/04_spec_build; never redirect it to a default-root phase path.

Strategy Builder

Build or edit strategy_spec.yaml from an audited strategy idea brief. This skill owns only the SPEC build phase in a multi-Agent research workflow.

Read-Only Validation-Only Mode

When the router asks only to validate an existing SPEC, use this mode instead of the builder workflow below. Run <resolved_runner> spec validate <existing_strategy_spec.yaml> and report the validator result without writing files. This mode does not require strategy_idea_brief.json and does not require strategy_idea_audit.json.

• Do not run oxq registry export or any equivalent catalog export.
• Do not create or modify builder_phase_result.json.
• Do not create or modify spec_mapping_contract.json.
• Do not create or modify spec_mapping_notes.md, component_catalog.json,

or the existing SPEC.

• Do not apply the builder input gates, output ownership rules, or phase-result

requirements below. They apply only to normal builder mode.

Reference Loading

Read these one-level references only when the matching work is needed:

• references/spec-shape-and-candidates.md: SPEC YAML shape, stable candidate

values, tradability, lag, timing, warmup, and latest_available rules.

• references/source-mapping-and-catalog.md: source mapping, unsupported

disclosure, mapping-contract fields, component catalog query patterns, canonical recipe selection, and cross-sectional feasibility.

• references/builder-output-schema.md: open-xquant version provenance,

validation commands, builder_phase_result.json, and output schema.

Version-Governed Artifact Gate

Before any catalog export, SPEC initialization, SPEC edit, or validation, read current.json and use active_version as version_id. If no active version exists, block and return to manage-strategy-version.

The required audited idea inputs are:

<phase_paths.01_brainstorm>/strategy_idea_brief.json
<phase_paths.02_idea_audit>/strategy_idea_audit.json

This builder may write only inside:

<phase_paths.04_spec_build>/

Required outputs are:

<phase_paths.04_spec_build>/strategy_spec.yaml
<phase_paths.04_spec_build>/component_catalog.json
<phase_paths.04_spec_build>/spec_build_notes.md
<phase_paths.04_spec_build>/spec_mapping_notes.md
<phase_paths.04_spec_build>/spec_mapping_contract.json
<phase_paths.04_spec_build>/builder_phase_result.json

Do not write root-level strategy_spec.yaml, component_catalog.json, spec_build_notes.md, spec_mapping_notes.md, spec_mapping_contract.json, or builder_phase_result.json.

Scope

Do:

• require strategy_idea_brief.json and passing strategy_idea_audit.json

before any SPEC or catalog work

• convert the audited strategy idea into strategy_spec.yaml
• use the component catalog and canonical recipes before choosing components
• preserve explicit user requirements and user-confirmed candidate values
• write concise spec_build_notes.md when component or recipe choices matter
• write spec_mapping_notes.md and spec_mapping_contract.json that map

audited idea fields to executable SPEC fields and disclose unsupported fields

• inventory every flattened source field in source_fields and require exactly

one field_mappings row for each inventory entry before builder pass

• run deterministic spec validation
• write builder_phase_result.json for the downstream orchestrator

Do not:

• produce spec_audit.json
• approve assumptions on behalf of the user
• call audit skills
• ask the user to complete brainstorm phases
• inspect, list, or read market data files, parquet files, manifests, or

provider directories

• download market data
• run oxq strategy compile
• run oxq backtest run
• attach provenance for runs, backtests, monitoring, or reports
• run monitoring, robustness, report writing, or report review
• describe an unaudited spec as ready for formal research

Audited Idea Input Gate

Before doing any SPEC work, require both artifacts:

• strategy_idea_brief.json
• strategy_idea_audit.json

The idea audit must have status: pass, idea_workflow_pass: true, and next_required_phase: build. If either artifact is missing, stale, blocked, or failing, stop and return a blocked builder_phase_result.json with next_required_phase: brainstorm.

Hard gate:

• Do not run oxq spec init before strategy_idea_audit.json passes.
• Do not run oxq registry export before strategy_idea_audit.json passes.
• Do not write or edit strategy_spec.yaml before strategy_idea_audit.json

passes.

If the audited brief contains unresolved defaults, candidates, contradictions, or missing phase evidence, do not choose values. Return the issue to brainstorm-strategy-idea through the coordinator.

Runner Resolution

In a new research directory, uv run oxq may fail because open-xquant is installed as a long-lived Agent capability, not as a package in that directory. Before running commands after the audited idea gate passes:

1. Read ~/.config/open-xquant/agent.yaml.
2. Prefer preferred_runner_argv when the shell tool accepts argv; otherwise

use preferred_runner in place of uv run oxq.

1. If it is missing or fails, read ~/.config/open-xquant/agent-install.json,

take sdk_bundle.runner.argv or sdk_bundle.runner.oxq, and use that cached runner.

Keep the shell in the user's research directory. Do not search unrelated home directories for another open-xquant checkout.

When this skill needs a Python SDK snippet in an installed research workspace, use the resolved runner's virtualenv Python from the same bin directory as the runner. oxq run python does not exist, and uv run python is only appropriate inside a source checkout where oxq is installed for that project.

Provenance And SPEC Shape

Every generated strategy_spec.yaml must distinguish the SPEC schema version from the open-xquant package version:

• schema_version is the SPEC schema version.
• required_oxq_version is the open-xquant package version used by the

resolved runner for this builder phase.

Do not change schema_version to the package version. When writing or materially editing strategy_spec.yaml, write required_oxq_version from the resolved runner/package version. If the runner cannot report a version, block instead of emitting a SPEC with an empty required_oxq_version.

Use references/spec-shape-and-candidates.md before writing or repairing SPEC fields. It contains the current StrategySpec YAML shape and stable candidate value rules.

Data Inspection Boundary

This builder does not own data coverage or data quality investigation. Do not list data_dir, read parquet files, inspect columns, call list_symbols, call inspect_symbol, or resolve date coverage from local market data. The explore-data skill and oxq-data-inspection-worker own those actions and write:

<phase_paths.05_data_inspection>/data_inspection_result.json
<phase_paths.05_data_inspection>/data_availability_report.md

The builder may use a data fact only when it is already present in the audited idea, explicitly confirmed by the user, or recorded in a prior data_inspection_result.json for the active version. Cite that artifact in spec_build_notes.md and spec_mapping_contract.json.

If latest_available, required column coverage, common symbol date range, price adjustment evidence, provider readiness, or suspension/tradability data availability is unknown, do not infer it and do not inspect the files. Return status: blocked with next_required_phase: data_inspection. If a prior data inspection artifact says required data is unavailable, preserve the requested strategy semantic in spec_mapping_contract.json and block instead of removing the requirement from the SPEC.

SPEC Audit Repair Handoff

When a blocked SPEC audit result returns next_required_phase: build, read <phase_paths.06_spec_audit>/spec_audit.json and audit_notes.md before editing the SPEC. The auditor is read-only and does not repair YAML. The builder owns the repair.

For contradictions that include effective_field_path, source_yaml_path, and builder_required_fix: