@galaxyproject/orbit 0.0.0 → 0.9.0

package/extensions/orbit/vendor/skills/changeset-to-galaxy-test-plan/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: changeset-to-galaxy-test-plan
+description: "Carry an existing Galaxy workflow's tests forward as a regression baseline and augment them for a change-set's deltas, emitting a Galaxy test plan."
+---
+
+# changeset-to-galaxy-test-plan
+
+Follow the procedure below and use the artifact/reference sections as the runtime contract.
+
+## When To Use
+
+- Carry an existing Galaxy workflow's tests forward as a regression baseline and augment them for a change-set's deltas, emitting a Galaxy test plan.
+
+## Inputs
+
+- Read artifact `summary-galaxy-workflow`. Schema: summary-galaxy-workflow. Produced by `summarize-galaxy-workflow`. Structured summary of the existing workflow from summarize-galaxy-workflow; its `tests[]` are the regression baseline to carry forward, and its resolved input/output labels are the anchors baseline assertions bind to.
+- Read artifact `galaxy-workflow-changeset`. Produced by `interview-to-galaxy-workflow-changeset`. Reviewed, step-anchored change-set from interview-to-galaxy-workflow-changeset; names which edits change observable behavior, hence which baseline cases to update and which new assertions to add.
+
+## Outputs
+
+- Write artifact `galaxy-test-plan` as `galaxy-test-plan.yml`. Format: `yaml`. Schema: galaxy-workflow-test-plan. Reviewable Galaxy workflow test plan (see galaxy-workflow-test-plan): baseline cases carried forward as test-evidence plus change-set-driven cases/assertions, with job inputs, expected outputs, assertion intent, fixture provenance, label status, unresolved mappings, and omissions.
+
+## Required Tools
+
+- None declared. Procedure should not assume external CLIs are present.
+
+## Load Upfront
+
+- `references/schemas/galaxy-workflow-test-plan.schema.json`: Schema file copied verbatim into the bundle. Output contract: the emitted plan conforms to galaxy-workflow-test-plan. Cast bundles the JSON Schema so the skill carries its output shape; validate with `foundry validate-galaxy-workflow-test-plan`.
+- `references/schemas/summary-galaxy-workflow.schema.json`: Schema file copied verbatim into the bundle. Input contract: read the existing workflow's `tests[]` (the regression baseline) and its resolved input/output labels so baseline assertions bind to real labels.
+
+## Load On Demand
+
+- `references/notes/galaxy-workflow-testability-design.md`: Research note copied verbatim into the bundle. Decide which change-set-exposed outputs and promoted checkpoints make meaningful new assertions, and how much a baseline assertion must loosen when an edit intentionally changes an output. Use when: adding assertions for a newly exposed output or a new step, or reconciling a baseline assertion an edit invalidates.
+- `references/notes/iwc-shortcuts-anti-patterns.md`: Research note copied verbatim into the bundle. Distinguish accepted IWC-style test shortcuts from assertion smells when loosening a baseline assertion or synthesizing a new one. Use when: considering existence-only, size-only, image-dimension, or tolerant output checks, or recording an omission.
+- `references/notes/iwc-test-data-conventions.md`: Research note copied verbatim into the bundle. Record job-input fixtures for change-set-added inputs (remote-URL-first locations, hashes, collection shapes) as fixture provenance, reusing the baseline's existing fixtures unchanged. Use when: a change-set adds a workflow input that needs new test data, or when recording provenance for a new fixture.
+- `references/notes/planemo-asserts-idioms.md`: Research note copied verbatim into the bundle. Pick the assertion family and tolerance for each change-set-driven expected output by output type. Use when: turning a change-set behavioral delta into assertion intent and a tolerance.
+- `references/notes/planemo-workflow-test-architecture.md`: Research note copied verbatim into the bundle. Keep the plan addressable by stable labels and artifacts Planemo can connect back to invocations, jobs, and outputs. Use when: recording the labels and checkpoints the downstream test must address.
+- `references/schemas/tests-format.schema.json`: Schema file copied verbatim into the bundle. Use the Galaxy workflow tests schema as the assertion-family vocabulary when carrying forward or synthesizing assertion intent. Use when: naming an assertion family or compare operator for a carried-forward or change-set-driven expected output.
+
+## Validation
+
+- Validate `galaxy-test-plan.yml` before returning it: run `foundry validate-galaxy-workflow-test-plan galaxy-test-plan.yml` from `@galaxy-foundry/gxwf-foundry`. If the command is not on PATH, run `npx --package @galaxy-foundry/gxwf-foundry foundry validate-galaxy-workflow-test-plan galaxy-test-plan.yml`. This checks artifact `galaxy-test-plan` against the galaxy-workflow-test-plan schema.
+
+## Procedure
+
+Produce a Galaxy workflow test plan for the update pipeline: carry the existing workflow's tests forward as a **regression baseline** and augment them for the change-set's behavioral deltas. The output is a reviewable YAML handoff conforming to galaxy-workflow-test-plan, not a concrete `tests-format` file — implement-galaxy-workflow-test authors the final `*-tests.yml` from it. This skill is the update pipeline's analogue of nextflow-test-to-galaxy-test-plan / freeform-summary-to-galaxy-test-plan: the dedicated test-plan producer every Galaxy-targeting pipeline places before the implement step.
+
+### Translate-and-augment, not synthesize-from-scratch
+
+The starting point is real test evidence — the existing workflow's own `tests[]`, captured in summary-galaxy-workflow. Most of the plan is those cases carried forward, so its **dominant basis is test-evidence**: set `source.kind: galaxy` and `source.derived_from: test-evidence`. `source.derived_from` is the plan's dominant basis, not a "was anything mixed" flag — the carried-forward baseline dominates, so it reads `test-evidence` even though the plan also carries synthesized change-set cases. The mix shows through at the finer grains: baseline cases keep `test_cases[].derived_from: test-evidence` with `evidence: test-evidence` on their assertions, while change-set-driven cases carry `test_cases[].derived_from: intent` (or `mixed` when a carried-forward case gains a change-set-driven assertion) and their assertions carry `evidence: intent` (raise to `test-evidence` only where the change-set pinned a concrete expected value). `mixed` is valid only at the case level, never at `source.derived_from`. Unlike a freeform-synthesized plan, the baseline's workflow-label bindings are `label_status: resolved` — the summary read them off the concrete existing workflow, so they are known, not assumed.
+
+### What the change-set drives
+
+Walk the change-set and touch only the assertions its edits reach:
+
+- **Behavior-changing edit → update the affected baseline case.** A `change-parameter`, `replace-tool`, or `add-step` that alters an existing output's content means the baseline assertion on that output is now wrong. Update it — tighten to the new expected value where the change-set gave one, or loosen it (e.g. presence/format where a content check no longer holds) and record the loosening in `omissions[]` with a rationale. **Never delete a baseline case to make it pass**; a regression that silently drops coverage is the failure mode this pipeline exists to avoid.
+- **New observable behavior → a new assertion or case.** An `expose-output` / `add-output` needs a new `expected_outputs[]` entry asserting the promoted output; a new step whose result is observable needs assertion intent for it; a new `add-input` needs a `job_inputs[]` binding and a fixture. Bind change-set-added labels at `label_status: assumed` (the concrete labels settle downstream once the per-step loop resolves the step) and reconcile them in implement-galaxy-workflow-test.
+- **Internal-only edit → no assertion change.** A `rewire`, `relabel`, or `remove-step` that does not change an observable output changes no assertions; carry the baseline through untouched.
+
+### Scope discipline mirrors the change-set
+
+Change only the assertions the change-set reaches. Do not add assertions for untouched regions beyond what the baseline already covers, and do not tidy or re-tolerance a baseline assertion no edit touched — the update pipeline's contract is that untouched behavior is verified exactly as before. Gratuitous churn in the plan propagates into gratuitous test churn downstream.
+
+### Fixtures
+
+Reuse the baseline's existing fixtures verbatim — they already ship with the workflow and are the regression data. Only a change-set that adds a workflow input needs new test data: record it with iwc-test-data-conventions (remote-URL-first, `storage: unresolved` with provenance when the input names data only by description), and leave resolution to the harness test-data step / find-test-data and implement-galaxy-workflow-test. When an added input's data cannot be settled here, add an `unresolved[]` entry (with `blocking: true` when the new case cannot be authored without it) rather than inventing a location.
+
+Keep the plan addressable by stable labels and artifacts (planemo-workflow-test-architecture) so the downstream test, run, and debug skills can connect assertions back to invocations and outputs.
+
+## Feedback Mode
+
+- Feedback mode is off unless the caller explicitly enables `--feedback` or supplies a feedback-ledger path.
+- When enabled, read `_feedback.md` before doing the work and use its registered `foundry-feedback.ledger.yml` protocol.
+- Preserve harness-owned run and phase state. Append only concrete observations about a canonical Foundry source asset or a related project that this run showed to be at fault; do not put ordinary workflow requirements in this ledger.
+- Before reporting completion, make one explicit pass over the work you just did. Do not ask yourself whether anything was unclear — recall what happened: where you guessed at something the instructions should have settled, needed information this bundle does not carry, hit an instruction that contradicted another or contradicted the artifacts in front of you, used a packaged reference that did not cover your case, or did something the procedure never describes.
+- Append an entry for each such event that clears the protocol's bar. If none do, append nothing and report `no feedback` explicitly. Silence and a clean pass are not the same thing, and nothing downstream can tell them apart unless you say which one it was.
+- Pass the same ledger path to any subagent used for this work, and merge updates serially so one writer cannot overwrite another.
+
+## Runtime Notes
+
+- Do not read Foundry source files at runtime; use only files packaged in this skill bundle and user-supplied artifacts.
+- Preserve declared artifact filenames unless the user or harness supplies explicit paths.
+- Carry unresolved assumptions into the output artifact instead of silently inventing missing source evidence.

