xingwudao/open-xquant/review-research-report

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.

Research Report Reviewer

Round 26: review consumes sealed revisions only. Missing-chart retry uses a fresh unsealed report revision attempt and must seal only after chart completion. Historical refresh follows write -> review -> lineage -> prepare new selection -> comparison -> resume with fresh selection and candidate hashes.

Use this skill after write-research-report has sealed the supplied immutable report revision, HTML has been rendered from the same Markdown, and deterministic artifact QA has run against that exact candidate directory.

oxq report qa checks files, dates, registered image references, manifest integrity, hashes, and dimensions. This skill reviews the research meaning: whether the report's decision, explanation, risk language, and chart narrative are faithful to the artifacts.

Version-Governed Review Gate

For normal phase work, read current.json and use active_version as version_id. Read the source run package from:

<phase_paths.09_backtests>/<run_id>/

Read final report artifacts from:

<phase_paths.10_reports>/<run_id>/candidates/<report_revision_id>/research_report.md
<phase_paths.10_reports>/<run_id>/candidates/<report_revision_id>/research_report.html
<phase_paths.10_reports>/<run_id>/candidates/<report_revision_id>/writer_result.json
<phase_paths.10_reports>/<run_id>/candidates/<report_revision_id>/candidate_manifest.json

Write the semantic review only to:

<phase_paths.10_reports>/<run_id>/reviews/<review_revision_id>/report_review.json

Do not write root-level report_review.json. The old direct path <phase_paths.10_reports>/<run_id>/report_review.json is a historical recognition target only and must not be replaced.

Historical Schema-1 Handoff Recognition

Any explicit inactive candidate whose review is missing or stale may be reviewed while another version is active, including a candidate with a stale current-schema report_review.json. The coordinator must use exactly this field inventory only when recognizing an old handoff. It is not a current producer request and must be translated to candidate_scoped_historical_report_revision before any write:

{
  "mode": "candidate_scoped_historical_rereview",
  "version_id": "v001",
  "run_id": "runA",
  "current_state_guard": {
    "path": "current.json",
    "active_version": "v002",
    "sha256": "sha256:0000000000000000000000000000000000000000000000000000000000000000"
  },
  "reason": "stale_report_review",
  "requested_by_role": "oxq-coordinator"
}

Validate the exact handoff fields before any candidate read. Require reason to be missing_report_review or stale_report_review and require direct evidence that the exact target review is absent or fails the normal current identity, schema, inventory, digest, decision-input, reviewed-artifact, or report-asset checks. Artifact age and schema age are not eligibility conditions. Require the guard path to be exactly current.json, hash its exact initial bytes, and require its active version and hash to match the handoff. Set expected_version_id and run_id only from the explicit handoff, then resolve <version_root>/v001/version_manifest.json and that manifest's exact run and report phase paths. Apply the same canonical containment, direct-child, identity, full-integrity, and pre/post review checks as normal mode. In the illustrated active-v002/historical-v001 case, the report reviewer must not change current.json, any version/phase state, or the active run; this mode does not reactivate v001.

Rerun deterministic report QA against the exact historical report package, but do not publish or replace the direct report_review.json. Publish a fresh schema-version-2 review revision against a fresh immutable report revision as defined below; do not backfill fields or hashes into the old payload. Re-read and rehash current.json immediately before and after publication and require the guard to remain unchanged. This remains a candidate-scoped historical re-review even though its current producer writes immutable candidate and review revisions. The coordinator then follows this regeneration order: rerun artifact lineage audit for v001/runA, regenerate every comparison that cites its old review or lineage evidence, and rerun final selection into a new selection directory. Historical re-review completion is evidence regeneration, not active phase completion, so it must not trigger version-manager state updates.

Inputs

Read:

• research_report.md and research_report.html
• strategy_spec.yaml, especially decision_policy
• spec_audit.json, including field provenance, recipe matches,

component audits, missing requirements, agent-added fields, contradictions, and blocking findings

• compiled_plan.json and runtime_audit.json
• metrics.json and execution_assumptions.json
• research_bias_audit.json and reproducibility_audit.json
• robustness.json, including perturbation and regime analysis sections
• report_assets/manifest.json, captions, source scripts, and figure files
• equity_curve.csv, benchmark_curve.csv, trades.csv, positions.csv,

and target_weights.csv when needed to verify a claim

• the deterministic oxq report qa output
• optional/advisory numeric QA output when available, especially any

numeric_claim_unverified warnings

• writer_result.json, especially the resolved language

Do not rewrite metrics, audits, robustness output, backtest artifacts, Markdown, or HTML. This skill reviews the report and writes report_review.json; it does not edit the report. If a report edit is needed, return a blocking finding for the upstream writer phase.

Review Artifact Identity

Before evidence consumption and again immediately before publication, independently invoke validate_run_artifact_inventory(run_dir) independent of the digest-row check. Treat its immutable return value as authoritative and require profile.contract_schema_version == RUN_ARTIFACT_INVENTORY_SCHEMA_VERSION == 1. Select the exactly one current digest row separately and require digest_row.artifact_inventory == {"schema_version": 1, "profile": profile.name}. The profile is derived only from artifact_hashes.json.schema_version: accept the runtime-defined artifact_hashes_v0_legacy through artifact_hashes_v5 profiles and reject omission, unknown or unbound extensions, aliases, duplicates, unsafe or stale bindings, and profile downgrade or mismatch. A digest-row pass never substitutes for this executable inventory call.

The review is valid only for the exact final evidence it inspected. Before semantic review, require exactly one valid matching run_id row in <phase_paths.09_backtests>/run_digests.jsonl, recompute the producer's canonical current run digest from the direct run's current artifact_hashes.json, and require equality. This has the same row-cardinality and current-manifest semantics as require_current_run_digest().

require_current_run_digest() is not the complete current-evidence gate. Regardless of helper implementation, callers must independently validate the producer-required manifest inventory and transitive bindings. Before semantic review and again immediately before publication, perform full manifest-entry integrity validation. Parse artifact_hashes.json as an object; derive all required entries from its producer schema; and validate every non-metadata entry. Each entry must name a safe relative current regular file below the exact direct run with no duplicate canonical target or symlink escape. Recompute every value with the producer's artifact-specific algorithm, including canonical-JSON exclusions, and require equality. Reject missing required entries, missing or extra governed targets, malformed digests, and stale entries.

A mutation without a manifest refresh must block even though the canonical manifest digest still matches the registry. A mutation followed by an integrity refresh changes the manifest and run digest and therefore invalidates the old review. Both the manifest-entry check and the digest-row check are mandatory at the pre-review and post-review gates; neither substitutes for the other.