@galaxyproject/orbit 0.0.0 → 0.9.0

package/extensions/orbit/vendor/skills/apply-galaxy-workflow-changeset/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: apply-galaxy-workflow-changeset
+description: "Apply a reviewed change-set to a concrete Galaxy workflow: untouched regions preserved, tool-introducing edits injected as drafty steps."
+---
+
+# apply-galaxy-workflow-changeset
+
+Follow the procedure below and use the artifact/reference sections as the runtime contract.
+
+## When To Use
+
+- Apply a reviewed change-set to a concrete Galaxy workflow: untouched regions preserved, tool-introducing edits injected as drafty steps.
+
+## Inputs
+
+- Read artifact `starting-galaxy-workflow`. Produced by `summarize-galaxy-workflow`. The normalized concrete gxformat2 workflow being modified, emitted by summarize-galaxy-workflow (passthrough when already gxformat2, the `.ga`→gxformat2 conversion otherwise). The substrate edits apply to — untouched regions must survive byte-for-byte.
+- Read artifact `galaxy-workflow-changeset`. Produced by `interview-to-galaxy-workflow-changeset`. Reviewed, step-anchored change-set from interview-to-galaxy-workflow-changeset; the edit intents to realize.
+- 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 `galaxy-workflow-draft` as `galaxy-workflow-draft.gxwf.yml`. Format: `yaml`. Schema: galaxy-workflow-draft. gxformat2 draft (see galaxy-workflow-draft-format) of the whole workflow: untouched steps carried at Resolved tier verbatim; tool-introducing/replacing edits injected as drafty steps with _plan_* fields for the per-step loop; direct edits applied inline.
+- 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/galaxy-workflow-draft-format.md`: Research note copied verbatim into the bundle. Represent the whole workflow as a draft: carry untouched steps at Resolved tier, inject tool-introducing/replacing edits as drafty steps with _plan_state / _plan_context / _plan_in / _plan_out.
+- `references/notes/open-requirements-ledger.md`: Research note copied verbatim into the bundle. Close the open entries the change-set discharges, and append a blocking entry for an edited region whose output the rewired inputs cannot supply, so an edit-introduced gap is recorded rather than discovered downstream.
+- `references/schemas/galaxy-workflow-draft.schema.json`: Schema file copied verbatim into the bundle. Output contract: the emitted gxformat2 draft conforms to galaxy-workflow-draft. Cast bundles the JSON Schema so the skill carries its output shape alongside draft-validate checks.
+
+## Load On Demand
+
+- `references/cli/draft-validate.json`: CLI command reference packaged as a sidecar. Validate the emitted draft against draft-contract rules (sentinel form, topology, _plan_* placement) before handing off to the per-step loop. Use when: after writing the modified draft workflow file.
+
+## Validation
+
+- Validate `galaxy-workflow-draft.gxwf.yml` for artifact `galaxy-workflow-draft` against the galaxy-workflow-draft schema when a validator is available.
+
+## Procedure
+
+Apply a reviewed change-set to a concrete Galaxy workflow and emit a `galaxy-workflow-draft.gxwf.yml`. This skill plays the topology-settling role the `*-to-galaxy-template` skills play in the greenfield pipelines — but it starts from an already-concrete workflow, so its defining job is to change **only** what the change-set names and carry everything else through untouched.
+
+**An edit is a drafty region.** The Foundry already drains drafty steps out of a partially-concrete workflow via advance-galaxy-draft-step. So this skill does not resolve tools or run an edit loop of its own. It represents the whole modified workflow as a draft (see galaxy-workflow-draft-format): untouched steps carried at Resolved tier verbatim, and any edit that introduces or replaces a tool injected as a **drafty step + `_plan_*`** for the per-step loop to realize.
+
+### What to apply directly vs. defer
+
+- **Direct edits (applied inline, no drafty step).** `remove-step`, `rewire`, `relabel` / `annotate`, `change-parameter`, `add-input` / `remove-input`, `add-output` / `expose-output`. These need no tool resolution: edit the concrete step/input/output in place and rewire consumers as the change-set dictates. A change-set of purely direct edits yields a draft with `draft: false` — an immediately concrete workflow, no loop iterations.
+- **Deferred edits (injected as drafty steps).** `add-step` and `replace-tool` (when the replacement is a different tool or an unpinned version). Add the step at draft tier with `tool_id: TODO` (or Identity-pinned when the change-set pinned an id), and record the operation, source evidence, and constraints in `_plan_state` / `_plan_context` / `_plan_in` / `_plan_out` so advance-galaxy-draft-step can resolve a wrapper and concretize it.
+
+### Preserve untouched regions
+
+Every step, input, and output the change-set does not name must survive byte-for-byte: same `tool_id`, `tool_version`, `tool_state`, labels, and connections. Do not reorder, reformat, re-case, or "tidy" an unrelated region — a structural diff of the emitted workflow against the input must touch only the change-set's targets and their necessary consequences (e.g. rewiring a consumer of a replaced producer). Gratuitous churn is a defect, not a style choice.
+
+### Computability and the ledger
+
+An edit can create a gap the connection graph won't catch: a rewire whose source doesn't carry what the consumer needs, or a `replace-tool` whose new tool can't supply a downstream port. Before handing off, check each edited region is computable from what feeds it. Where you find a gap you can't wire, append a **blocking** entry to the open-requirements-ledger naming the edit, the uncomputable output, and the missing evidence — so the per-step loop or repair-galaxy-draft-topology acts on it rather than discovering it late. Never fabricate a connection to make the graph look complete.
+
+### Hand off
+
+Run draft-validate on the emitted draft (sentinel form, topology, `_plan_*` placement). On green, hand the draft to advance-galaxy-draft-step, which drains any injected drafty steps and extracts the concrete `galaxy-workflow.gxwf.yml`. If the change-set was all direct edits, the loop is a no-op and the workflow is already concrete.
+
+## 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/apply-galaxy-workflow-changeset/_provenance.json

@@ -0,0 +1,133 @@
+{
+  "provenance_schema_version": 4,
+  "cast_target": "claude",
+  "mold": {
+    "name": "apply-galaxy-workflow-changeset",
+    "path": "content/molds/apply-galaxy-workflow-changeset/index.md",
+    "revision": 3,
+    "content_hash": "82d8e6e440fc48fdb4e7c5a5e25591ecc8e8a248ea03cc950df5096256656b62",
+    "commit": "63a3f9cf9c97a637fe1628d298e524f35709e289"
+  },
+  "cast_at": "2026-09-13T20:58:26.175Z",
+  "refs": [
+    {
+      "kind": "cli-command",
+      "mode": "sidecar",
+      "ref": "[[draft-validate]]",
+      "src": "content/cli/gxwf/draft-validate.md",
+      "dst": "references/cli/draft-validate.json",
+      "used_at": "runtime",
+      "load": "on-demand",
+      "evidence": "hypothesis",
+      "purpose": "Validate the emitted draft against draft-contract rules (sentinel form, topology, _plan_* placement) before handing off to the per-step loop.",
+      "trigger": "After writing the modified draft workflow file.",
+      "verification": "Cast the skill, run on a representative workflow + change-set, confirm draft-validate diagnostics route back.",
+      "src_hash": "37cded427fbccf49ff19a6fe8b03f9e90857afe556e5db0e51a01402fbf33f1e",
+      "dst_hash": "afa59b0815308a340780247df0548909518564d58352a0c695ceca37a07eee5b",
+      "source": "deterministic"
+    },
+    {
+      "kind": "research",
+      "mode": "verbatim",
+      "ref": "[[galaxy-workflow-draft-format]]",
+      "src": "content/research/galaxy-workflow-draft-format/index.md",
+      "dst": "references/notes/galaxy-workflow-draft-format.md",
+      "used_at": "runtime",
+      "load": "upfront",
+      "evidence": "hypothesis",
+      "purpose": "Represent the whole workflow as a draft: carry untouched steps at Resolved tier, inject tool-introducing/replacing edits as drafty steps with _plan_state / _plan_context / _plan_in / _plan_out.",
+      "verification": "Promote after a downstream advance-galaxy-draft-step run drains the injected drafty steps without round-tripping back through the change-set.",
+      "src_hash": "93f3b231dd063bf059c550f18b2200c61909af0da9408e0d43351116e886bf7b",
+      "dst_hash": "93f3b231dd063bf059c550f18b2200c61909af0da9408e0d43351116e886bf7b",
+      "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 the change-set discharges, and append a blocking entry for an edited region whose output the rewired inputs cannot supply, so an edit-introduced gap is recorded rather than discovered downstream.",
+      "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"
+    },
+    {
+      "kind": "schema",
+      "mode": "verbatim",
+      "ref": "[[galaxy-workflow-draft]]",
+      "src": "package://@galaxy-tool-util/schema#galaxyWorkflowDraftJsonSchema",
+      "dst": "references/schemas/galaxy-workflow-draft.schema.json",
+      "used_at": "runtime",
+      "load": "upfront",
+      "evidence": "cast-validated",
+      "purpose": "Output contract: the emitted gxformat2 draft conforms to [[galaxy-workflow-draft]]. Cast bundles the JSON Schema so the skill carries its output shape alongside [[draft-validate]] checks.",
+      "license": "MIT",
+      "license_file": "LICENSES/galaxy-tool-util-ts.LICENSE",
+      "src_hash": "86822b6bf4c11ba1d9eaa12d9e442db7f7d28b2734a2daddf62b5cdd2f1f75aa",
+      "dst_hash": "86822b6bf4c11ba1d9eaa12d9e442db7f7d28b2734a2daddf62b5cdd2f1f75aa",
+      "source": "deterministic",
+      "license_file_hash": "383450c494c01c466bcf22df102540a39ac89da50563fd7be686ba06772f96b3"
+    }
+  ],
+  "artifacts": {
+    "produces": [
+      {
+        "id": "galaxy-workflow-draft",
+        "kind": "yaml",
+        "default_filename": "galaxy-workflow-draft.gxwf.yml",
+        "schema": "[[galaxy-workflow-draft]]",
+        "description": "gxformat2 draft (see [[galaxy-workflow-draft-format]]) of the whole workflow: untouched steps carried at Resolved tier verbatim; tool-introducing/replacing edits injected as drafty steps with _plan_* fields for the per-step loop; direct edits applied inline."
+      },
+      {
+        "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": "starting-galaxy-workflow",
+        "description": "The normalized concrete gxformat2 workflow being modified, emitted by [[summarize-galaxy-workflow]] (passthrough when already gxformat2, the `.ga`→gxformat2 conversion otherwise). The substrate edits apply to — untouched regions must survive byte-for-byte.",
+        "producers": [
+          "summarize-galaxy-workflow"
+        ]
+      },
+      {
+        "id": "galaxy-workflow-changeset",
+        "description": "Reviewed, step-anchored change-set from [[interview-to-galaxy-workflow-changeset]]; the edit intents to realize.",
+        "producers": [
+          "interview-to-galaxy-workflow-changeset"
+        ]
+      },
+      {
+        "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/apply-galaxy-workflow-changeset/_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 draft-validate"
+    ]
+  }
+]

package/extensions/orbit/vendor/skills/apply-galaxy-workflow-changeset/_verify.json

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

package/extensions/orbit/vendor/skills/apply-galaxy-workflow-changeset/references/cli/draft-validate.json

@@ -0,0 +1,140 @@
+{
+  "type": "cli-command",
+  "tool": "gxwf",
+  "command": "draft-validate",
+  "summary": "Validate a `class: GalaxyWorkflowDraft` workflow against draft-contract rules; with --concrete, also validate the extracted concrete subset.",
+  "source_path": "content/cli/gxwf/draft-validate.md",
+  "source_revision": 1,
+  "package": "@galaxy-tool-util/cli",
+  "description": "Validate a draft Galaxy workflow (class: GalaxyWorkflowDraft)",
+  "synopsis": "gxwf draft-validate [options] <file>",
+  "args": [
+    {
+      "raw": "file",
+      "name": "file",
+      "required": true,
+      "variadic": false,
+      "description": "Draft workflow file (.gxwf.yml)"
+    }
+  ],
+  "options": [
+    {
+      "flags": "--format <fmt>",
+      "name": "format",
+      "description": "Force format: format2 (native is rejected for drafts)",
+      "takesArgument": true,
+      "argumentPlaceholder": "<fmt>",
+      "optionalArgument": false,
+      "negatable": false
+    },
+    {
+      "flags": "--json",
+      "name": "json",
+      "description": "Output structured JSON report",
+      "takesArgument": false,
+      "optionalArgument": false,
+      "negatable": false
+    },
+    {
+      "flags": "--report-html [file]",
+      "name": "reportHtml",
+      "description": "Write HTML report to file (or stdout if omitted)",
+      "takesArgument": true,
+      "argumentPlaceholder": "[file]",
+      "optionalArgument": true,
+      "negatable": false
+    },
+    {
+      "flags": "--report-markdown [file]",
+      "name": "reportMarkdown",
+      "description": "Write Markdown report to file (or stdout if omitted)",
+      "takesArgument": true,
+      "argumentPlaceholder": "[file]",
+      "optionalArgument": true,
+      "negatable": false
+    },
+    {
+      "flags": "--concrete",
+      "name": "concrete",
+      "description": "Additionally extract the concrete subset and run the regular `gxwf validate` checks on it",
+      "takesArgument": false,
+      "optionalArgument": false,
+      "negatable": false
+    },
+    {
+      "flags": "--cache-dir <dir>",
+      "name": "cacheDir",
+      "description": "Tool cache directory (for --concrete tool-state validation)",
+      "takesArgument": true,
+      "argumentPlaceholder": "<dir>",
+      "optionalArgument": false,
+      "negatable": false
+    },
+    {
+      "flags": "--offline",
+      "name": "offline",
+      "description": "Do not fetch uncached tools; read only the local cache (uncached tools are skipped)",
+      "takesArgument": false,
+      "optionalArgument": false,
+      "negatable": false
+    },
+    {
+      "flags": "--galaxy-url <url>",
+      "name": "galaxyUrl",
+      "description": "Galaxy instance to try as a tool source after the ToolShed when fetching uncached tools",
+      "takesArgument": true,
+      "argumentPlaceholder": "<url>",
+      "optionalArgument": false,
+      "negatable": false
+    },
+    {
+      "flags": "--no-tool-state",
+      "name": "toolState",
+      "description": "Skip tool-state validation in the --concrete pass (default: enabled when --concrete is set)",
+      "takesArgument": false,
+      "optionalArgument": false,
+      "negatable": true
+    },
+    {
+      "flags": "--connections",
+      "name": "connections",
+      "description": "Validate connection-type compatibility on the --concrete subset (collection algebra, map-over)",
+      "takesArgument": false,
+      "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 draft-validate`\n\nValidate a draft Galaxy workflow against the **draft contract**: sentinel form, dangling edge references, top-level `_plan_*` placement, `_plan_*` on fully-resolved tool steps, and recursive draft subworkflows. Native (.ga) input is rejected — drafts are format2-only.\n\nDistinct from validate, which validates a fully concrete `class: GalaxyWorkflow` and would reject the draft relaxations outright. Use `draft-validate` during the per-step authoring loop; use `validate` at the terminal pass once `promoteFullyConcreteDrafts` has flipped the class.\n\n## Output\n\nDefault output is human-readable: counted buckets for structure / topology / semantic errors and warnings, plus a one-line survey (TODO sentinel count, paths carrying `_plan_*`). `--json` emits a `SingleDraftValidationReport`; `--report-html` and `--report-markdown` write the same data as a self-contained HTML page or templated Markdown. With `--concrete`, the report carries an optional `concrete: ConcreteValidationReport` whose buckets (`structure_errors`, `strict_structure_errors`, `strict_encoding_errors`, `strict_state_errors`, `tool_state`, `connection_report`) are **absent when the corresponding check did not run** — readers should treat absence as \"not run,\" not as \"passed.\"\n\n## Flags\n\n`--concrete` runs the extract+promote pipeline (`extractConcreteSubset` → `stripPlanFields` → `promoteFullyConcreteDrafts`) and applies the full concrete `gxformat2` validation surface to the result. The following pass-through flags only take effect under `--concrete`; passing them without it prints a stderr warning and no-ops:\n\n- `--cache-dir <dir>` — tool cache for tool-state lookups.\n- `--no-tool-state` — skip tool-state validation on the concrete pass. Combined with `--strict-state`, the strict flag warns + no-ops (there's no state to be strict about).\n- `--connections` — run connection validation on the concrete subset.\n- `--strict` — escalate every strict bucket (structure, encoding, state) to error.\n- `--strict-structure` / `--strict-encoding` / `--strict-state` — escalate one bucket only.\n\nDraft structural errors gate the concrete pass entirely — the pipeline would mutate a malformed input, so the concrete section is skipped and only the draft buckets populate.\n\n## Examples\n\n```bash\ngxwf draft-validate workflow.gxwf.yml\ngxwf draft-validate workflow.gxwf.yml --json\ngxwf draft-validate workflow.gxwf.yml --concrete --json\ngxwf draft-validate workflow.gxwf.yml --concrete --strict --cache-dir ~/.cache/gxwf\ngxwf draft-validate workflow.gxwf.yml --report-html report.html\n```\n\n## Exit codes\n\n- `0` — clean draft (no structure / topology / semantic errors; warnings allowed). Under `--concrete`, also requires the concrete pass to be clean.\n- `1` — draft validation errors (topology or semantic). With `--concrete`, also returned when the concrete projection fails — including strict-* failures that `gxwf validate` would have exited `2` on standalone. The asymmetry is deliberate: the draft itself parsed, only its projection failed.\n- `2` — parse failure, native input rejected, structural decode failure (class is not `GalaxyWorkflowDraft`), or a stdout-sink collision between `--json` and `--report-{html,markdown}=-`.\n\n## Gotchas\n\n- The draft validator is **contract-shaped**, not workflow-shaped. It will not catch tool-state errors, parameter-name mismatches, or other concerns that belong to validate on the concretized subset. Use `--concrete` (or run draft-extract | validate manually) when you need both surfaces.\n- A draft with zero implemented steps still runs the `--concrete` pipeline, but the projection is empty — the concrete buckets report `skipped` semantics (absent in the JSON) rather than a green pass. Signal grows as the loop fills steps in; do not interpret early-loop runs as evidence the workflow concretizes correctly.\n- `_plan_*` on a fully-resolved tool step is a `semanticError`, not a warning. Strip planning fields explicitly via draft-extract (or `stripPlanFields`) when a step concretizes; the per-step Mold should never carry them forward.\n- Subworkflow draft roots are validated recursively; diagnostics carry the outer step path.\n- `TODO`, `TODO_x`, `TODO-x` are sentinels; `TODONE` and `TODOLIST` are not.\n- Prefer `--json` whenever a cast skill or harness needs to classify diagnostics."
+}