package/extensions/orbit/vendor/skills/changeset-to-galaxy-test-plan/_provenance.json

@@ -0,0 +1,166 @@
+{
+  "provenance_schema_version": 4,
+  "cast_target": "claude",
+  "mold": {
+    "name": "changeset-to-galaxy-test-plan",
+    "path": "content/molds/changeset-to-galaxy-test-plan/index.md",
+    "revision": 2,
+    "content_hash": "1a5f10ecf90158c4fdaf292055ca73dcd6dd39e7253fe417b62020c3c4ec8be9",
+    "commit": "63a3f9cf9c97a637fe1628d298e524f35709e289"
+  },
+  "cast_at": "2026-09-13T20:58:26.449Z",
+  "refs": [
+    {
+      "kind": "research",
+      "mode": "verbatim",
+      "ref": "[[galaxy-workflow-testability-design]]",
+      "src": "content/research/galaxy-workflow-testability-design/index.md",
+      "dst": "references/notes/galaxy-workflow-testability-design.md",
+      "used_at": "runtime",
+      "load": "on-demand",
+      "evidence": "corpus-observed",
+      "purpose": "Decide which change-set-exposed outputs and promoted checkpoints make meaningful new assertions, and how much a baseline assertion must loosen when an edit intentionally changes an output.",
+      "trigger": "When adding assertions for a newly exposed output or a new step, or reconciling a baseline assertion an edit invalidates.",
+      "src_hash": "81b01801ec3d14810d570dd2d7815da2bb11e41a562af9182c29fd2974f4b855",
+      "dst_hash": "81b01801ec3d14810d570dd2d7815da2bb11e41a562af9182c29fd2974f4b855",
+      "source": "deterministic"
+    },
+    {
+      "kind": "research",
+      "mode": "verbatim",
+      "ref": "[[iwc-shortcuts-anti-patterns]]",
+      "src": "content/research/iwc-shortcuts-anti-patterns/index.md",
+      "dst": "references/notes/iwc-shortcuts-anti-patterns.md",
+      "used_at": "runtime",
+      "load": "on-demand",
+      "evidence": "corpus-observed",
+      "purpose": "Distinguish accepted IWC-style test shortcuts from assertion smells when loosening a baseline assertion or synthesizing a new one.",
+      "trigger": "When considering existence-only, size-only, image-dimension, or tolerant output checks, or recording an omission.",
+      "src_hash": "14cc27c6a3e01588b06151535afdcb671cadd8e10dc960a248934e9133ebc8ab",
+      "dst_hash": "14cc27c6a3e01588b06151535afdcb671cadd8e10dc960a248934e9133ebc8ab",
+      "source": "deterministic"
+    },
+    {
+      "kind": "research",
+      "mode": "verbatim",
+      "ref": "[[iwc-test-data-conventions]]",
+      "src": "content/research/iwc-test-data-conventions/index.md",
+      "dst": "references/notes/iwc-test-data-conventions.md",
+      "used_at": "runtime",
+      "load": "on-demand",
+      "evidence": "corpus-observed",
+      "purpose": "Record job-input fixtures for change-set-added inputs (remote-URL-first locations, hashes, collection shapes) as fixture provenance, reusing the baseline's existing fixtures unchanged.",
+      "trigger": "When a change-set adds a workflow input that needs new test data, or when recording provenance for a new fixture.",
+      "src_hash": "1921e939703444604440e0768caca6e6b834a73dcfa964f450fa081143e008d3",
+      "dst_hash": "1921e939703444604440e0768caca6e6b834a73dcfa964f450fa081143e008d3",
+      "source": "deterministic"
+    },
+    {
+      "kind": "research",
+      "mode": "verbatim",
+      "ref": "[[planemo-asserts-idioms]]",
+      "src": "content/research/planemo-asserts-idioms/index.md",
+      "dst": "references/notes/planemo-asserts-idioms.md",
+      "used_at": "runtime",
+      "load": "on-demand",
+      "evidence": "corpus-observed",
+      "purpose": "Pick the assertion family and tolerance for each change-set-driven expected output by output type.",
+      "trigger": "When turning a change-set behavioral delta into assertion intent and a tolerance.",
+      "src_hash": "81b8feeccd891642572e587a494d1e4d3a1b369a19d92947626230494fd92beb",
+      "dst_hash": "81b8feeccd891642572e587a494d1e4d3a1b369a19d92947626230494fd92beb",
+      "source": "deterministic"
+    },
+    {
+      "kind": "research",
+      "mode": "verbatim",
+      "ref": "[[planemo-workflow-test-architecture]]",
+      "src": "content/research/planemo-workflow-test-architecture/index.md",
+      "dst": "references/notes/planemo-workflow-test-architecture.md",
+      "used_at": "runtime",
+      "load": "on-demand",
+      "evidence": "corpus-observed",
+      "purpose": "Keep the plan addressable by stable labels and artifacts Planemo can connect back to invocations, jobs, and outputs.",
+      "trigger": "When recording the labels and checkpoints the downstream test must address.",
+      "src_hash": "d6ac347c8361d6c312c64c1197426673e53aa1c5577e1c72f1c80a20ccd1cce3",
+      "dst_hash": "d6ac347c8361d6c312c64c1197426673e53aa1c5577e1c72f1c80a20ccd1cce3",
+      "source": "deterministic"
+    },
+    {
+      "kind": "schema",
+      "mode": "verbatim",
+      "ref": "[[galaxy-workflow-test-plan]]",
+      "src": "package://@galaxy-foundry/gxwf-foundry#galaxyWorkflowTestPlanSchema",
+      "dst": "references/schemas/galaxy-workflow-test-plan.schema.json",
+      "used_at": "runtime",
+      "load": "upfront",
+      "evidence": "hypothesis",
+      "purpose": "Output contract: the emitted plan conforms to [[galaxy-workflow-test-plan]]. Cast bundles the JSON Schema so the skill carries its output shape; validate with `foundry validate-galaxy-workflow-test-plan`.",
+      "verification": "Cast the skill, run on a summary with existing tests plus a change-set, confirm the emitted YAML validates and downstream [[implement-galaxy-workflow-test]] consumes it without re-reading the change-set.",
+      "license": "MIT",
+      "src_hash": "325e9cf1bb5e075fa818dc68868647de95389ca8df8581ee8cf1e2be61196e37",
+      "dst_hash": "325e9cf1bb5e075fa818dc68868647de95389ca8df8581ee8cf1e2be61196e37",
+      "source": "deterministic"
+    },
+    {
+      "kind": "schema",
+      "mode": "verbatim",
+      "ref": "[[summary-galaxy-workflow]]",
+      "src": "package://@galaxy-foundry/gxwf-foundry#summaryGalaxyWorkflowSchema",
+      "dst": "references/schemas/summary-galaxy-workflow.schema.json",
+      "used_at": "runtime",
+      "load": "upfront",
+      "evidence": "cast-validated",
+      "purpose": "Input contract: read the existing workflow's `tests[]` (the regression baseline) and its resolved input/output labels so baseline assertions bind to real labels.",
+      "license": "MIT",
+      "src_hash": "55831dd043243e137cae595badc7f1ecc9a84a44936c0e036c7c3f5d33978bb3",
+      "dst_hash": "55831dd043243e137cae595badc7f1ecc9a84a44936c0e036c7c3f5d33978bb3",
+      "source": "deterministic"
+    },
+    {
+      "kind": "schema",
+      "mode": "verbatim",
+      "ref": "[[tests-format]]",
+      "src": "package://@galaxy-foundry/gxwf-foundry#testsFormatSchema",
+      "dst": "references/schemas/tests-format.schema.json",
+      "used_at": "runtime",
+      "load": "on-demand",
+      "evidence": "corpus-observed",
+      "purpose": "Use the Galaxy workflow tests schema as the assertion-family vocabulary when carrying forward or synthesizing assertion intent.",
+      "trigger": "When naming an assertion family or compare operator for a carried-forward or change-set-driven expected output.",
+      "license": "MIT",
+      "license_file": "LICENSES/galaxy-tool-util-ts.LICENSE",
+      "src_hash": "ff0de5041f4c3de0ab7abe9e7555c5a7120665b077f42661461301b0fb26f372",
+      "dst_hash": "ff0de5041f4c3de0ab7abe9e7555c5a7120665b077f42661461301b0fb26f372",
+      "source": "deterministic",
+      "license_file_hash": "383450c494c01c466bcf22df102540a39ac89da50563fd7be686ba06772f96b3"
+    }
+  ],
+  "artifacts": {
+    "produces": [
+      {
+        "id": "galaxy-test-plan",
+        "kind": "yaml",
+        "default_filename": "galaxy-test-plan.yml",
+        "schema": "[[galaxy-workflow-test-plan]]",
+        "description": "Reviewable Galaxy workflow test plan (see [[galaxy-workflow-test-plan]]): baseline cases carried forward as test-evidence plus change-set-driven cases/assertions, with job inputs, expected outputs, assertion intent, fixture provenance, label status, unresolved mappings, and omissions."
+      }
+    ],
+    "consumes": [
+      {
+        "id": "summary-galaxy-workflow",
+        "description": "Structured summary of the existing workflow from [[summarize-galaxy-workflow]]; its `tests[]` are the regression baseline to carry forward, and its resolved input/output labels are the anchors baseline assertions bind to.",
+        "inherited_schema": "[[summary-galaxy-workflow]]",
+        "producers": [
+          "summarize-galaxy-workflow"
+        ]
+      },
+      {
+        "id": "galaxy-workflow-changeset",
+        "description": "Reviewed, step-anchored change-set from [[interview-to-galaxy-workflow-changeset]]; names which edits change observable behavior, hence which baseline cases to update and which new assertions to add.",
+        "producers": [
+          "interview-to-galaxy-workflow-changeset"
+        ]
+      }
+    ]
+  }
+}

