Agent Skill · cast

cwl-test-to-galaxy-test-plan

Translate CWL test fixtures into a Galaxy workflow test plan.

Install with Claude Code

/plugin marketplace add galaxyproject/foundry
/plugin install foundry-skills@galaxy-workflow-foundry

Then invoke as:

/foundry-skills:cwl-test-to-galaxy-test-plan

Install with Codex

codex plugin marketplace add galaxyproject/foundry
codex plugin add foundry-skills@galaxy-workflow-foundry

Then select with /skills or invoke explicitly as:

$cwl-test-to-galaxy-test-plan

Skill Bundle

/ packaged cast

attached files: 8
upfront: 2
on demand: 6
cast rev: n/a
validated: 0

Produces: 1 artifact.

Consumes: 1 artifact.

Artifact Contract

/ skill handoff

Produces

galaxy-test-plan

Reviewable Galaxy workflow test plan (see [[galaxy-workflow-test-plan]]) derived from CWL test fixtures, job inputs, expected outputs, and assertion evidence.

yamlgalaxy-test-plan.yml[[galaxy-workflow-test-plan]]

Raw artifact contract

{
  "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]]) derived from CWL test fixtures, job inputs, expected outputs, and assertion evidence."
}

Consumes

summary-cwl

Structured CWL summary from [[summarize-cwl]]; carries test fixtures, job inputs, expected outputs.

Raw artifact contract

{
  "id": "summary-cwl",
  "description": "Structured CWL summary from [[summarize-cwl]]; carries test fixtures, job inputs, expected outputs.",
  "inherited_schema": "[[summary-cwl]]",
  "producers": [
    "summarize-cwl"
  ]
}

Attached Files

/ runtime references

Load upfront

schema

galaxy-workflow-test-plan

packaged

Output contract: the emitted plan conforms to [[galaxy-workflow-test-plan]]. Cast bundles the JSON Schema; validate with `foundry validate-galaxy-workflow-test-plan`.

upfront runtime verbatim hypothesis deterministic 18.0 KB

bundle: references/schemas/galaxy-workflow-test-plan.schema.json
source: package://@galaxy-foundry/foundry#galaxyWorkflowTestPlanSchema

