feat(workflows): add workflow step submission intake

[mnriem]

Summary

• add the canonical intake-only issue form for community workflow step-type submissions
• capture the current external package/catalog contract, including version-pinned file URLs with exact per-file SHA-256 digests
• document the current manual community catalog path and executable-code trust boundary
• add regression coverage for the exact triage-must-have label, absence of premature validation labels, field IDs, required fields, and unchanged behavior of other issue forms

This is phase 1 only. It does not add a validation workflow, classifier, draft-PR generator, functional workflow-step-submission trigger, or catalog entry.

Contract mapping

The form follows the implementation currently used by specify workflow step:

• catalog ID = step.type_key = matching StepBase.type_key
• one installed package registers one step type
• catalog installs download step.yml, __init__.py, and declared extra_files
• the SHA-256 mapping covers exactly those downloaded files
• exact release selection uses PEP 440-compatible versions and verifies step.version

Repository, license, documentation, changelog, compatibility, and runtime dependency fields provide provenance and manual-review evidence. The documentation explicitly notes that compatibility and dependency semantics are not yet defined or enforced by a canonical step catalog schema.

Validation

• LC_ALL=en_US.UTF-8 .venv/bin/python -m pytest tests/test_github_workflows.py -q — 127 passed
• uvx ruff@0.15.0 check tests/test_github_workflows.py — passed
• YAML/field-ID validation — passed; 22 unique valid field IDs
• git diff --check — passed
• LC_ALL=en_US.UTF-8 .venv/bin/python -m pytest — 9,738 passed, 19 skipped; 9,757 collected

AI assistance disclosure

Implemented with GitHub Copilot using GPT-5.6 Sol in autonomous mode. Copilot researched the existing workflow-step package and catalog contracts, authored the issue form, documentation, and regression tests, resolved the rebase overlap, addressed review feedback, ran validation, and prepared this pull request on behalf of @mnriem.

[Copilot]

Copilot review overview

🟡 Changes recommended

The new community guide is missing from the DocFX community navigation in docs/toc.yml.

Review effort: Balanced
Findings: 1

Open (1)

• Add the new guide to the Community navigation TOC · New

What changed in this PR

Adds intake-only submission support for community workflow step types.

Changes:

• Adds a metadata-rich issue form.
• Documents packaging, provenance, and trust boundaries.
• Adds regression tests for labels and field contracts.

File	Description
.github/​ISSUE_TEMPLATE/​workflow_step_submission.yml	Adds the submission form.
docs/​community/​workflow-steps.md	Documents submission and package contracts.
docs/​community/​overview.md	Links the new guide.
docs/​reference/​workflows.md	References community intake guidance.
tests/​test_github_workflows.py	Tests labels, fields, and intake-only wording.

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🔵 Needs a closer look

The documentation must clarify the community catalog’s discovery-only trust boundary and fix the interrupted package-example flow.

Review effort: Balanced
Findings: None

Resolved since last review (1)

• Add the new guide to the Community navigation TOC

Previously missed (2)

In code that hasn't changed since last review

Clarify that the discovery-only catalog cannot install workflows

docs/​community/​workflow-steps.md:20

The accepted catalog is the built-in community source, which is explicitly configured as discovery-only (install_allowed=False in src/specify_cli/workflows/step/catalog/_domain.py:443-448), so workflow step add <id> refuses to install from it. Please state that security boundary here; otherwise readers may interpret acceptance and the later “consumed by catalog installation” wording as making the submitted executable code installable by ID. Direct archive installation after source review, or a separately curated install-allowed catalog, is the supported path.

Move the intake link after the package tree

docs/​reference/​workflows.md:591

This link interrupts the colon that introduces the package tree, leaving the preceding sentence grammatically attached to an unrelated paragraph. Move the intake link after the tree so the example remains the direct continuation of “containing metadata and executable Python:”.

[mnriem]

Addressed the two previously missed documentation points in 54f7ee88:

• clarified that the built-in community workflow-step catalog is discovery-only, so accepted entries are searchable but cannot be installed by ID unless the user configures a separate install-allowed catalog; direct reviewed archive installation remains supported
• moved the community intake link after the package tree so the example directly follows its introductory colon

Validation: npx --yes markdownlint-cli2@0.23.2 docs/community/workflow-steps.md docs/reference/workflows.md passed with 0 issues, and git diff --check passed.

GitHub Copilot (GPT-5.6 Sol, autonomous) implemented and validated these documentation fixes on behalf of @mnriem.

[Copilot]

Copilot review overview

🟡 Changes recommended

The submitted archive provenance is not immutable or checksum-verifiable as currently specified.

Review effort: Balanced
Findings: 1

Open (1)

• Require immutable archive provenance or SHA-256 verification · New

Previously missed (1)

In code that hasn't changed since last review

Require commit-pinned URLs or immutable release-backed tags

docs/​community/​workflow-steps.md:78

A URL pinned only to a Git tag is still a moving target because the tag can be force-updated unless it is protected by an immutable release. This contradicts the next sentence and the review criterion at line 108. Specify commit-SHA-pinned URLs or tags backed by an immutable release so submitters and reviewers have an enforceable provenance requirement.

[mnriem]

