@galaxyproject/orbit 0.0.0 → 0.9.0

package/extensions/orbit/vendor/skills/compare-against-iwc-exemplar/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: compare-against-iwc-exemplar
+description: "Find nearest IWC exemplar(s) and surface a structural diff against the upstream Galaxy design briefs to guide template authoring."
+---
+
+# compare-against-iwc-exemplar
+
+Follow the procedure below and use the artifact/reference sections as the runtime contract.
+
+## When To Use
+
+- Find nearest IWC exemplar(s) and surface a structural diff against the upstream Galaxy design briefs to guide template authoring.
+
+## Inputs
+
+- Read artifact `nextflow-galaxy-interface`. Produced by `nextflow-summary-to-galaxy-interface`. Galaxy interface brief from nextflow-summary-to-galaxy-interface when running the NEXTFLOW → GALAXY pipeline.
+- Read artifact `nextflow-galaxy-data-flow`. Produced by `nextflow-summary-to-galaxy-data-flow`. Galaxy data-flow brief from nextflow-summary-to-galaxy-data-flow when running the NEXTFLOW → GALAXY pipeline.
+- Read artifact `cwl-galaxy-interface`. Produced by `cwl-summary-to-galaxy-interface`. Galaxy interface brief from cwl-summary-to-galaxy-interface when running the CWL → GALAXY pipeline.
+- Read artifact `cwl-galaxy-data-flow`. Produced by `cwl-summary-to-galaxy-data-flow`. Galaxy data-flow brief from cwl-summary-to-galaxy-data-flow when running the CWL → GALAXY pipeline.
+- Read artifact `freeform-galaxy-interface`. Produced by `freeform-summary-to-galaxy-interface`. Galaxy interface brief from freeform-summary-to-galaxy-interface when running the PAPER → GALAXY or INTERVIEW → GALAXY pipelines.
+- Read artifact `freeform-galaxy-data-flow`. Produced by `freeform-summary-to-galaxy-data-flow`. Galaxy data-flow brief from freeform-summary-to-galaxy-data-flow when running the PAPER → GALAXY or INTERVIEW → GALAXY pipelines.
+- Read artifact `open-requirements-ledger`. Produced by `advance-galaxy-draft-step`, `apply-galaxy-workflow-changeset`, `compare-against-iwc-exemplar`, `cwl-summary-to-galaxy-data-flow`, `cwl-summary-to-galaxy-interface`, `cwl-summary-to-galaxy-template`, `freeform-summary-to-galaxy-data-flow`, `freeform-summary-to-galaxy-interface`, `freeform-summary-to-galaxy-template`, `implement-galaxy-tool-step`, `interview-to-galaxy-workflow-changeset`, `mature-galaxy-workflow-for-iwc`, `nextflow-summary-to-galaxy-data-flow`, `nextflow-summary-to-galaxy-interface`, `nextflow-summary-to-galaxy-reference-data`, `nextflow-summary-to-galaxy-template`, `repair-galaxy-draft-topology`. Carried obligations ledger open-requirements-ledger: the run's open, resolved, and surrendered entries with their provenance. Absent on the first Mold of a run; start an empty one.
+
+## Outputs
+
+- Write artifact `iwc-comparison-notes` as `iwc-comparison-notes.md`. Format: `markdown`. Structural diff against the nearest IWC exemplar(s); guidance for the downstream *-summary-to-galaxy-template Mold before per-step authoring. Carries an inline, bounded gxformat2 excerpt of the nearest exemplar's relevant subgraph under a labeled section, cross-referencing the iwc-exemplar-gxformat2 sibling file.
+- Write artifact `iwc-exemplar-gxformat2` as `iwc-exemplar.gxwf.yml`. Format: `yaml`. Cleaned gxformat2 conversion (via convert --to format2 --compact) of the nearest IWC exemplar's relevant subgraph — the concrete idiom the downstream template draft pattern-matches against. Bounded to the relevant subgraph, not the whole workflow. Absent when no nearest exemplar is found.
+- Write artifact `open-requirements-ledger` as `open-requirements.ledger.yml`. Format: `yaml`. Carried obligations ledger re-emitted by this step: entries it appended or closed updated, every other entry passed through with its provenance intact.
+
+## Required Tools
+
+- **`gxwf`** (gxwf). `npm install -g '@galaxy-tool-util/cli@^1.8.1'`.
+  Ephemeral run: `npx --yes --package @galaxy-tool-util/cli@1.8.1 gxwf`.
+  Check: `gxwf --help | grep -q draft-validate`.
+  Docs: https://github.com/jmchilton/galaxy-tool-util-ts/tree/main/packages/cli
+
+## Load Upfront
+
+- `references/notes/open-requirements-ledger.md`: Research note copied verbatim into the bundle. Close the open entries a corpus exemplar answers — a collection idiom, a label convention, a structural shape the corpus already settles — and append the ones no exemplar covers, so a structural divergence with no corpus precedent reaches the template tier as a recorded obligation.
+
+## Load On Demand
+
+- `references/cli/convert.json`: CLI command reference packaged as a sidecar. Normalize fetched IWC workflows into a consistent representation for structural comparison, and surface the nearest exemplar forward as a cleaned gxformat2 view (sibling file plus inline excerpt) for the downstream template Mold. Use when: after fetching a candidate IWC workflow file and before structural comparison; and again on the nearest exemplar after ranking to emit the iwc-exemplar-gxformat2 view.
+- `references/notes/galaxy-data-flow-draft-contract.md`: Research note copied verbatim into the bundle. Compare against the design briefs' abstract intent without turning exemplar comparison into tool resolution. Use when: deciding whether to compare abstract data-flow shape, interface structure, or speculative implementation details.
+- `references/notes/iwc-shortcuts-anti-patterns.md`: Research note copied verbatim into the bundle. Flag proposed shortcuts that are accepted in IWC versus shortcuts that should be treated as smells. Use when: the design briefs propose tests, assertions, labels, or expected-output comparisons.
+- `references/notes/iwc-test-data-conventions.md`: Research note copied verbatim into the bundle. Compare proposed test-data placement and fixture shapes against IWC conventions. Use when: the design briefs hint at workflow tests or input fixture organization.
+
+## Validation
+
+- None declared.
+
+## Procedure
+
+Find the nearest IWC exemplar workflow(s) for the upstream Galaxy design briefs and emit a structural diff that guides the downstream `*-summary-to-galaxy-template` skill before per-step authoring effort is spent.
+
+This skill is the corpus-first check in Galaxy-targeting pipelines. It runs after the source-specific interface and data-flow briefs and before the gxformat2 template skill. Discovery, ranking, and comparison are one action — there is no separate retrieval skill.
+
+### Procedure
+
+- Clone or pull and merge the IWC corpus (`https://github.com/galaxyproject/iwc`) to `~/.foundry/iwc`.
+- Normalize candidate workflows with convert as needed for structural comparison.
+- Find the closest workflow and rank it.
+- Surface the nearest exemplar forward (skip when the result is "no nearest exemplar"): see *Nearest exemplar (gxformat2) view*.
+
+### Feature Hierarchy
+
+1. Domain or analysis intent.
+2. Input collection topology.
+3. Primary tool families.
+4. DAG motifs and structural recipes.
+5. Output types and report shape.
+6. Test style and fixture topology.
+
+Domain comes first so a structurally similar workflow in the wrong science area does not become a misleading exemplar. Topology comes second because collection shape is one of the most important Galaxy-specific design decisions. Test style is useful after a workflow match, but should not drive initial retrieval. Briefs with no domain signal should not produce a high-confidence exemplar even if they share generic tools.
+
+### Confidence Levels
+
+| Level | Meaning |
+|---|---|
+| High | Same domain/subdomain, same input topology, same primary tool families, same major DAG motifs, and matching test fixture shape. |
+| Medium | Same domain and topology, but partial tool-family or output match. Useful exemplar, not canonical. |
+| Low | Cross-domain structural match only. Useful for a pattern comparison, not a nearest domain exemplar. |
+| No nearest exemplar | Candidate lacks domain or topology alignment, or only shares generic tools such as MultiQC. |
+
+### Routing findings forward
+
+Each finding should name the authoring surface most likely to own the fix:
+
+- Template/data-flow issue: missing node, wrong collection shape, wrong branch, placeholder too vague — surfaced for the downstream `*-summary-to-galaxy-template` skill to apply.
+- Pattern issue: recurring Galaxy idiom should become or update a pattern page.
+- Tool-step issue: exact wrapper or parameterization will be handled later in the per-step loop.
+- Test issue: defer to `*-test-to-galaxy-test-plan` or `implement-galaxy-workflow-test`.
+
+Do not block downstream authoring on low-confidence exemplar mismatches. Report them as review guidance for the template skill and the user.
+
+### Nearest exemplar (gxformat2) view
+
+The schema tells the template skill what is *legal* gxformat2; it does not show *idiom*. A real, domain-adjacent gxformat2 workflow is high-value signal for constructing the draft — input/collection shapes, map-over wiring, output promotion, post-job actions. Agents have seen far more legacy `.ga` JSON than gxformat2 YAML in training, so surface the converted view rather than leaving it as prose.
+
+Once the nearest exemplar is chosen (High or Medium confidence):
+
+- Convert it with convert (`--to format2 --compact`).
+- Write the cleaned gxformat2 of the **relevant subgraph** to the `iwc-exemplar.gxwf.yml` sibling artifact — the slice that matches the briefs' structure, not the whole workflow.
+- Inline a bounded excerpt (~10–40 lines) of that subgraph under a labeled section in `iwc-comparison-notes.md`, and cite the abstract IWC workflow ID (e.g. `transcriptomics/rnaseq-pe/rnaseq-pe`) plus the step labels it covers. Cross-reference the sibling file for the fuller view.
+
+Keep it size-bounded — a whole large workflow is noise; the relevant subgraph is the signal. When the result is "no nearest exemplar," emit neither the sibling file nor the excerpt. A Low-confidence cross-domain match may surface a short excerpt for pattern comparison but should be labeled as such, not as a domain exemplar.
+
+### Non-goals
+
+- **No tool discovery.** Do not replace discover-shed-tool.
+- **No automatic rewrite.** This skill emits structural diff guidance; the harness or user decides which changes to apply.
+- **No forced nearest.** A no-match result is valid when IWC lacks a close exemplar.
+
+## 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/compare-against-iwc-exemplar/_provenance.json

