fix(workflows): validate requires keys and reject phantom permissions gate

[zied-jlassi]

Description

A workflow's requires: block was parsed (WorkflowDefinition.requires) but its keys were never validated, so a typo or an unsupported key was silently ignored.

Most importantly, an author could write:

requires:
  permissions:
    shell: true

expecting a runtime capability gate — but no such gate exists. A shell step always runs with the user's privileges, so this declaration gives a false sense of sandboxing. (This came up in #2440, where it was understandably assumed that such a declaration was already enforced.)

This PR makes validate_workflow honest about requires:

• Only the recognised keys are accepted: speckit_version, integrations, tools, mcp.
• Any unknown key is rejected (a typo surfaces at validation time instead of being silently dropped) — same spirit as the recent "fail loudly on unknown" hardening.
• requires.permissions is rejected with an explicit message pointing authors at a gate step for approval, so nobody mistakes it for a security boundary.

It does not add any per-step permission system or runtime prompt — requires stays advisory. The model comment and the docs (docs/reference/workflows.md, workflows/PUBLISHING.md) are updated to say so plainly.

Testing

• Ran existing tests with pytest (full suite green, no regressions)
• Tested locally with uv run specify --help
• Added tests: valid recognised keys, non-mapping requires, unknown key, and requires.permissions

Validation is reached on the user-facing paths (workflow add / info / run), so the new errors actually surface.

AI Disclosure

• I did not use AI assistance for this contribution
• I did use AI assistance (describe below)

AI assistance (an AI coding agent) was used for the initial code review that surfaced the issue, and to help draft the implementation, tests, and documentation wording. All changes were reviewed and verified by me (red→green tests, full suite, ruff) before submitting.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Tightens workflow validation so requires: only accepts known keys and explicitly rejects requires.permissions to avoid implying a non-existent runtime permission gate.

Changes:

• Add validation for requires type and allowed keys; reject requires.permissions with a clear error.
• Add tests covering valid/invalid requires cases (unknown keys, non-mapping, permissions).
• Update docs to clarify shell runs with user privileges and requires is advisory.

Show a summary per file

File	Description
workflows/PUBLISHING.md	Documents shell privilege model and that requires is advisory (no permissions gate).
tests/test_workflows.py	Adds tests for requires validation behavior (recognized keys, non-mapping, unknown key, permissions).
src/specify_cli/workflows/engine.py	Implements requires key/type validation and explicit rejection of requires.permissions.
docs/reference/workflows.md	Adds a security note about shell steps and (intended) advisory nature of requires.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

• Files reviewed: 4/4 changed files
• Comments generated: 4

[mnriem]

Please address Copilot feedback

[Copilot]

Copilot's findings

• Files reviewed: 4/4 changed files
• Comments generated: 3

[mnriem]

Please address Copilot feedback

[zied-jlassi]

Thanks @mnriem — addressed the Copilot feedback in the latest commit:

1. Truthiness vs None (engine.py) — validation now guards on if definition.requires is not None: instead of truthiness, so a falsy-but-non-mapping value (requires: [] / requires: '') is reported instead of silently skipped; a bare requires: (YAML null) is still treated as omitted. Added a regression test (test_requires_empty_sequence_is_rejected_as_non_mapping).
2. Docs example (workflows.md) — reworded the security note so requires.permissions is presented as rejected/unsupported rather than as a valid example of requires.
3. Spelling — standardised on US spelling to match the surrounding code (_RECOGNIZED_REQUIRES_KEYS, "recognized" in messages/comments).
4. Test assertion — the permissions-rejection test now asserts on specific markers (requires.permissions + the gate guidance) instead of the permissive "permissions" + "not".

Validation: tests/test_workflows.py 292 passed (the 5 requires tests included). No new ruff findings on src/. Scope unchanged — still validation + honest docs, no runtime gate.

[Copilot]

Copilot's findings

• Files reviewed: 4/4 changed files
• Comments generated: 1

[mnriem]

The core fix is solid — validating requires keys and rejecting requires.permissions with a pointer to a gate step is a real improvement, and the tests cover it well.

One change needed before this lands: drop tools and mcp from the recognized set. They're out of scope for this PR, and the justification doesn't hold for workflows:

• PUBLISHING.md (L59–62) and the workflow docs only ever document speckit_version and integrations. This PR's own PUBLISHING.md edit is what introduces the "recognised keys: …, tools, mcp" claim.
• requires.tools exists only in a different schema — the integration descriptor in integrations/catalog.py (~L709), not workflow requires.
• requires.mcp doesn't appear anywhere as a requires key (the only mcp hits are an unrelated cursor-agent --approve-mcps flag). Nothing resolves it for workflows or integrations.

So for workflows, tools/mcp have no docs (pre-PR), no schema, and no consumer. Whitelisting them undercuts the PR's own thesis: an author could write requires.tools:, pass validation, and have nothing read or enforce it — the same false-affordance trap you're closing for permissions.

Please:

1. Set _RECOGNIZED_REQUIRES_KEYS = {"speckit_version", "integrations"}.
2. Remove the tools/mcp additions from the PUBLISHING.md line.
3. Update the code comment so it no longer claims tools/mcp are "resolved by the bundler" for workflows.

Expanding the recognized requires surface is a separate decision and shouldn't ride along with this fix. If there's a future need for tools/mcp in workflow requires, that should go through its own issue/PR with docs and a real consumer.