Preview json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://galaxyproject.org/foundry/schemas/galaxy-workflow-test-plan.schema.json",
  "$comment": "Canonical source: packages/foundry/src/schemas/galaxy-workflow-test-plan/galaxy-workflow-test-plan.schema.json in galaxyproject/foundry. Mold frontmatter cites this schema via [[galaxy-workflow-test-plan]] wiki-links; the cast pipeline imports the `galaxyWorkflowTestPlanSchema` runtime export and serializes it into cast bundles. The on-disk artifact is YAML; validate it with `foundry validate-galaxy-workflow-test-plan`.",
  "title": "Galaxy Workflow Test Plan",
  "description": "Intermediate, reviewable Galaxy workflow test-plan handoff produced by a *-test-to-galaxy-test-plan Mold (nextflow, cwl, freeform, or galaxy) and consumed by implement-galaxy-workflow-test. It preserves test intent, fixture provenance, assertion intent, tolerances, label assumptions, unresolved mappings, and intentional omissions before any concrete tests-format `*-tests.yml` is authored. It is NOT the final test artifact: assertion vocabulary is referenced by family name from the tests-format schema, not duplicated here.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "plan_version",
    "source",
    "workflow",
    "test_cases",
    "unresolved",
    "omissions",
    "warnings"
  ],
  "properties": {
    "plan_version": {
      "type": "string",
      "enum": [
        "1"
      ],
      "description": "Test-plan schema major version."
    },
    "source": {
      "$ref": "#/$defs/SourceRecord"
    },
    "workflow": {
      "$ref": "#/$defs/WorkflowRef"
    },
    "test_cases": {
      "type": "array",
      "description": "One entry per planned Galaxy workflow test (each becomes one tests-format test entry downstream).",
      "items": {
        "$ref": "#/$defs/TestCase"
      }
    },
    "unresolved": {
      "type": "array",
      "description": "Mappings the plan could not resolve and that implement-galaxy-workflow-test (or a reviewer) must settle before authoring the final test file.",
      "items": {
        "$ref": "#/$defs/UnresolvedItem"
      }
    },
    "omissions": {
      "type": "array",
      "description": "Outputs or behaviors deliberately left unasserted, with rationale, so the gap is a recorded decision rather than an oversight.",
      "items": {
        "$ref": "#/$d
...

schema

summary-cwl

packaged

Read the CWL summary's test cases, job inputs, expected outputs, and assertion evidence.

upfront runtime verbatim corpus-observed deterministic 19.3 KB

bundle: references/schemas/summary-cwl.schema.json
source: package://@galaxy-foundry/foundry#summaryCwlSchema

Preview json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://galaxyproject.org/foundry/schemas/summary-cwl.schema.json",
  "$comment": "Canonical source: packages/foundry/src/schemas/summary-cwl/summary-cwl.schema.json in galaxyproject/foundry. Mold frontmatter cites this schema via [[summary-cwl]] wiki-links; the cast pipeline imports the `summaryCwlSchema` runtime export and serializes it into cast bundles.",
  "title": "CWL Workflow Summary",
  "description": "Structured per-source summary emitted by the summarize-cwl Mold. CWL is already a typed workflow language, so this schema records validated and normalized workflow/tool structure rather than inferred pipeline semantics.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "summary_version",
    "source",
    "documents",
    "workflow_inputs",
    "workflow_outputs",
    "steps",
    "tools",
    "graph",
    "tests",
    "warnings"
  ],
  "properties": {
    "summary_version": {
      "type": "string",
      "enum": [
        "1"
      ],
      "description": "Summary schema major version."
    },
    "source": {
      "$ref": "#/$defs/SourceRecord"
    },
    "documents": {
      "$ref": "#/$defs/DocumentSet"
    },
    "workflow_inputs": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/WorkflowInput"
      }
    },
    "workflow_outputs": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/WorkflowOutput"
      }
    },
    "steps": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/WorkflowStep"
      }
    },
    "tools": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/CommandLineTool"
      }
    },
    "graph": {
      "$ref": "#/$defs/WorkflowGraph"
    },
    "tests": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/TestCase"
      }
    },
    "warnings": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Warning"
      }
    }
  },
  "$defs": {
    "SourceRecord": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "ecosystem",
        "workflow",
        "url",
        "version",
        "license",
        "slug",
        "cwl_version",
        "entrypoint"
      ],
      "properties": {
        "ecosystem": {
          "type": "string",
          "enum": [
            "cwl"
          ],
          "description": 
...

Load on demand

research

galaxy-workflow-testability-design

packaged

Choose which workflow outputs and promoted checkpoints make meaningful assertions.

Trigger: When deciding which outputs to assert and which labels the plan should bind to.

on-demand runtime verbatim corpus-observed deterministic 11.4 KB

bundle: references/notes/galaxy-workflow-testability-design.md
source: content/research/galaxy-workflow-testability-design/index.md

Preview md

---
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 doma
...

research

iwc-shortcuts-anti-patterns

packaged

Distinguish accepted IWC-style test shortcuts from assertion smells while translating tests.

Trigger: When deciding whether to use existence-only, size-only, image-dimension, or tolerant output checks.

on-demand runtime verbatim corpus-observed deterministic 23.9 KB

bundle: references/notes/iwc-shortcuts-anti-patterns.md
source: content/research/iwc-shortcuts-anti-patterns/index.md

Preview md

---
type: research
tags:
  - target/galaxy
status: draft
created: 2026-04-30
revised: 2026-05-03
revision: 2
related_notes:
  - "[[galaxy-workflow-testability-design]]"
  - "[[iwc-test-data-conventions]]"
  - "[[planemo-asserts-idioms]]"
  - "[[implement-galaxy-workflow-test]]"
  - "[[tests-format]]"
  - "[[iwc-conditionals-survey]]"
  - "[[iwc-map-over-lifecycle-survey]]"
  - "[[iwc-tabular-operations-survey]]"
  - "[[iwc-transformations-survey]]"
summary: "What IWC test suites cut corners on (accepted) vs what's a code smell — existence-only probes, sim_size deltas, image dim checks, label coupling."
---

# IWC test-suite shortcuts and anti-patterns

## Purpose

When an agent translates or authors a Galaxy workflow for IWC submission, the test suite it writes will be reviewed against IWC's *de facto* style — not against an idealized assertion ladder. That style routinely tolerates assertions that look weak in isolation. This note distinguishes the corner-cutting that is **normal and accepted** in the corpus from the patterns that an agent should treat as **smells** worth flagging.

This note owns accepted-vs-smell calls. For positive workflow-structure guidance behind label stability, checkpoint promotion, and collection identifier design, use [[galaxy-workflow-testability-design]].

Grounding: 115 `*-tests.yml` files under `workflow-fixtures/iwc-src/workflows/` (mirror of `galaxyproject/iwc`), prior synthesis in `galaxy-brain/vault/projects/workflow_state/skills/COMPONENT_GALAXY_WORKFLOW_TESTING.md`. Path citations below are relative to `iwc-src/workflows/` unless absolute.

## TL;DR rules of thumb

1. **Default to tolerant assertions.** `compare: sim_size` + `delta:`, `has_image_*` + `delta:`, `has_text` substring, `has_h5_keys`, `has_n_lines` + `delta:` are *the IW
...

research

iwc-test-data-conventions

packaged

Emit Galaxy/IWC-style job input fixtures, remote locations, hashes, and collection input shapes.

Trigger: When writing job inputs or deciding whether fixtures belong in test-data, Zenodo, ENA/SRA, or CVMFS.

on-demand runtime verbatim corpus-observed deterministic 21.1 KB

bundle: references/notes/iwc-test-data-conventions.md
source: content/research/iwc-test-data-conventions/index.md

Preview md

---
type: research
tags:
  - target/galaxy
status: draft
created: 2026-04-30
revised: 2026-05-03
revision: 3
related_notes:
  - "[[galaxy-workflow-testability-design]]"
  - "[[iwc-shortcuts-anti-patterns]]"
  - "[[planemo-asserts-idioms]]"
  - "[[implement-galaxy-workflow-test]]"
  - "[[tests-format]]"
  - "[[iwc-tabular-operations-survey]]"
summary: "How IWC workflows organize and reference test data — Zenodo-first, SHA-1 integrity, collection shapes, CVMFS gotchas."
---

# IWC test data conventions

Reference for an agent implementing or editing a `<workflow>-tests.yml` in IWC style. All evidence cited from `/Users/jxc755/projects/repositories/workflow-fixtures/iwc-src/workflows/` (raw IWC clone) and `workflows/README.md`. Authoritative spec: [planemo.readthedocs.io/en/latest/test_format.html](https://planemo.readthedocs.io/en/latest/test_format.html). The companion analysis at `/Users/jxc755/projects/repositories/galaxy-brain/vault/projects/workflow_state/skills/COMPONENT_GALAXY_WORKFLOW_TESTING.md` is the synthesized source for several normative claims here.

This note owns **test YAML fixture shapes**. For workflow-structure choices that make those fixtures possible before the test file exists, use [[galaxy-workflow-testability-design]].

## 1. Where does test data live? Remote vs in-repo

Two storage patterns. They mix freely inside one job.

**Remote `location:` (default for any non-trivial input).** Strongly preferred for anything bigger than a toy fixture. Order of preference, observed in the corpus:

- **Zenodo** — overwhelming default, persistent DOI-backed URL.
  - `read-preprocessing/short-read-qc-trimming/short-read-quality-control-and-trimming-tests.yml:13,17` — `https://zenodo.org/records/11484215/files/paired_r1.fastq.gz` (note the modern `/records/` pl
...

research

planemo-asserts-idioms

packaged

Describe Galaxy workflow-test assertion intent and tolerances for translated expected outputs.

Trigger: When turning CWL expected outputs into Galaxy test-plan assertions.

on-demand runtime verbatim corpus-observed deterministic 18.1 KB

bundle: references/notes/planemo-asserts-idioms.md
source: content/research/planemo-asserts-idioms/index.md

Preview md

---
type: research
tags:
  - target/galaxy
status: draft
created: 2026-04-30
revised: 2026-05-11
revision: 6
related_notes:
  - "[[galaxy-workflow-testability-design]]"
  - "[[iwc-test-data-conventions]]"
  - "[[iwc-shortcuts-anti-patterns]]"
  - "[[implement-galaxy-workflow-test]]"
  - "[[tests-format]]"
  - "[[planemo-workflow-test-architecture]]"
  - "[[validate-tests]]"
  - "[[iwc-tabular-operations-survey]]"
  - "[[galaxy-discover-datasets]]"
summary: "Decision and idiom guide for picking planemo workflow-test assertions: which family per output type, how to size tolerances, when to validate."
---

# Planemo asserts: idiom and decision guide

Companion to [[iwc-test-data-conventions]] (input shapes), [[galaxy-workflow-testability-design]] (workflow structure before test YAML exists), and [[iwc-shortcuts-anti-patterns]] (what's accepted vs smell). This note is forward-looking: when authoring a new `<workflow>-tests.yml`, which assertion family fits which output, and what the recommended tolerances and operators are.

The **vocabulary itself is not restated here** — every assertion's parameter list, types, defaults, required fields, and Python docstring is rendered from the test-format JSON Schema at [[tests-format]]. Assertion names below deep-link into that page (e.g. [[tests-format#has_text_model|has_text]] jumps straight to that `$def`).

## 1. Choose by output type

The single most useful decision table. Pick the row that matches the file format the workflow emits; default to the recommended assertion family.

| Output type | Default assertion family | Why | Fallback |
|---|---|---|---|
| **Plain text reports / logs** (FastQC summary, MultiQC text section) | [[tests-format#has_text_model|has_text]] (substring on a known stable token) + [[tests-format#has_n_lines
...

research

planemo-workflow-test-architecture

packaged

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.

on-demand runtime verbatim corpus-observed deterministic 8.1 KB

bundle: references/notes/planemo-workflow-test-architecture.md
source: content/research/planemo-workflow-test-architecture/index.md

Preview md

---
type: research
title: "Planemo workflow-test architecture"
tags:
  - tool/planemo
  - target/galaxy
status: draft
created: 2026-05-02
revised: 2026-05-11
revision: 3
related_notes:
  - "[[galaxy-workflow-testability-design]]"
  - "[[galaxy-tool-job-failure-reference]]"
  - "[[galaxy-workflow-invocation-failure-reference]]"
  - "[[planemo-asserts-idioms]]"
related_molds:
  - "[[run-workflow-test]]"
  - "[[debug-galaxy-workflow-output]]"
  - "[[implement-galaxy-workflow-test]]"
sources:
  - "~/projects/repositories/planemo/planemo/commands/cmd_test.py"
  - "~/projects/repositories/planemo/planemo/commands/cmd_run.py"
  - "~/projects/repositories/planemo/planemo/galaxy/activity.py"
  - "~/projects/repositories/planemo/planemo/galaxy/invocations"
  - "~/projects/repositories/planemo/planemo/galaxy/config.py"
summary: "Reference for Planemo workflow test/run architecture, Galaxy modes, API polling, and noisy failure boundaries."
---

# Planemo Workflow-Test Architecture

This note describes Planemo architecture relevant to workflow tests and workflow runs. It is reference material for Molds that need to run tests or interpret Planemo artifacts, not a command-selection recipe.

## Main Commands

| User action | Command | Core behavior |
|---|---|---|
| Full workflow test | `planemo test <workflow>` ([[planemo-test]]) | Finds test definitions, starts or targets Galaxy, stages inputs, invokes workflow, checks assertions, writes reports. |
| Direct run | `planemo run <workflow> <job.yml>` | Runs one workflow/job pair and can download outputs without assertion checks. |
| Recheck assertions | `planemo workflow_test_on_invocation <tests.yml> <invocation_id>` ([[planemo-workflow_test_on_invocation]]) | Runs test assertions against an existing invocation without rerunning the wo
...

schema

tests-format

packaged

Use the Galaxy workflow tests schema as the assertion-family vocabulary when translating CWL test evidence into a Galaxy test plan.

Trigger: When mapping expected outputs, tolerances, or fixture assertions into Galaxy workflow-test assertion intent.

on-demand runtime verbatim corpus-observed deterministic 201.1 KB

bundle: references/schemas/tests-format.schema.json
source: package://@galaxy-foundry/foundry#testsFormatSchema

Preview json

{
  "$defs": {
    "Collection": {
      "additionalProperties": false,
      "properties": {
        "class": {
          "const": "Collection",
          "title": "Class",
          "type": "string"
        },
        "collection_type": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Collection Type"
        },
        "elements": {
          "anyOf": [
            {
              "items": {
                "oneOf": [
                  {
                    "oneOf": [
                      {
                        "$ref": "#/$defs/LocationFile"
                      },
                      {
                        "$ref": "#/$defs/PathFile"
                      },
                      {
                        "$ref": "#/$defs/ContentsFile"
                      },
                      {
                        "$ref": "#/$defs/CompositeDataFile"
                      }
                    ]
                  },
                  {
                    "$ref": "#/$defs/Collection"
                  }
                ]
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Elements"
        },
        "identifier": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Identifier"
        },
        "name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Name"
        },
        "rows": {
          "anyOf": [
            {
              "additionalProperties": {
                "items": {},
                "type": "array"
              },
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Rows"
        }
      },
      "required": [
        "class"
      ],
      "title": "Collection",
      "type": "object"
    },
    "CollectionAttributes": {
      "additionalProperties": false,
...

SKILL.md


# cwl-test-to-galaxy-test-plan

Follow the procedure below and use the artifact/reference sections as the runtime contract.

## When To Use

- Translate CWL test fixtures into a Galaxy workflow test plan.

## Inputs

- Read artifact `summary-cwl`. Schema: summary-cwl. Produced by `summarize-cwl`. Structured CWL summary from summarize-cwl; carries test fixtures, job inputs, expected outputs.

## 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) derived from CWL test fixtures, job inputs, expected outputs, and assertion evidence.

## 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; validate with `foundry validate-galaxy-workflow-test-plan`.
- `references/schemas/summary-cwl.schema.json`: Schema file copied verbatim into the bundle. Read the CWL summary's test cases, job inputs, expected outputs, and assertion evidence.

## Load On Demand

- `references/notes/galaxy-workflow-testability-design.md`: Research note copied verbatim into the bundle. Choose which workflow outputs and promoted checkpoints make meaningful assertions. Use when: deciding which outputs to assert and which labels the plan should bind to.
- `references/notes/iwc-shortcuts-anti-patterns.md`: Research note copied verbatim into the bundle. Distinguish accepted IWC-style test shortcuts from assertion smells while translating tests. Use when: deciding whether to use existence-only, size-only, image-dimension, or tolerant output checks.
- `references/notes/iwc-test-data-conventions.md`: Research note copied verbatim into the bundle. Emit Galaxy/IWC-style job input fixtures, remote locations, hashes, and collection input shapes. Use when: writing job inputs or deciding whether fixtures belong in test-data, Zenodo, ENA/SRA, or CVMFS.
- `references/notes/planemo-asserts-idioms.md`: Research note copied verbatim into the bundle. Describe Galaxy workflow-test assertion intent and tolerances for translated expected outputs. Use when: turning CWL expected outputs into Galaxy test-plan assertions.
- `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 translating CWL test evidence into a Galaxy test plan. Use when: mapping expected outputs, tolerances, or fixture assertions into Galaxy workflow-test assertion intent.

## Validation

- Validate `galaxy-test-plan.yml` before returning it: run `foundry validate-galaxy-workflow-test-plan galaxy-test-plan.yml` from `@galaxy-foundry/foundry`. If the command is not on PATH, run `npx --package @galaxy-foundry/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

Translate CWL test fixtures, job inputs, expected outputs, and assertion evidence into a Galaxy workflow test plan. The output is a reviewable YAML handoff conforming to galaxy-workflow-test-plan, not a concrete `tests-format` file; implement-galaxy-workflow-test owns final YAML authoring and static validation. Because this plan is translated from real CWL test fixtures, set `source.derived_from: test-evidence` and prefer `evidence: test-evidence` on the assertions it carries.

## 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.