@@ -0,0 +1,198 @@
+{
+  "provenance_schema_version": 4,
+  "cast_target": "claude",
+  "mold": {
+    "name": "compare-against-iwc-exemplar",
+    "path": "content/molds/compare-against-iwc-exemplar/index.md",
+    "revision": 10,
+    "content_hash": "5b198e9b87cf554cb01aceaa14a5aaa3ab24c6a35afc35dab7d09ce154cc3a77",
+    "commit": "63a3f9cf9c97a637fe1628d298e524f35709e289"
+  },
+  "cast_at": "2026-09-13T20:58:26.504Z",
+  "cast_date": "2026-05-07",
+  "cast_revision": 3,
+  "cast_history": [
+    {
+      "rev": 1,
+      "date": "2026-05-06",
+      "note": "cast requested nextflow-to-galaxy chain"
+    },
+    {
+      "rev": 2,
+      "date": "2026-05-06",
+      "note": "deterministic skill render"
+    },
+    {
+      "rev": 3,
+      "date": "2026-05-07",
+      "note": "runtime-facing deterministic skill render"
+    }
+  ],
+  "refs": [
+    {
+      "kind": "cli-command",
+      "mode": "sidecar",
+      "ref": "[[convert]]",
+      "src": "content/cli/gxwf/convert.md",
+      "dst": "references/cli/convert.json",
+      "used_at": "runtime",
+      "load": "on-demand",
+      "evidence": "corpus-observed",
+      "purpose": "Normalize fetched IWC workflows into a consistent representation for structural comparison, and surface the nearest exemplar forward as a cleaned gxformat2 view (sibling file plus inline excerpt) for the downstream template Mold.",
+      "trigger": "After fetching a candidate IWC workflow file and before structural comparison; and again on the nearest exemplar after ranking to emit the iwc-exemplar-gxformat2 view.",
+      "src_hash": "1bb19d20b4a39b1708d8f5346a0294616cdb9df83ba5255c4a90d97030d13b83",
+      "dst_hash": "1cdf49f10f77039af6efc5b82fe79720bb18e50d1f57d653670697f7262c7640",
+      "source": "deterministic"
+    },
+    {
+      "kind": "research",
+      "mode": "verbatim",
+      "ref": "[[galaxy-data-flow-draft-contract]]",
+      "src": "content/research/galaxy-data-flow-draft-contract/index.md",
+      "dst": "references/notes/galaxy-data-flow-draft-contract.md",
+      "used_at": "runtime",
+      "load": "on-demand",
+      "evidence": "hypothesis",
+      "purpose": "Compare against the design briefs' abstract intent without turning exemplar comparison into tool resolution.",
+      "trigger": "When deciding whether to compare abstract data-flow shape, interface structure, or speculative implementation details.",
+      "verification": "Promote after exemplar comparison flags structural issues without resolving concrete tool metadata.",
+      "src_hash": "f8f75f5a4ff750bff5f682847466492dd8a9910b95b5078373567f84ce16fb54",
+      "dst_hash": "f8f75f5a4ff750bff5f682847466492dd8a9910b95b5078373567f84ce16fb54",
+      "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": "Flag proposed shortcuts that are accepted in IWC versus shortcuts that should be treated as smells.",
+      "trigger": "When the design briefs propose tests, assertions, labels, or expected-output comparisons.",
+      "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": "Compare proposed test-data placement and fixture shapes against IWC conventions.",
+      "trigger": "When the design briefs hint at workflow tests or input fixture organization.",
+      "src_hash": "1921e939703444604440e0768caca6e6b834a73dcfa964f450fa081143e008d3",
+      "dst_hash": "1921e939703444604440e0768caca6e6b834a73dcfa964f450fa081143e008d3",
+      "source": "deterministic"
+    },
+    {
+      "kind": "research",
+      "mode": "verbatim",
+      "ref": "[[open-requirements-ledger]]",
+      "src": "content/research/open-requirements-ledger/index.md",
+      "dst": "references/notes/open-requirements-ledger.md",
+      "used_at": "runtime",
+      "load": "upfront",
+      "evidence": "hypothesis",
+      "purpose": "Close the open entries a corpus exemplar answers — a collection idiom, a label convention, a structural shape the corpus already settles — and append the ones no exemplar covers, so a structural divergence with no corpus precedent reaches the template tier as a recorded obligation.",
+      "verification": "Promote after a worked run shows entries this Mold appends or resolves are consumed downstream without re-derivation.",
+      "src_hash": "e1d5e3a4d6d650af5b2efc4703fe6f79bb4d0cc12e6cd14e841c5b91df122ea0",
+      "dst_hash": "e1d5e3a4d6d650af5b2efc4703fe6f79bb4d0cc12e6cd14e841c5b91df122ea0",
+      "source": "deterministic"
+    }
+  ],
+  "artifacts": {
+    "produces": [
+      {
+        "id": "iwc-comparison-notes",
+        "kind": "markdown",
+        "default_filename": "iwc-comparison-notes.md",
+        "description": "Structural diff against the nearest IWC exemplar(s); guidance for the downstream *-summary-to-galaxy-template Mold before per-step authoring. Carries an inline, bounded gxformat2 excerpt of the nearest exemplar's relevant subgraph under a labeled section, cross-referencing the iwc-exemplar-gxformat2 sibling file."
+      },
+      {
+        "id": "iwc-exemplar-gxformat2",
+        "kind": "yaml",
+        "default_filename": "iwc-exemplar.gxwf.yml",
+        "description": "Cleaned gxformat2 conversion (via [[convert]] --to format2 --compact) of the nearest IWC exemplar's relevant subgraph — the concrete idiom the downstream template draft pattern-matches against. Bounded to the relevant subgraph, not the whole workflow. Absent when no nearest exemplar is found."
+      },
+      {
+        "id": "open-requirements-ledger",
+        "kind": "yaml",
+        "default_filename": "open-requirements.ledger.yml",
+        "description": "Carried obligations ledger re-emitted by this step: entries it appended or closed updated, every other entry passed through with its provenance intact."
+      }
+    ],
+    "consumes": [
+      {
+        "id": "nextflow-galaxy-interface",
+        "description": "Galaxy interface brief from [[nextflow-summary-to-galaxy-interface]] when running the NEXTFLOW → GALAXY pipeline.",
+        "producers": [
+          "nextflow-summary-to-galaxy-interface"
+        ]
+      },
+      {
+        "id": "nextflow-galaxy-data-flow",
+        "description": "Galaxy data-flow brief from [[nextflow-summary-to-galaxy-data-flow]] when running the NEXTFLOW → GALAXY pipeline.",
+        "producers": [
+          "nextflow-summary-to-galaxy-data-flow"
+        ]
+      },
+      {
+        "id": "cwl-galaxy-interface",
+        "description": "Galaxy interface brief from [[cwl-summary-to-galaxy-interface]] when running the CWL → GALAXY pipeline.",
+        "producers": [
+          "cwl-summary-to-galaxy-interface"
+        ]
+      },
+      {
+        "id": "cwl-galaxy-data-flow",
+        "description": "Galaxy data-flow brief from [[cwl-summary-to-galaxy-data-flow]] when running the CWL → GALAXY pipeline.",
+        "producers": [
+          "cwl-summary-to-galaxy-data-flow"
+        ]
+      },
+      {
+        "id": "freeform-galaxy-interface",
+        "description": "Galaxy interface brief from [[freeform-summary-to-galaxy-interface]] when running the PAPER → GALAXY or INTERVIEW → GALAXY pipelines.",
+        "producers": [
+          "freeform-summary-to-galaxy-interface"
+        ]
+      },
+      {
+        "id": "freeform-galaxy-data-flow",
+        "description": "Galaxy data-flow brief from [[freeform-summary-to-galaxy-data-flow]] when running the PAPER → GALAXY or INTERVIEW → GALAXY pipelines.",
+        "producers": [
+          "freeform-summary-to-galaxy-data-flow"
+        ]
+      },
+      {
+        "id": "open-requirements-ledger",
+        "description": "Carried obligations ledger [[open-requirements-ledger]]: the run's open, resolved, and surrendered entries with their provenance. Absent on the first Mold of a run; start an empty one.",
+        "producers": [
+          "advance-galaxy-draft-step",
+          "apply-galaxy-workflow-changeset",
+          "compare-against-iwc-exemplar",
+          "cwl-summary-to-galaxy-data-flow",
+          "cwl-summary-to-galaxy-interface",
+          "cwl-summary-to-galaxy-template",
+          "freeform-summary-to-galaxy-data-flow",
+          "freeform-summary-to-galaxy-interface",
+          "freeform-summary-to-galaxy-template",
+          "implement-galaxy-tool-step",
+          "interview-to-galaxy-workflow-changeset",
+          "mature-galaxy-workflow-for-iwc",
+          "nextflow-summary-to-galaxy-data-flow",
+          "nextflow-summary-to-galaxy-interface",
+          "nextflow-summary-to-galaxy-reference-data",
+          "nextflow-summary-to-galaxy-template",
+          "repair-galaxy-draft-topology"
+        ]
+      }
+    ]
+  }
+}