Addressed the release-provenance review in 1893dae0 by aligning the workflow-step form with the existing extension, preset, and bundle forms:

• renamed the field to the shared download-url / Download URL convention and describes it as a versioned release archive
• removed unsupported claims that the archive or tag is immutable
• documented that direct --from installation does not verify an archive digest
• retained the supported per-file SHA-256 contract for install-allowed catalog downloads, which detects changed catalog payload bytes
• added regression assertions that the field aligns with the bundle form and contains no immutability claim

Validation: focused GitHub workflow tests passed (127), Ruff 0.15.0 passed, markdownlint-cli2 0.23.2 passed with 0 issues, YAML/field IDs passed, and git diff --check passed.

GitHub Copilot (GPT-5.6 Sol, autonomous) implemented and validated this review-round update on behalf of @mnriem.

[Copilot]

Copilot review overview

🟡 Changes recommended

The form conflicts with AI-disclosure policy, and the PR description overstates URL immutability.

Review effort: Balanced
Findings: 1

Open (1)

• Include testing details in the provenance statement · New

Resolved since last review (1)

• Require immutable archive provenance or SHA-256 verification

Previously missed (2)

In code that hasn't changed since last review

Add required AI disclosure or extend the policy exemption

.github/​ISSUE_TEMPLATE/​workflow_step_submission.yml:233

This intake ends without the AI disclosure required for issues by CONTRIBUTING.md:349-368. The documented exception names only extension, preset, and bundle forms because they feed validation automation, while this form explicitly says no validation workflow runs. Add the standard ai-disclosure field and update the contract test, or explicitly extend the policy exemption to this manual workflow-step intake.

Correct PR summary wording about version-pinned URLs

.github/​ISSUE_TEMPLATE/​workflow_step_submission.yml:88

The PR summary still says this intake captures “immutable file URLs,” but this field requests tag-pinned URLs and the guide correctly notes that tags can move. The SHA-256 values make changed bytes detectable; they do not make the URLs immutable. Update the PR description to say “version-pinned file URLs with exact per-file SHA-256 digests.”

[mnriem]

Addressed review feedback in 36e2547b:

• added the repository-standard required AI Disclosure field because this phase is manual intake and does not qualify for the catalog-automation exemption
• clarified that the Download URL and Testing Details fields jointly provide release/test evidence, while per-file SHA-256 digests protect the catalog-installation path
• corrected the PR summary to say “version-pinned file URLs with exact per-file SHA-256 digests”

Validation: focused GitHub workflow tests passed (127), pinned Ruff passed, Markdown lint passed, YAML validation passed with 22 unique field IDs, and git diff --check passed.

AI disclosure: This response and the associated changes were generated by GitHub Copilot using GPT-5.6 Sol in autonomous mode; Copilot authored the form, documentation, test, and PR-description updates on behalf of @mnriem.

[Copilot]

Copilot review overview

🔵 Needs a closer look

The documented trust boundary and extra-file path contract do not fully match the implementation.

Review effort: Balanced
Findings: None

Resolved since last review (1)

• Include testing details in the provenance statement

Previously missed (3)

In code that hasn't changed since last review

Document valid package-relative path constraints

.github/​ISSUE_TEMPLATE/​workflow_step_submission.yml:106

package-relative does not capture the catalog validator's accepted path syntax. validate_checksums rejects backslashes, absolute paths, empty/./.. segments, and case-insensitive aliases of step.yml or __init__.py; because this phase has no validator, the current prompt can collect mappings that later fail catalog release validation. State those constraints in the field itself so submitters and manual reviewers can enforce the actual contract.

Clarify installation versus code-loading trust boundaries

docs/​community/​workflow-steps.md:8

This warning misstates the execution boundary: installation validates and copies the package without importing __init__.py (installer.validate_step_package explicitly never executes it), while specify workflow add, run, and resume later call load_custom_steps and execute import-time code. Since this page is defining the trust boundary, distinguish installation from the commands that actually load the code.

Document extra_files path validation restrictions

docs/​community/​workflow-steps.md:69

The contract table omits the path restrictions enforced for extra_files: catalog release validation rejects absolute/backslash paths, empty/./.. segments, and aliases of the two required files. Documenting those rules here is necessary for the claimed package/catalog contract, especially while review is manual.

[mnriem]

Addressed the three contract mismatches identified in review 5434714211 in e3bdf882:

• the issue form now states the exact accepted extra_files path syntax: forward-slash relative paths, no empty/./.. segments, and no case-insensitive aliases of step.yml or __init__.py
• the community guide documents the same path restrictions in both the package and submission contracts
• the trust warning now distinguishes validation/copy during workflow step add from import-time execution when later workflow add, run, or resume commands load installed step packages

Validation: focused GitHub workflow tests passed (127), pinned Ruff passed, Markdown lint passed, YAML validation passed with 22 unique field IDs, and git diff --check passed.

AI disclosure: This response and the associated changes were generated by GitHub Copilot using GPT-5.6 Sol in autonomous mode; Copilot researched the implementation, authored the form/documentation/test updates, and ran validation on behalf of @mnriem.

[Copilot]

Copilot review overview

🟢 Approval recommended

The intake form, documentation, implementation contracts, and focused regression tests are consistent and complete.

Review effort: Balanced
Findings: None