package/extensions/orbit/vendor/skills/changeset-to-galaxy-test-plan/_verify.json

@@ -0,0 +1,29 @@
+{
+  "verify_schema_version": 1,
+  "entries": [
+    {
+      "artifact_id": "summary-galaxy-workflow",
+      "direction": "input",
+      "kind": "json",
+      "default_filename": "summary-galaxy-workflow.json",
+      "schema": "[[summary-galaxy-workflow]]",
+      "validator_bin": "foundry",
+      "args": [
+        "validate-summary-galaxy-workflow",
+        "{artifact_path}"
+      ]
+    },
+    {
+      "artifact_id": "galaxy-test-plan",
+      "direction": "output",
+      "kind": "yaml",
+      "default_filename": "galaxy-test-plan.yml",
+      "schema": "[[galaxy-workflow-test-plan]]",
+      "validator_bin": "foundry",
+      "args": [
+        "validate-galaxy-workflow-test-plan",
+        "{artifact_path}"
+      ]
+    }
+  ]
+}

package/extensions/orbit/vendor/skills/changeset-to-galaxy-test-plan/references/notes/galaxy-workflow-testability-design.md

@@ -0,0 +1,136 @@
+---
+type: research
+tags:
+  - target/galaxy
+status: draft
+created: 2026-05-03
+revised: 2026-05-06
+revision: 2
+related_notes:
+  - "iwc-workflow-testability-survey"
+  - "iwc-test-data-conventions"
+  - "planemo-asserts-idioms"
+  - "iwc-shortcuts-anti-patterns"
+  - "planemo-workflow-test-architecture"
+  - "implement-galaxy-workflow-test"
+  - "gxformat2-schema"
+  - "gxformat2-workflow-inputs"
+  - "galaxy-datatypes-conf"
+summary: "Design guidance for Galaxy workflow inputs, outputs, and checkpoints that make IWC-style workflow tests possible."
+---
+
+# Galaxy workflow testability design
+
+Use this note when authoring or translating a Galaxy workflow **before** the `-tests.yml` file exists. It covers workflow structure choices that make later IWC-style tests meaningful: labels, promoted checkpoints, collection identifiers, and fixture-compatible inputs.
+
+This is not a `content/patterns/` page. It is cross-cutting design guidance for Molds that need testable Galaxy workflows. Assertion syntax lives in planemo-asserts-idioms. Test YAML fixture shapes live in iwc-test-data-conventions. Accepted shortcut vs smell calls live in iwc-shortcuts-anti-patterns. Corpus evidence trail lives in iwc-workflow-testability-survey.
+
+## 1. Treat labels as API
+
+Workflow input and output labels are not cosmetic. Planemo and IWC tests address workflow inputs and outputs by label, and the survey found exact label matches for every asserted output across 114 matched workflow/test pairs. A generated workflow should therefore pick stable, descriptive labels before test authoring starts.
+
+Rules:
+
+- Label every output that may need a test assertion.
+- Treat input/output renames as breaking changes requiring sibling `-tests.yml` updates.
+- Prefer stable domain names over tool-step defaults or positional names.
+- Do not rely on unlabeled or positional outputs for tests.
+
+Evidence:
+
+- Scanpy exposes outputs such as `Initial Anndata General Info`, `UMAP of louvain`, `Ranked genes with Wilcoxon test`, and `Dotplot of top genes on clusters` (`$IWC_FORMAT2/scRNAseq/scanpy-clustering/Preprocessing-and-Clustering-of-single-cell-RNA-seq-data-with-Scanpy.gxwf.yml:105-147`). The sibling test keys assertions by those exact labels (`$IWC/workflows/scRNAseq/scanpy-clustering/Preprocessing-and-Clustering-of-single-cell-RNA-seq-data-with-Scanpy-tests.yml:27-205`).
+- VGP scaffolding uses punctuation-heavy labels such as `Hi-C duplication stats on scaffolds: Raw`, `Hi-C duplication stats on scaffolds: MultiQc`, and `Merged Alignment stats` (`$IWC_FORMAT2/VGP-assembly-v2/Scaffolding-HiC-VGP8/Scaffolding-HiC-VGP8.gxwf.yml:170-196`). The test asserts those exact labels (`$IWC/workflows/VGP-assembly-v2/Scaffolding-HiC-VGP8/Scaffolding-HiC-VGP8-tests.yml:218-245`).
+
+## 2. Promote assertable checkpoints
+
+IWC workflow tests assert workflow-level outputs. Intermediate step results are invisible unless promoted to top-level workflow outputs. When final reports are weakly assertable, expose intermediate checkpoints that carry deterministic content or structure.
+
+Rules:
+
+- Promote intermediate outputs when they are the best deterministic or structural checkpoint.
+- Prefer a checkpoint table/text/HDF5 object that can prove content over a final plot/report that can only prove existence.
+- Accept some output-list clutter when it buys meaningful tests.
+- Do not promote every intermediate by default; expose checkpoints that map to concrete assertion intent.
+
+Evidence:
+
+- Scanpy exposes 21 workflow outputs and the sibling test asserts all 21. These include initial AnnData summaries, intermediate plots, ranked-gene tables, final AnnData, cluster-count tables, and final plots (`$IWC_FORMAT2/scRNAseq/scanpy-clustering/Preprocessing-and-Clustering-of-single-cell-RNA-seq-data-with-Scanpy.gxwf.yml:105-147`; `$IWC/workflows/scRNAseq/scanpy-clustering/Preprocessing-and-Clustering-of-single-cell-RNA-seq-data-with-Scanpy-tests.yml:27-205`).
+- RNA-seq paired-end exposes mapped reads, stranded/unstranded coverage, abundance estimates, expression tables, counts tables, and MultiQC reports (`$IWC_FORMAT2/transcriptomics/rnaseq-pe/rnaseq-pe.gxwf.yml:90-112`). The sibling test asserts sizes for coverage/read outputs and stronger regex/line checks for expression/count outputs (`$IWC/workflows/transcriptomics/rnaseq-pe/rnaseq-pe-tests.yml:48-97`).
+- MGnify complete exposes 83 workflow outputs; 38 are asserted in the sibling test, including MultiQC reports, FASTA collections, taxonomic classifications, OTU tables, and HDF5/JSON outputs (`$IWC_FORMAT2/amplicon/amplicon-mgnify/mgnify-amplicon-pipeline-v5-complete/mgnify-amplicon-pipeline-v5-complete.gxwf.yml:163-329`; `$IWC/workflows/amplicon/amplicon-mgnify/mgnify-amplicon-pipeline-v5-complete/mgnify-amplicon-pipeline-v5-complete-tests.yml:15-120`).
+
+## 3. Stabilize collection output identifiers
+
+Collection tests key assertions by element identifier. If a workflow emits collections with unstable or opaque identifiers, the test cannot target elements cleanly.
+
+Rules:
+
+- Preserve biologically or sample-meaningful identifiers through map-over and collection reshaping.
+- When generating or relabeling collections, make the identifier derivation deterministic and visible in workflow structure.
+- For nested collections, ensure each axis has predictable identifiers.
+- Quote special identifiers in tests when YAML requires it, but do not simplify identifiers merely for YAML convenience.
+
+Evidence:
+
+- 59 of 115 IWC test files use `element_tests:`, with 227 `element_tests:` blocks in the corpus survey.
+- 10x CellPlex tests nested collection outputs by `subsample`, then inner `matrix`, `barcodes`, and `genes` elements (`$IWC/workflows/scRNAseq/fastq-to-matrix-10x/scrna-seq-fastq-to-matrix-10x-cellplex-tests.yml:82-128`). The workflow exposes the corresponding collection outputs (`$IWC_FORMAT2/scRNAseq/fastq-to-matrix-10x/scrna-seq-fastq-to-matrix-10x-cellplex.gxwf.yml:73-91`).
+- HyPhy collection outputs are tested by generated gene identifiers such as `NC_001477.1|capsid_protein_C|95-394_DENV1` (`$IWC/workflows/comparative_genomics/hyphy/hyphy-core-tests.yml:31-71`). The workflow exposes collection outputs for MEME, PRIME, BUSTED, and FEL (`$IWC_FORMAT2/comparative_genomics/hyphy/hyphy-core.gxwf.yml:26-38`).
+
+## 4. Choose checkpoints by assertion strength
+
+Assertion choice is not only a test-file decision. It should feed back into workflow output design. If the only exposed output is a stochastic plot or binary file, the best possible test may be a weak size check. Exposing a sibling table, report, HDF5 structure, or summary line can make the same workflow much more testable.
+
+Rules:
+
+- For image-heavy workflows, expose data or summary outputs behind the plot when possible.
+- For stochastic statistical outputs, expose structural checkpoints and stable summary tokens.
+- For binary outputs, expose a text/table report or stats file when the tool can produce one.
+- Use planemo-asserts-idioms to select the assertion family after choosing the checkpoint.
+
+Evidence:
+
+- Scanpy image outputs are mostly smoke-tested with `has_size`, `has_image_width`, and `has_image_height`, but the same workflow also exposes AnnData HDF5 keys and cluster-count table checks (`$IWC/workflows/scRNAseq/scanpy-clustering/Preprocessing-and-Clustering-of-single-cell-RNA-seq-data-with-Scanpy-tests.yml:33-205`).
+- RNA-seq paired-end pairs coarse size checks for coverage/mapped-read outputs with stronger regex and exact-line checks for expression/count tables (`$IWC/workflows/transcriptomics/rnaseq-pe/rnaseq-pe-tests.yml:48-97`).
+- VGP scaffolding tests combine stable text checks for scaffold/report stats with size checks for map/alignment artifacts (`$IWC/workflows/VGP-assembly-v2/Scaffolding-HiC-VGP8/Scaffolding-HiC-VGP8-tests.yml:173-245`).
+
+## 5. Design inputs with fixtures in mind
+
+Workflow input labels and types constrain the eventual `job:` block. Fixture planning is not only a test-file activity: it should influence whether the workflow exposes a file input, a collection input, a string data-table input, or a typed parameter.
+
+Rules:
+
+- Choose input labels that will be readable as test `job:` keys.
+- Match workflow input collection types to realistic fixture shapes.
+- Decide early whether reference data should be a portable remote file or a CVMFS/data-table string.
+- Keep typed parameters explicit when tests need to set them (`int`, `boolean`, `string`) rather than burying them in step defaults.
+
+Evidence:
+
+- 10x CellPlex job inputs include `fastq PE collection GEX`, `reference genome`, `gtf`, `cellranger_barcodes_3M-february-2018.txt`, `fastq PE collection CMO`, `sample name and CMO sequence collection`, and `Number of expected cells` (`$IWC/workflows/scRNAseq/fastq-to-matrix-10x/scrna-seq-fastq-to-matrix-10x-cellplex-tests.yml:2-75`). The workflow declares matching collection, data, string, boolean, and int inputs (`$IWC_FORMAT2/scRNAseq/fastq-to-matrix-10x/scrna-seq-fastq-to-matrix-10x-cellplex.gxwf.yml:4-72`).
+- HyPhy accepts a `list` collection of unaligned sequences and preserves accession-like fixture identifiers through to output element assertions (`$IWC/workflows/comparative_genomics/hyphy/hyphy-core-tests.yml:7-30`; `$IWC_FORMAT2/comparative_genomics/hyphy/hyphy-core.gxwf.yml:14-25`).
+
+## 6. Know what a gxformat2 output entry contains
+
+Top-level gxformat2 `outputs:` is the public workflow-output surface. It is separate from per-step `out:` declarations and from step post-job actions such as `change_datatype` or `rename`.
+
+Authoring rules:
+
+- Use `label` as the stable public name tests and users will address.
+- Use `outputSource` to point at the producing step output; do not rely on positional output order.
+- Use `doc` for short user-facing context when the label is not self-explanatory.
+- Keep `type` aligned with the exposed value (`data`, `collection`, or scalar vocabulary from gxformat2-workflow-inputs) when the schema needs it.
+- Apply `change_datatype` at the producing step output when Galaxy needs a stronger datatype than the tool reports; choose values from galaxy-datatypes-conf.
+- Use `rename` only for generated dataset names inside Galaxy histories. It is not a substitute for stable workflow-output `label`.
+- Treat `add_tags` and `remove_tags` as metadata helpers, not as the test API. IWC tests key by labels and collection element identifiers, not tags.
+- Avoid `hide` or `delete_intermediate_datasets` on outputs that are promoted as test checkpoints.
+
+Design inference: a workflow-output promotion decision should pick both the public `outputs:` entry and any producer-side post-job action needed to make that output useful. For example, a synthesized BED checkpoint needs a stable output `label` plus a producer-side `change_datatype: bed`; one without the other is incomplete for a testable workflow.
+
+## Cross-references
+
+- iwc-workflow-testability-survey — corpus survey and distribution rationale.
+- iwc-test-data-conventions — job/input YAML shapes, remote fixtures, hashes, collection fixture syntax.
+- planemo-asserts-idioms — assertion-family choice after an output is exposed.
+- iwc-shortcuts-anti-patterns — accepted shortcut vs smell calls for weak assertions and label coupling.
+- planemo-workflow-test-architecture — Planemo execution, output-problem ambiguity, and structured artifacts.
+- gxformat2-schema — structural vocabulary for top-level workflow outputs and step post-job actions.
+- galaxy-datatypes-conf — valid Galaxy datatype extensions for `format` and `change_datatype` choices.