package/extensions/orbit/vendor/skills/compare-against-iwc-exemplar/_required_tools.json

@@ -0,0 +1,16 @@
+[
+  {
+    "tool": "gxwf",
+    "origin": "npm",
+    "package": "@galaxy-tool-util/cli",
+    "package_version": "^1.8.1",
+    "invoke": "gxwf",
+    "invoke_fallback": "npx --yes --package @galaxy-tool-util/cli@1.8.1 gxwf",
+    "availability_check": "gxwf --help | grep -q draft-validate",
+    "docs_url": "https://github.com/jmchilton/galaxy-tool-util-ts/tree/main/packages/cli",
+    "source": "implied",
+    "implied_by": [
+      "gxwf convert"
+    ]
+  }
+]

package/extensions/orbit/vendor/skills/compare-against-iwc-exemplar/_verify.json

@@ -0,0 +1,4 @@
+{
+  "verify_schema_version": 1,
+  "entries": []
+}

package/extensions/orbit/vendor/skills/compare-against-iwc-exemplar/references/cli/convert.json

@@ -0,0 +1,123 @@
+{
+  "type": "cli-command",
+  "tool": "gxwf",
+  "command": "convert",
+  "summary": "Convert a Galaxy workflow between native (.ga) and format2 (.gxwf.yml) representations.",
+  "source_path": "content/cli/gxwf/convert.md",
+  "source_revision": 2,
+  "package": "@galaxy-tool-util/cli",
+  "description": "Convert between native (.ga) and format2 (.gxwf.yml) formats",
+  "synopsis": "gxwf convert [options] <file>",
+  "args": [
+    {
+      "raw": "file",
+      "name": "file",
+      "required": true,
+      "variadic": false,
+      "description": "Workflow file (.ga, .gxwf.yml)"
+    }
+  ],
+  "options": [
+    {
+      "flags": "--to <format>",
+      "name": "to",
+      "description": "Target format: native or format2 (infers opposite by default)",
+      "takesArgument": true,
+      "argumentPlaceholder": "<format>",
+      "optionalArgument": false,
+      "negatable": false
+    },
+    {
+      "flags": "--output <file>",
+      "name": "output",
+      "description": "Write result to file (default: stdout)",
+      "takesArgument": true,
+      "argumentPlaceholder": "<file>",
+      "optionalArgument": false,
+      "negatable": false
+    },
+    {
+      "flags": "--compact",
+      "name": "compact",
+      "description": "Omit position info in format2 output",
+      "takesArgument": false,
+      "optionalArgument": false,
+      "negatable": false
+    },
+    {
+      "flags": "--json",
+      "name": "json",
+      "description": "Force JSON output",
+      "takesArgument": false,
+      "optionalArgument": false,
+      "negatable": false
+    },
+    {
+      "flags": "--yaml",
+      "name": "yaml",
+      "description": "Force YAML output",
+      "takesArgument": false,
+      "optionalArgument": false,
+      "negatable": false
+    },
+    {
+      "flags": "--format <fmt>",
+      "name": "format",
+      "description": "Force source format (auto-detected by default)",
+      "takesArgument": true,
+      "argumentPlaceholder": "<fmt>",
+      "optionalArgument": false,
+      "negatable": false
+    },
+    {
+      "flags": "--stateful",
+      "name": "stateful",
+      "description": "Use cached tool definitions for schema-aware state re-encoding",
+      "takesArgument": false,
+      "optionalArgument": false,
+      "negatable": false
+    },
+    {
+      "flags": "--cache-dir <dir>",
+      "name": "cacheDir",
+      "description": "Tool cache directory (for --stateful)",
+      "takesArgument": true,
+      "argumentPlaceholder": "<dir>",
+      "optionalArgument": false,
+      "negatable": false
+    },
+    {
+      "flags": "--strict",
+      "name": "strict",
+      "description": "Shorthand for --strict-structure --strict-encoding --strict-state",
+      "takesArgument": false,
+      "optionalArgument": false,
+      "negatable": false
+    },
+    {
+      "flags": "--strict-structure",
+      "name": "strictStructure",
+      "description": "Reject unknown keys at envelope/step level",
+      "takesArgument": false,
+      "optionalArgument": false,
+      "negatable": false
+    },
+    {
+      "flags": "--strict-encoding",
+      "name": "strictEncoding",
+      "description": "Reject JSON-string tool_state and format2 field misuse",
+      "takesArgument": false,
+      "optionalArgument": false,
+      "negatable": false
+    },
+    {
+      "flags": "--strict-state",
+      "name": "strictState",
+      "description": "Require every tool step to validate; no skips allowed",
+      "takesArgument": false,
+      "optionalArgument": false,
+      "negatable": false
+    }
+  ],
+  "body": "# `gxwf convert`\n\nConvert a Galaxy workflow between the native `.ga` JSON and the `.gxwf.yml` format2 representation. Use this to normalize fetched IWC workflows into a consistent comparison representation.\n\n## Output\n\nDefault output is the converted workflow on stdout. With `--output`, the result is written to a file. JSON output is selected with `--json` (or `--to native`); YAML output is selected with `--yaml` (or `--to format2`).\n\n## Examples\n\n```bash\ngxwf convert workflow.ga --to format2 --output workflow.gxwf.yml\ngxwf convert workflow.ga --to format2 --compact\ngxwf convert workflow.gxwf.yml --to native --output workflow.ga\n```\n\n## Gotchas\n\n- Default output is stdout; pipe or pass `--output` when persisting.\n- `--compact` drops node position metadata; useful for structural diffs and skeleton generation.\n- `--stateful` requires a populated tool cache (see `galaxy-tool-cache`); without it, tool-state stays as fetched."
+}

