| name | heliosi-501-corpus |
| version | 0.1.0 |
| description | Use when the user asks about HelioSI, the heliophysics paper-skill corpus, the 501-skill corpus, paper-to-skill compilation, generating hypotheses or experiments from heliophysics literature, selecting corpus entries by topic (PFSS, open flux, PSP switchbacks, SEPs, turbulence, solar-wind classification, instruments, MHD, agent-runtime design), or deciding which papers to verify against full text. |
| allowed-tools | Read, Grep, Glob, Bash |
HelioSI 501-Skill Corpus (aggregator)
Verification status (read first)
This corpus is a scaffold / triage substrate, not a fully verified
reproduction corpus. Concretely, as of the current snapshot:
- A large fraction of entries still carry one or more
TODO_verify_with_full_text / TODO verify markers in non-authorship
prose fields of their metadata.yaml / SKILL.md (venue, DOI, numerical
targets, etc.). These are intentional triage markers, not claims.
- T3 + T4 = 424 / 501 entries (85 %) are in the
paper-grounded-pending-full-text (T3, 266) or stub / scaffold (T4, 158)
maturity tiers — i.e. the Layer-1 claim and Layer-2 contract are authored
but the paper has not been verified end-to-end against full text and no
end-to-end run has been recorded against the bundled corpus.
- Only 1 / 501 entries (T1:
wu-2026-nonspherical-coronal-magnetic-field-open-flux)
carries a documented local numerical reproduction; that reproduction's
code lives in a separate internal repository and is not shipped here.
When citing or composing from this corpus, treat every entry's identifiers
(DOI, arXiv, ADS), numerical targets, and author lists as provisional
until the full paper has been read. Surface the TODO_verify gap to the
user — do not paper over it.
Authorship fields specifically (issue #8 hygiene)
Authorship is the only dimension on which the corpus refuses to ship
placeholder strings as data:
metadata.yaml first_author / authors[] and the per-entry
SKILL.md frontmatter paper.first_author / paper.authors[] are
guaranteed to contain no TODO / TBD placeholder strings
(enforced by scripts/validate.sh section S4d and
tests/test_authorship_hygiene.py).- Unverified author scalars are
null; unverified author lists are []
or a list of only the real authors that were recoverable from the
local source. Entries where authorship is unknown carry an explicit
authors_verified: false flag; entries with a partial author list
carry authors_complete: false.
- The
authors_verified: false flag is kept in bidirectional parity
between metadata.yaml (top-level) and SKILL.md frontmatter
(paper.authors_verified): a consumer reading either surface alone
sees the same disclosure (enforced by scripts/validate.sh section
S4f and tests/test_authorship_flag_parity.py).
- The surname embedded in a slug (e.g.
paper-mason-2026-…) is not
asserted as the verified first author. Do not promote it to
first_author without independent confirmation.
Do not cite first_author / authors from this corpus without
independent verification.
arXiv IDs specifically (issue #9 hygiene)
Per-entry metadata.yaml carries an arXiv ID at top-level arxiv: and
per-entry SKILL.md frontmatter mirrors it at paper.arxiv_id: (or
top-level arxiv_id: for the minimal-frontmatter schema). The presence
of an ID is not a verification claim. To distinguish verified from
merely advertised IDs the entry must carry an
provenance.id_verifications[] record in metadata.yaml, for example:
provenance:
id_verifications:
- arxiv_id: "2601.20624"
url: "https://arxiv.org/abs/2601.20624"
http_status: 200
fetched_title: "..."
title_match: true
status: arxiv-http-title-match
fetched_at: "2026-05-19T07:20:21Z"
source: live
A record with status: arxiv-http-title-match means a one-shot HTTP GET
of https://arxiv.org/abs/<id> returned HTTP 200 and the live page's
<title> matched the entry's recorded title after normalization. CI
checks this block structurally (scripts/validate.sh S4e and
tests/test_arxiv_provenance.py) without doing any live network call;
live verification is the responsibility of scripts/verify_arxiv_ids.py.
Current snapshot: only 28 / 531 advertised arXiv-ID slots have a structured id_verifications[] HTTP-title-match record (~5 % verified); treat the rest as advertised-but-unverified until a live check records provenance.
Without a provenance.id_verifications[] record, treat an arXiv ID as
unverified, regardless of how plausible its numeric suffix looks. Issue
#9 originally hypothesized that six 2025/2026 IDs with high numeric
suffix (2511.03905, 2512.24749, 2601.08999, 2601.20624,
2603.11329, 2604.21639) might be hallucinated; live verification
confirmed all six resolve to HTTP 200 with matching titles. High suffix
alone is not evidence of hallucination — the audit-trail block is.
What this is
A single Claude Code aggregator skill that exposes a curated corpus of 501 harness-agnostic paper-skills across 18 batches of heliophysics literature (PFSS / open flux, PSP & Solar Orbiter inner heliosphere, SEPs & shocks, turbulence & heating, solar-wind classification & ML, instruments & data products, coronal CME/flares, waves/instabilities/reconnection, agent-runtime & evaluation design, plus pilots). The corpus is authored against an up-to-four-layer model, populated as each entry matures:
- Scientific invariant (claim, assumptions, failure modes, validation targets) — present on every entry.
- Executable protocol against abstract capabilities (Layer-2 contract) — populated at method-ready promotion.
- Adapter / runtime notes (Layer-3 example bindings only) — optional; populated when a runtime binding is documented.
- Research-generation affordances (gaps, tensions, composable experiments) — populated when the entry exposes hypothesis seeds.
The "four-layer model" is the authoring spec, not a per-entry invariant: stub and scaffold entries deliberately ship with Layers 2/3/4 marked false in their layers: frontmatter block until they are promoted. See references/corpus_qa_report_v2.md §9 for the current fully-populated vs partially-populated breakdown (issue #58), and scripts/audit_layer_population.py to recompute it.
The corpus is structural and bibliographic. It is not 501 reproduced experiments.
When to use
- "What's in the HelioSI corpus?" / "Show me the 501-skill index."
- "Find corpus entries about " (PFSS, open flux, switchbacks, alpha/proton, reconnection, SEP, kappa, GCS, foundation model, …).
- "Generate a hypothesis from cross-skill tensions."
- "Which entries are worth verifying against full text first?"
- "Convert this corpus entry into a runtime-specific experiment plan."
Bundle layout
heliosi-501-corpus/
├── SKILL.md (this file)
├── README.md install + smoke test
├── VALIDATION.md bundle integrity report
├── scripts/
│ ├── search_corpus.py stdlib helper
│ ├── validate.sh structural validation
│ └── verify_arxiv_ids.py live arXiv-ID provenance verifier (opt-in)
└── references/
├── corpus_index_v2.md human-readable index
├── corpus_qa_report_v2.md count audit + claim boundaries
├── corpus_manifest_v2.json machine roll-up (501 entries)
└── corpus/ 18 batches × per-entry SKILL.md + metadata.yaml
Companion MCP adapters (external, not bundled)
The corpus's Layer-2 contracts are runtime-neutral by design, but two
first-class MCP adapters exist as separate repositories that a
consumer may install to satisfy common Layer-2 capabilities:
These are the only domain MCPs that this skill treats as first-class
companions — the rest of the named adapters in the corpus
(sunkit-magex, sw-scanner, ENLIL, EUHFORIA, MAS, Surya,
pyspedas / HAPI loaders, …) appear only as Layer-3 example
bindings.
Important constraints — none of these are bundled in this repository:
- Neither MCP ships inside
heliosi-501-corpus-skill. The aggregator
skill is self-contained at runtime (Python stdlib only); the two
MCPs add capabilities on top when present.
- Treat both as optional consumer-side adapters. Do not assume a
given runtime has
xhelio-spice or xhelio-cdaweb installed — check
the user's MCP inventory before issuing tool calls against them. If a
Layer-2 capability needs SPICE or CDAWeb access and neither MCP is
configured, surface the binding gap as a prerequisite rather than
inventing a fallback.
- Citing one of these MCPs is not a verification claim about the
underlying paper-skill. A corpus entry that lists "loads MAG via
CDAWeb" still has its Layer-1
TODO_verify_with_full_text markers
unaffected by the MCP being available.
The corpus's metadata.yaml adapter_notes[] entries point at these
MCPs where a binding example is appropriate, but the Layer-2 contract
itself never names them — the contract is the abstract capability
(C-FETCH-DATA, C-EPHEMERIS, …), and the MCP is one possible
fulfilment.
How to use this skill (do NOT bulk-load)
The corpus is ~8 MB of structured text. Never read all 501 SKILL.md files into context. Always start from the roll-ups and narrow down.
Default flow:
- Orient: read
references/corpus_index_v2.md first (single roll-up; ~28 KB). For claim boundaries and maturity tiers also read references/corpus_qa_report_v2.md (~20 KB).
- Narrow: use
scripts/search_corpus.py or Grep over references/corpus/ to locate candidate slugs. Do not enumerate the tree.
- Inspect:
Read only the 1–5 per-entry SKILL.md files needed. Each is self-contained.
- Compose: cite slugs (the
name in each entry's frontmatter, e.g. wu-2026-nonspherical-coronal-magnetic-field-open-flux) when answering the user.
scripts/search_corpus.py — quick reference
Stdlib-only. Run from anywhere; the script resolves paths relative to itself.
python3 scripts/search_corpus.py --query PFSS --limit 5
python3 scripts/search_corpus.py --query "open flux" --limit 10 --in skill
python3 scripts/search_corpus.py --batches
python3 scripts/search_corpus.py --maturity
python3 scripts/search_corpus.py --show wu-2026-nonspherical-coronal-magnetic-field-open-flux
python3 scripts/search_corpus.py --ready-for experiment --limit 10
python3 scripts/search_corpus.py --query PFSS --ready-for hypothesis
python3 scripts/search_corpus.py --maturity-tier T1 --maturity-tier T2
| Flag | Effect |
|---|
--query STR | case-insensitive, accent-folded literal substring search over manifest fields: slug, title, batch, theme, first_author, year, venue, source_type, quality, executable_status, arxiv, doi. Regex metacharacters are escaped — see note below. |
--in {manifest,skill,both} | where to search (default manifest; skill greps Layer-1 SKILL.md body; both tags each row [manifest] / [skill] / [both]) |
--limit N | cap hits (default 20) |
--batches | list 18 batches with three columns: name, manifest skill count, theme |
--maturity | print T1–T7 tier counts |
--show SLUG | print absolute path(s) of the entry's SKILL.md + metadata.yaml |
--ready-for {experiment,hypothesis,verify,discovery} | workflow-eligibility filter (issue #60). Used standalone to list eligible entries or paired with --query. See Workflow eligibility filter below. |
--maturity-tier T1..T7 | filter to one or more derived maturity tiers (repeatable). Tier is derived from (quality, executable_status); counts match --maturity. |
--version | print the bundle version (matches version: in this file's frontmatter) and exit |
--query is literal substring only — re.escape is applied internally,
so a query like 'open.*flux' matches the literal six-character sequence,
not the regex. For regex or multi-field filters use Grep directly over
references/corpus/.
Workflow eligibility filter (--ready-for, issue #60)
The corpus is overwhelmingly T3/T4 (paper-grounded-pending-full-text or
stub/scaffold). Earlier workflow documentation overpromised by advertising
"hypothesis generation" and "experiment design" as if every entry were
ready for them. --ready-for makes that selection explicit and queryable.
| Intent | Definition | Live count (issue #63 backfill) |
|---|
discovery | every entry — useful for scripted callers that always pass --ready-for. | 501 |
hypothesis | T1/T2 entries, plus T3 entries with a populated Layer 4 (research_generation_affordances_present == true), and not flagged layer2_stub: true. The Layer-4 affordances flag was backfilled by scripts/backfill_layer4_affordances.py on a conservative substantive-content heuristic; T3 entries whose Layer-4 section is empty / No affordances identified yet / TBD are NOT in this bucket. | 146 |
experiment | Strictly T1/T2 and not Layer-2 stub. T1 has a documented local reproduction (1 entry); T2 has method-ready or runnable-pilot quality (22 entries). A T3 entry is NOT experiment-ready under the corpus's own taxonomy because its full-text verification is still pending. | 23 |
verify | T3/T4/T7 entries that still carry a verification TODO (weak_flag_count > 0, DOI starting TODO/TBD, or layer2_stub: true). This is the inverse of experiment-ready: it surfaces what to spend full-text-verification budget on next. | 433 |
hypothesis is a strict superset of experiment once the Layer-4
affordances flag is backfilled — 23 T1/T2 entries plus 123 T3 entries
with a substantive Layer 4 and no Layer-2 stub. If you observe
hypothesis == experiment on a fresh checkout, run
python3 scripts/backfill_layer4_affordances.py --tier T3 --apply to
re-derive the flag from per-entry SKILL.md (issue #63). The backfill is
idempotent.
The 55 entries flagged layer2_stub: true in metadata.yaml (issue #14:
45 in wave500_inner_heliosphere_psp_solo_045 + 10 in
wave500_waves_instabilities_reconnection_045) are intentionally excluded
from experiment and hypothesis even when their quality would
otherwise qualify them; they appear in verify instead.
Do not advertise discovery as a synonym for "every entry is workflow-
ready". It only means every entry can be browsed. Use experiment for
the honest workflow-ready set.
Workflows
1. Answer "what's in the corpus?"
Read references/corpus_index_v2.md (top sections only — framing, four-layer model, batch table, maturity counts). Quote tier counts from §4 of corpus_qa_report_v2.md. Do not enumerate all 501 entries.
2. Find relevant skills by topic
Run search_corpus.py --query <topic> --limit 10. If <10 hits, optionally rerun with --in both to catch matches that live inside SKILL.md bodies but not in the metadata. Present results as a short list of (slug, batch, title, maturity) rows. Read at most the top 3 per-entry SKILL.md files for detail.
3. Generate a hypothesis from cross-skill tensions
Workflow gating: only hypothesis-ready entries qualify.
Run python3 scripts/search_corpus.py --ready-for hypothesis --query <topic>
first; restrict the candidate set to its output. The bucket excludes the
55 Layer-2 stub entries (issue #14) and the wide T4 stub tier; if a
candidate slug does not appear in --ready-for hypothesis output, do not
use it as a hypothesis seed without first reading the paper.
a. Find 2–3 hypothesis-ready skills via search whose Layer-2 contracts overlap (e.g. PFSS + multi-constraint + AI-farside synoptic).
b. Read their Layer-1 (invariant) and Layer-4 (research-generation affordances) sections.
c. Articulate the tension: where do the papers disagree on cause, parameter regime, or composition?
d. Propose a minimal experiment that resolves the tension using the abstract capabilities listed in Layer-2 (do not bind to any specific MCP unless the user asks).
4. Choose candidates for full-text verification
Use python3 scripts/search_corpus.py --ready-for verify to enumerate
the verification-target set (433 entries). Then narrow further by:
quality == paper-grounded-pending-full-text (T3) and the user's downstream task depends on the numerical target,- the entry sits on a
depends_on edge cited by another high-priority skill,
- the slug appears in the v1 research-generation map's tensions T1–T9 or gaps G1–G6 (see
corpus_index_v2.md),
- the entry carries
layer2_stub: true (issue #14, 55 entries) — its
Layer-2 protocol is a placeholder and reading the paper is the only way
to authorize using it for experiment design.
Avoid spending verification budget on T5 (agent-runtime / design-precedent) entries unless the user is doing runtime evolution work. The verify bucket already excludes T1 (reproduced) and T6 (link-only); restrict tier further with --maturity-tier T3 --maturity-tier T4 if needed.
5. Convert a selected corpus entry into a runtime-specific experiment plan
Workflow gating: only experiment-ready entries qualify. Run
python3 scripts/search_corpus.py --show <slug> and confirm the entry is
in the output of --ready-for experiment (23 entries total). If the slug
is not experiment-ready, refuse the request and surface the gap to the
user — they should either (i) pick a different entry, (ii) author the
missing Layer-2 first, or (iii) run --ready-for verify to find the
verification-target subset and read the paper before designing anything.
a. Read the entry's SKILL.md (whichever of the up-to-four layers are populated — check the layers: frontmatter block when present) and metadata.yaml.
b. Map each abstract Layer-2 capability to a concrete adapter the user actually has (their MCPs, scripts, datasets). When the capability is SPICE-shaped (ephemeris, orbit geometry, frame transform), the companion MCP xhelio-spice is the recommended Layer-3 binding if the consumer has it installed. When the capability is CDAWeb-shaped (FIELDS / SWEAP / IS☉IS / SWA / MAG / EPD time-series fetch), xhelio-cdaweb is the recommended binding if installed. Verify availability before issuing tool calls; if neither MCP is configured, surface the binding gap as a prerequisite — do not invent a fallback.
c. Reproduce the entry's Layer-1 Validation target verbatim; keep tolerance numbers as the paper / reproduction stated them.
d. Preserve the entry's Claim boundary (in-scope / out-of-scope). Never widen scope when porting to a runtime.
Claim boundaries (load-bearing — do not relax)
Safe to assert:
- The bundle contains exactly 501 paper-skill directories across 18 batches with cross-matched filesystem + manifest counts (see
corpus_qa_report_v2.md §1).
- Slugs are globally unique across batches (
totals.duplicate_slugs == {} in references/corpus_manifest_v2.json; the top-level duplicate_slugs key is null).
- The corpus is authored under the harness-agnostic four-layer model as an authoring spec — every entry has Layer 1 (scientific invariant); Layers 2/3/4 are populated as the entry matures (stub → method-ready → reproduced). For entries that ship an explicit
layers: boolean frontmatter block (225 / 501 entries — see references/corpus_qa_report_v2.md §9), the booleans are authoritative: false means that layer is intentionally not yet populated and the entry must not be cited as if it were.
- Exactly one entry (
wu-2026-nonspherical-coronal-magnetic-field-open-flux, in batch_pfss_source_mapping) has a documented local numerical reproduction (open flux 9.09 vs paper 9.19 G·R²_sun, 1.1 % error, GONG CR 2282, R_init = 2.5).
Unsafe to assert (do NOT claim):
- That any other entry is full-text verified. Most are
paper-grounded-pending-full-text, stub, scaffold, pilot, or positioning-skill-not-executable-science.
- That any Layer-3 example MCP (sunkit-magex, sw-scanner, kglobal, ENLIL, EUHFORIA, MAS, Surya foundation-model loader, pyspedas/HAPI/CDAWeb loaders) is bound and runnable on the consumer's harness. The corpus has two first-class companion MCPs (xhelio-spice for SPICE/ephemeris/orbit geometry and xhelio-cdaweb for CDAWeb data access — see Companion MCP adapters above) but both are external repositories that the consumer must install; neither is bundled in this skill.
- That
executable_status values like pipeline-specified-not-yet-runnable, contract-spec-only-not-yet-runnable, scaffold, stub, design-pattern-extractor, manuscript-checklist-only, architecture-template-only, benchmark-design-template, review-routing-not-runnable imply runnable code.
- That DOIs / arXiv IDs / ADS bibcodes marked
TODO_verify_with_full_text are verified.
- That an arXiv ID without a
provenance.id_verifications[].status: arxiv-http-title-match record has been independently checked against arxiv.org. See the arXiv IDs specifically (issue #9 hygiene) subsection above.
- That the research-generation map is an externally validated agenda; it is corpus-internal seed material.
- That
wave500_agent_runtime_eval_design_045 (45 entries) is heliophysics-executable science — those are design-pattern transplants.
Preserve the four-layer separation when summarizing: never collapse Layer-3 examples into Layer-2 contracts, never widen Layer-1 claim boundaries during synthesis. Where an entry's layers: frontmatter block marks a layer false, treat that layer as not authored — do not synthesize content for it.
Maturity tiers (T1–T7) — exact distribution
| Tier | Meaning | Count |
|---|
| T1 | locally reproduced end-to-end | 1 |
| T2 | method-ready / executable pilot | 22 |
| T3 | paper-grounded, full-text pending (largest tier) | 266 |
| T4 | stub or scaffold, paper-anchored | 158 |
| T5 | agent-runtime / design-precedent (not executable science) | 52 |
| T6 | link-only / routing hub | 1 |
| T7 | weak attribution / citation TODO | 1 |
Use these to weight recommendations (--maturity confirms live counts).
Anti-patterns
- Reading every
SKILL.md file before answering. The roll-ups + targeted reads exist for a reason.
- Treating
quality == method-ready as "runnable today." It means the Layer-2 contract is specified; a concrete adapter still needs to be wired.
- Citing a Layer-3 adapter (a Python package, an MCP name) as if it were the paper's claim.
- Inventing a DOI or full author list when the entry shows
TODO_verify_with_full_text. Surface the gap instead.
- Promoting the Wu 2026 reproduction's tolerance to other PFSS entries.
