xingwudao/open-xquant/build-report-charts

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.

Report Chart Builder

Round 26: default_professional_chart_pack is versioned with a canonical requested set; caller subsets fail exact requested equality. Omitted charts are generated or recorded with a closed skip reason. Use an unsealed report revision attempt, fresh report_revision_id on chart retry, and seal only after chart completion.

Use this skill after a run exists and the experiment report needs charts. Final research reports need charts by default: build the Default Professional Chart Pack automatically, save generated figures as experiment assets, and register them before handing the final narrative to write-research-report.

For an explicit ad hoc chart request that is not part of final report writing, the Agent may discuss chart requirements before plotting. Do not use that interactive mode to delay or skip the default report chart pack.

Version-Governed Chart Package

Before writing chart artifacts, read current.json and use active_version as version_id. Read source run artifacts from:

<phase_paths.09_backtests>/<run_id>/

For current production, stage chart assets for the supplied immutable report revision and publish them under:

<phase_paths.10_reports>/<run_id>/candidates/<report_revision_id>/report_assets/manifest.json
<phase_paths.10_reports>/<run_id>/candidates/<report_revision_id>/report_assets/figures/<figure>.png
<phase_paths.10_reports>/<run_id>/candidates/<report_revision_id>/report_assets/scripts/<script>.py
<phase_paths.10_reports>/<run_id>/candidates/<report_revision_id>/chart_build_result.json

Do not write root-level report_assets/. Do not place final report assets outside the version's 10_reports/<run_id>/ package.

Workflow

1. Confirm the run directory and required artifacts exist.

• Read metrics.json, equity_curve.csv, benchmark_curve.csv,

trades.csv, orders.csv, positions.csv, and target_weights.csv only if present.

• scan the run directory for available data assets before recommending

charts.

• Do not modify metrics.
• Do not modify audit artifacts.

1. Resolve chart mode and recommend a chart set.

• Default Report Mode: when invoked by oxq-report-writer-worker,

write-research-report, the coordinator's post-run auto-advance, or any final report task without an explicit chart list, set chart_decision: default_professional_chart_pack and build the Default Professional Chart Pack automatically.

• Do not ask the user to confirm the default report chart batch.
• Do not omit charts merely because the user did not request them.
• Use the Chart Applicability Matrix below to decide which default charts are

applicable from available artifacts.

• List the recommended chart set sorted by rotation-strategy value and data

availability.

• Skip an individual default chart only when its source artifact is missing,

empty, or structurally insufficient. Record the skipped chart and reason in the chart result or manifest notes; do not treat the whole report as chart-free.

• For explicit ad hoc chart tasks outside report auto-advance, discuss chart

requirements, ask what decision the chart should support, clarify chart type, time range, benchmark, grouping, and labels, then ask the user to confirm that custom batch before generating charts.

• Explain when a useful or requested chart cannot be produced from available

data.

1. Write plotting Python.

• Build a small script in temporary staging whose final relative key will be

report_assets/scripts/<script>.py.

• Read run artifacts from the run directory.
• Render figure outputs into temporary staging. Their final relative keys

will be under report_assets/figures/; do not render directly into the governed report package.

• Keep plotting deterministic and local; do not download new data unless the

user explicitly asks.

• Require seaborn for the default open-xquant report chart style. The

project chart extra includes seaborn>=0.13; if import fails, treat it as an environment problem and fix the chart environment or block with a clear message; do not silently downgrade to arbitrary Matplotlib defaults.

• In a source worktree, run the staged plotting script with

uv run --extra chart python <temporary_staging>/<script>.py so the chart extra is active. In an installed SDK bundle, verify import seaborn works in the runner environment before plotting.

• Use the open-xquant Report Chart Style below in every generated script

before plotting any figure.

import matplotlib
matplotlib.use("Agg")
import matplotlib.pyplot as plt
import seaborn as sns
OXQ_REPORT_STYLE = {
    "figure.figsize": (12, 6.75),
    "figure.dpi": 160,
    "savefig.dpi": 180,
    "axes.facecolor": "#FFFFFF",
    "figure.facecolor": "#FFFFFF",
    "axes.edgecolor": "#D8DEE9",
    "axes.grid": True,
    "grid.color": "#E6EAF0",
    "grid.linewidth": 0.8,
    "axes.spines.top": False,
    "axes.spines.right": False,
    "axes.titleweight": "semibold",
    "axes.titlesize": 15,
    "axes.labelsize": 11,
    "xtick.labelsize": 10,
    "ytick.labelsize": 10,
    "legend.fontsize": 10,
    "legend.frameon": False,
    "lines.linewidth": 2.2,
    "lines.markersize": 5,
    "font.family": "sans-serif",
    "font.sans-serif": [
        "PingFang SC",
        "Noto Sans CJK SC",
        "Microsoft YaHei",
        "SimHei",
        "Arial Unicode MS",
        "DejaVu Sans",
    ],
    "axes.unicode_minus": False,
}
OXQ_PALETTE = [
    "#2563EB",  # strategy / primary
    "#6B7280",  # benchmark / neutral
    "#0891B2",  # exposure
    "#D97706",  # cost / stress
    "#7C3AED",  # secondary factor
    "#374151",  # text-adjacent series
]
sns.set_theme(style="whitegrid", context="notebook", palette=OXQ_PALETTE, rc=OXQ_REPORT_STYLE)
plt.rcParams.update(OXQ_REPORT_STYLE)
def market_return_colors(market_region: str) -> tuple[str, str]:
    """Return positive and negative colors for bar/heatmap returns."""
    if market_region == "cn":
        return "#D62728", "#2CA02C"  # red-up / green-down
    return "#059669", "#DC2626"

• Set figure text language from the report language. Default to Chinese

labels when the report language is Chinese; use the font fallback above and inspect the final PNG for readable CJK text. If CJK rendering is unavailable after environment repair, use concise English labels and keep Chinese captions in the report.

• For a custom chart requested by the user, keep the same OXQ_REPORT_STYLE,

palette, figure size, title weight, grid, source-artifact caption, and registration rules unless the user explicitly asks for a different style.

• For return bars and heatmaps, resolve a string region such as

market_region = market.get("region") or spec.market.region, then use market_region == "cn" to select red-up / green-down colors; use green-up / red-down outside China.

1. Publish generated assets as one batch.

Generate every figure and source script in temporary staging, construct the complete next manifest from those exact bytes, and route the figure, script, obsolete-file deletion, and report_assets/manifest.json set through publish_report_artifacts(report_dir, artifacts, *, lock_subject=None). The mapping uses safe relative keys and complete bytes; None deletes an obsolete asset. Use a callable builder when the manifest depends on the current package: the callable builder executes under the final-selection lock, performs its baseline check there, and commits an atomic all-or-rollback batch. Do not write any target directly and do not invoke an asset CLI path that publishes files or the manifest outside this batch.

Keep the two relative-path namespaces distinct. Manifest asset path values are relative to the report_assets/manifest.json package, so figure values use figures/<name>.png, and source.script values use scripts/<name>.py; a manifest value is never report_assets/figures/<name>.png. Publisher mapping keys remain relative to the report directory and therefore use report_assets/manifest.json, report_assets/figures/<name>.png, and report_assets/scripts/<name>.py. In research_report.md and rendered HTML, the report image URL remains report_assets/figures/<name>.png because those documents are also relative to the report directory.