package/extensions/orbit/vendor/skills/apply-galaxy-workflow-changeset/references/notes/galaxy-workflow-draft-format.md

@@ -0,0 +1,135 @@
+---
+type: research
+title: "Galaxy workflow draft format"
+tags:
+  - target/galaxy
+status: draft
+created: 2026-05-06
+revised: 2026-05-10
+revision: 2
+related_notes:
+  - "gxformat2-schema"
+  - "galaxy-data-flow-draft-contract"
+  - "discover-shed-tool"
+  - "galaxy-workflow-draft"
+  - "open-requirements-ledger"
+related_molds:
+  - "nextflow-summary-to-galaxy-template"
+  - "cwl-summary-to-galaxy-template"
+  - "freeform-summary-to-galaxy-template"
+  - "compare-against-iwc-exemplar"
+  - "implement-galaxy-tool-step"
+  - "advance-galaxy-draft-step"
+  - "repair-galaxy-draft-topology"
+summary: "gxformat2 draft superset: wrapper-tier TODOs (tool_id, state, port names) plus _plan_state / _plan_context / _plan_in / _plan_out per tool step."
+---
+
+# Galaxy workflow draft format
+
+The output artifact `galaxy-workflow-draft` produced by the `*-summary-to-galaxy-template` Molds is **gxformat2 with wrapper-tier relaxations and free-text planning fields**, sized to the gap between data-flow design and tool-resolved implementation.
+
+Topology — workflow inputs and their collection shapes, workflow outputs, the step set, the producer→consumer edge graph, branches, and `when:` guards — is **settled by the template Mold itself**, drawing on the upstream interface and data-flow briefs (see galaxy-data-flow-draft-contract). The output is concrete gxformat2 with no topology TODOs. Wrapper-tier resolution — which Tool Shed wrapper, what parameters, the wrapper-determined port names that populate `in:` / `out:` / `outputSource` — is **evidence-gated per step** (see Resolution tiers below): a step resolves fully when the evidence pins wrapper and parameters together, pins identity alone when the wrapper is named but its settings are not, and defers entirely when the evidence is weak.
+
+A step's declared `in:` arity is a topology decision and must be realizable by one wrapper. Combining N sources into one — concatenate, merge, union — is its own node (`gops_concat_1`, `cat1` for two/N datasets; `collapse_dataset` for a collection), never folded into a downstream 1→1 reshape. A step that would declare ≥2 dataset inputs under a reshape intent (awk, text-reformatting, "reshape") is a missing-combine-node smell: split it into an explicit combine step plus single-input reshapes. The relevant concat/merge/union recipes are reachable through the tabular, interval, and collection pattern indices the template already consults.
+
+## Resolution tiers
+
+Each tool step is resolved to the tier its evidence supports — **evidence-gated, not source-gated**. The source kind (free-form, nf-core, CWL) shifts how often a step reaches each tier but never caps it; each `*-summary-to-galaxy-template` Mold records its own source tendency.
+
+- **Resolved** — concrete `tool_id`, `tool_shed_repository` / changeset (or a stable built-in id), and bound `state`; no `_plan_*`. Use when the evidence pins wrapper *and* parameters jointly: a built-in Galaxy tool with brief-determined params (`Filter1`, `Cut1`, a collection operation), or a pattern page / IWC exemplar worked example that supplies `tool_id`, changeset, and parameter values together. `draft-validate` rejects `_plan_*` on a fully-resolved step.
+- **Identity-pinned** — concrete `tool_id` with `tool_version: TODO` (changeset deferred); `state` and `tool_shed_repository` absent; `_plan_state` (and any other open `_plan_*`) kept. The `tool_version: TODO` sentinel is load-bearing: it keeps the step drafty for draft-next-step and not-fully-resolved for draft-validate, so the retained `_plan_state` is legal rather than a `semanticError`. (A step is "fully-resolved" — and so forbidden from carrying `_plan_*` — exactly when it has *no* remaining TODO sentinel in `tool_id`, `tool_version`, or any `in:` / `out:` port; pinning identity without this sentinel would trip that gate.) Use when the evidence confidently names *which* wrapper but not its settings or exact changeset for this context: a portion of an IWC exemplar that compare-against-iwc-exemplar flags as a high-confidence match, a pattern page's worked example, or a source summary that names a specific `tool_id` with evidence.
+- **Deferred** — `tool_id: TODO`, full `_plan_*`. Use when the evidence is weak, multi-candidate, a domain-specific scientific tool with no covering pattern or exemplar, or a corpus gap.
+
+Pin identity only on strong evidence — a wrapper an exemplar actually uses for the same operation, a worked pattern example, or a tool the source names explicitly — never on plausibility: a wrong pinned `tool_id` lets discover-shed-tool resolve the wrong tool's changeset instead of searching afresh. Port names follow the wrapper: real on a Resolved step, `TODO_<hint>` sentinels until the step resolves.
+
+The per-step loop does not edit topology — but it may **escalate back to a template-tier Mold** when implementation proves the settled topology can't support a declared step (see "Topology repair escalation" below). Wiring authority stays in the template tier; the loop only gains a path back to it.
+
+## Relaxations vs. gxformat2
+
+For tool steps, when the wrapper has not been picked:
+
+- `tool_id` and `tool_version` MAY be the literal string `TODO`. Resolution belongs to discover-shed-tool and the per-step implementation Mold.
+- `tool_shed_repository` (the `{ changeset_revision, name, owner, tool_shed }` block) MAY be absent.
+- `state` MAY be absent. A draft is authored, so it uses `state` — never the export-side
+  `tool_state`; see gxformat2-schema for the distinction.
+- Step `out[].id` and `in[]` keys MAY be `TODO_<hint>` sentinels (e.g. `TODO_trimmed_paired`, `TODO_input`). Workflow `outputs[].outputSource` MAY reference such a sentinel via `step/TODO_<hint>` so the connection graph still resolves syntactically. The connection itself (which step's output feeds which step's input) is topology and MUST be present; only the wrapper-determined port names are deferred.
+
+Workflow inputs (types, collection shapes, formats, optionality), workflow outputs, step labels, and the producer→consumer edge set MUST be expressed in normal gxformat2 form with concrete values — never `TODO`. The template Mold is the locus where these decisions are made; if the upstream brief leaves a topology choice open, decide it here from source evidence, IWC exemplars, and pattern pages rather than punting downstream.
+
+## Additions: `_plan_*` planning fields
+
+Free-text fields per tool step capture the template Mold's intent for the downstream per-step implementation Mold. All optional, but expected on any Identity-pinned or Deferred step (`tool_id` is `TODO`, or `tool_id` is pinned but `state` is absent); a Resolved step carries none.
+
+- `_plan_state` — parameter binding intent: which knobs matter, value or range, why. Read by the per-step Mold to bind real `state` once a wrapper is selected.
+- `_plan_context` — extras the per-step Mold needs to pick a wrapper: source `command:` block, conda packages, Docker/Singularity images, environment variables, preconditions, postconditions, container entrypoints, scratch-disk needs.
+- `_plan_in` — wrapper input port mapping intent. The connection graph already says "this source feeds this step"; `_plan_in` records the semantic role of each port and likely wrapper-side names (`single_paired` vs `paired_input` vs `input`) so the per-step Mold can collapse `TODO_*` keys to the real ones.
+- `_plan_out` — wrapper output surface intent: which outputs downstream consumers depend on (with the existing edges as evidence) so the per-step Mold can pick a wrapper that exposes them, or insert a follow-up step if it does not.
+
+The `_plan_*` family is **wrapper-tier**: each entry exists because the wrapper is not yet fully resolved and disappears the moment the step is. Topology decisions do not belong here.
+
+`_plan_*` fields are **draft-only**. They MUST be removed before the workflow is treated as a runnable gxformat2 document. Any remaining `TODO` / `TODO_*` sentinels MUST also be resolved at the same time.
+
+## Example (sketch)
+
+```yaml
+class: GalaxyWorkflowDraft
+inputs:
+  reads:
+    type: collection
+    collection_type: list:paired
+    format: fastqsanger.gz
+outputs:
+  trimmed:
+    outputSource: fastp/TODO_trimmed_paired
+steps:
+  fastp:
+    tool_id: TODO
+    label: trim and QC paired reads
+    in:
+      TODO_input: reads
+    out:
+      - id: TODO_trimmed_paired
+      - id: TODO_html_report
+    _plan_state: |
+      adapter trimming on, quality cutoff ~Q20, min length ~50.
+      preserve paired-end pairing for downstream alignment.
+    _plan_context: |
+      upstream: nf-core FASTP module.
+      conda: bioconda::fastp=0.23.4
+      container: quay.io/biocontainers/fastp:0.23.4--h5f740d0_0
+      precondition: paired list collection with sane element identifiers
+    _plan_in: |
+      single semantic port `reads`: feeds workflow `reads` (list:paired).
+      wrapper input port name likely one of `single_paired` | `paired_input` |
+      `input` depending on which fastp wrapper is picked.
+    _plan_out: |
+      need a paired output that preserves list:paired shape (downstream
+      alignment step consumes it). also expose the HTML report as a
+      checkpoint output for QC.
+```
+
+## Why this shape
+
+- Keeps the artifact recognizably gxformat2 so static tooling (`gxwf validate --no-tool-state`, structural diff against IWC) still applies to topology and port wiring.
+- Carves a stable handoff between the template Mold and the per-step implementation Mold without sneaking tool resolution into either side.
+- Makes the boundary between topology (settled upstream) and wrapper-tier (deferred) explicit — the `_plan_*` family lives squarely on the deferred side.
+- Free-text `_plan_*` is intentional for v1: it lets the templating agent record intent without a contract pretending to be parameterizable yet. Structuring those fields is open work — see each template Mold's `refinement.md`.
+
+## Topology repair escalation
+
+The template Mold settles topology, but it can miss a **computability** gap: a step whose declared output needs evidence no wired input carries. The connection graph validates — ports connect — yet the step can't be implemented. The template's computability review pass catches most of these and either wires the producer or records the gap in the open-requirements-ledger; the rest surface in the per-step loop.
+
+When one surfaces, the per-step loop does not author topology to fix it. It **escalates**:
+
+- implement-galaxy-tool-step detects, while implementing, that the declared output can't be computed from the wired inputs. It appends a blocking entry to the open-requirements-ledger and falls through rather than fabricating the output.
+- repair-galaxy-draft-topology — a template-tier Mold sharing the template's reference set — reads the blocking entries and re-wires the affected region: one producer step, a small sub-path, or honest narrowing of the output. New steps land at draft (wrapper-tier `TODO`) tier, so the existing discover-or-author → implement machinery realizes them.
+
+This is **repair**, distinct from **settling**: it is narrow (one named region), reactive (only a detected computability gap triggers it), and bounded. The loop's convergence gate counts open blocking entries in the ledger; each escalation must strictly reduce that count, under a hard cap on escalations. When the cap is reached with entries still open, they are **surrendered** — written into the final draft as labelled gaps — the clean terminal that replaces spin-or-fabricate. So the boundary "topology decisions do not belong in the per-step loop" still holds: the loop never decides topology, it returns the decision to the template tier.
+
+## Open work
+
+- Decide whether `_plan_state` should grow structure (parameter-name hints, value ranges, references back to the source summary).
+- Decide whether `_plan_context` should be split into typed fields (`source_command`, `conda`, `containers`, `env`, `pre`, `post`).
+- Decide structure for `_plan_in` and `_plan_out` once two or three worked drafts exercise them. Candidate `_plan_out`: array of `{ semantic_name, downstream_consumers[], required_for }`. Candidate `_plan_in`: map keyed by the `TODO_*` placeholder key to `{ semantic_name, source_step_output, shape_constraint }`.
+- Pick a JSON Schema strategy: extend the gxformat2 schema with `_plan_*` and the relaxed wrapper / port-name rules, or validate the draft via a sibling schema that wraps gxformat2 with the relaxations.
+- Specify the strip step that converts a draft into a runnable gxformat2 workflow. It MUST drop all `_plan_*` fields and reject any remaining `TODO` or `TODO_<hint>` sentinel in `tool_id`, `tool_version`, `out[].id`, `in[]` keys, or `outputSource`.