package/extensions/orbit/vendor/skills/compare-against-iwc-exemplar/references/notes/galaxy-data-flow-draft-contract.md

@@ -0,0 +1,129 @@
+---
+type: research
+title: "Galaxy data-flow draft contract"
+tags:
+  - target/galaxy
+status: draft
+created: 2026-05-02
+revised: 2026-05-03
+revision: 2
+related_notes:
+  - "nextflow-to-galaxy-channel-shape-mapping"
+  - "nextflow-operators-to-galaxy-collection-recipes"
+  - "galaxy-workflow-draft"
+related_molds:
+  - "nextflow-summary-to-galaxy-data-flow"
+  - "cwl-summary-to-galaxy-data-flow"
+  - "freeform-summary-to-galaxy-data-flow"
+  - "nextflow-summary-to-galaxy-template"
+  - "cwl-summary-to-galaxy-template"
+  - "freeform-summary-to-galaxy-template"
+  - "compare-against-iwc-exemplar"
+  - "advance-galaxy-draft-step"
+sources:
+  - "https://github.com/galaxyproject/foundry/issues/54"
+summary: "Defines the proposed boundary between Galaxy data-flow drafts, gxformat2 templates, and concrete step implementation."
+---
+
+# Galaxy Data-Flow Draft Contract
+
+This is an architectural contract, not a schema. Evidence is strongest for Mold and Pipeline boundaries. Proposed fields are speculative until exercised by two or three worked translations.
+
+## Boundary
+
+The data-flow draft owns a target-shaped abstract DAG for Galaxy. It should not be valid `gxformat2` and should not resolve exact Tool Shed tools.
+
+Data-flow draft owns:
+
+- Galaxy-facing workflow inputs and outputs.
+- Abstract nodes, edges, branches, collection mapping, collection reduction, and placeholder transformations.
+- Input/output shape decisions such as `File`, `list`, `paired`, `list:paired`, or `list:list`.
+- Conceptual Galaxy idioms: map-over, reduction, Apply Rules, collection cleanup, identifier synchronization, tabular bridge, fan-in / combine (concatenate, merge, or union N sources into one — a distinct node, not a side-effect of a reshape).
+- Abstract unresolved tool needs with input and output shapes.
+- Confidence and rationale on inferred nodes, edges, transforms, and tool needs.
+
+The Galaxy template owns:
+
+- A `gxformat2` skeleton.
+- Ordered steps, labels, workflow inputs, workflow outputs, and the producer→consumer connection graph.
+- Per-step wrapper resolution to the tier its evidence supports — **evidence-gated, not source-gated** (tiers defined in galaxy-workflow-draft-format): a fully **Resolved** step (concrete `tool_id`, changeset, `state`) when wrapper and parameters are pinned jointly; **Identity-pinned** (`tool_id` only, `_plan_state` kept) when the wrapper is named but not its settings; **Deferred** (`tool_id: TODO`, full `_plan_*`) otherwise.
+- Placeholder collection-operation or Apply Rules steps only when the data-flow draft says they are necessary.
+- `_plan_*` handoff units (intent, evidence, constraints) for every step left short of Resolved.
+
+Concrete step implementation owns:
+
+- For every step the template left short of **Resolved**: the changeset (`tool_version`, `tool_shed_repository` owner/repository metadata), bound `state` parameters, and `input_connections` — resolving any `tool_id: TODO` and confirming or correcting any `tool_id` the template pinned. Steps the template already Resolved pass through — confirm, do not re-derive.
+- Concrete built-in collection-operation steps and parameters.
+- Validation with `gxwf` and repair after schema/lint failures.
+
+## Proposed Body-Level Contract
+
+Do not add these as frontmatter fields yet.
+
+| Concept | Status | Notes |
+|---|---|---|
+| `source_summary_ref` | Speculative | Reference to the source summary consumed by the Mold. |
+| `workflow_inputs` | Speculative | Abstract Galaxy-facing inputs and collection types. |
+| `workflow_outputs` | Speculative | Intended outputs and source-summary provenance. |
+| `nodes` | Speculative | Abstract operations, not concrete Galaxy tools. |
+| `edges` | Speculative | Data dependencies, shape before/after, and source evidence. |
+| `galaxy_idioms` | Speculative | Map-over, reduction, Apply Rules, collection filter, tabular bridge, etc. |
+| `unresolved_tool_needs` | Speculative | Per abstract step needs for `discover-shed-tool` or `author-galaxy-tool-wrapper`. |
+| `placeholder_transformations` | Speculative | Shape/text/table transforms needed for Galaxy semantics but not concretely implemented. |
+| `confidence` | Speculative | Prefer `high`, `medium`, `low` plus rationale. |
+| `handoff_notes` | Speculative | Instructions to template, exemplar comparison, and per-step Molds. |
+| `open_questions` | Speculative | Semantic/tooling issues carried forward. |
+
+## Handoff Examples
+
+Unresolved tool need:
+
+- nextflow-summary-to-galaxy-data-flow emits an abstract node such as `trim FASTQ reads`, input `list:paired fastq`, output `list:paired fastq`, tool need `read trimming`, confidence `medium`.
+- nextflow-summary-to-galaxy-template creates a placeholder step with TODOs and collection-shaped connections.
+- The harness routes through tool discovery or wrapper authoring.
+- implement-galaxy-tool-step fills exact Galaxy tool metadata, parameters, and connections.
+
+Collection cleanup after fan-out:
+
+- Data-flow records a conceptual cleanup transform after a mapped step.
+- Template materializes a placeholder collection-operation step.
+- Implementation chooses exact built-in tool and parameters.
+
+Identifier-derived reshaping:
+
+- Data-flow records desired input shape, output shape, and identifier transformation.
+- Template emits an Apply Rules placeholder only if needed.
+- Implementation fills concrete rule JSON after exemplar comparison confirms the shape.
+
+IWC exemplar comparison:
+
+- Data-flow and template should hand compare-against-iwc-exemplar the abstract topology, placeholder transformations, unresolved tool needs, and confidence notes.
+- Exemplar comparison should flag structural divergence, not resolve tools.
+
+## Confidence Guidance
+
+- Attach confidence to the smallest useful unit: node, edge, transformation, or tool need.
+- Use qualitative `high`, `medium`, `low` until examples justify a richer schema.
+- Require rationale for low confidence.
+- Do not reuse source-summary `warnings[]` as data-flow confidence.
+- Keep evidence quality distinct from translation confidence. A claim can be corpus-observed but still low-confidence for a specific workflow.
+
+## Risks
+
+If the data-flow draft is too broad, it duplicates the template Mold, makes premature tool decisions, and leaks harness routing into Mold output.
+
+If it is too narrow, the template Mold receives source-summary details without Galaxy-shaped semantics, exemplar comparison has only a surface skeleton to diff, and tool discovery loses input/output shape context.
+
+## Evidence
+
+- nextflow-to-galaxy-channel-shape-mapping and nextflow-operators-to-galaxy-collection-recipes show why a Galaxy-shaped abstraction is needed between source summary and `gxformat2` template.
+- `content/pipelines/nextflow-to-galaxy.md` places data-flow before template, exemplar comparison, and per-step implementation.
+- `content/molds/summarize-nextflow/index.md` says source summarization should not produce Galaxy data flow.
+- `content/molds/implement-galaxy-tool-step/index.md` owns concrete step implementation.
+
+## TODOs
+
+- Decide whether to author `galaxy-data-flow-draft.schema.json` now or wait for worked examples.
+- Decide whether confidence should be a single enum or per-axis vector.
+- Decide how much ordering guidance belongs in data-flow versus template.
+- Decide whether built-in collection operations should be abstract placeholders or concrete template steps.