feat: validate with signatures — PipeSignature contract-only pipes + --allow-signatures

[lchoquel]

Summary

Adds PipeSignature — contract-only pipes for top-down pipeline design — and strict signature validation, and merges the latest dev into the branch.

• PipeSignature pipe type (type = "PipeSignature"): declares a pipe's inputs, output, and description without an implementation, so an author or agent can sketch a complete pipeline before committing to the operator that will do the work. Slots into PipeBlueprintUnion/PipeSpecUnion, produced by PipeSignatureFactory, with its own runtime in pipelex/pipe_signature/. Dry-run mints a mock Stuff matching the declared output; live-run raises PipeSignatureNotExecutableError.
• --allow-signatures flag on pipelex validate pipe/bundle and every pipelex-agent validate subcommand (default off). Without it, strict validation refuses any pipeline whose dependency graph reaches a signature, raising SignaturesNotAllowedError and reporting every reachable signature plus the controller chain (signature_refs, dep_paths).
• Graph walk (collect_signature_refs() / collect_signature_paths() in pipelex/pipe_signature/signature_walk.py) powers the strict-mode pre-check in dry_run_pipe/dry_run_pipes and validate_bundle.
• dry_run_pipe, dry_run_pipes, validate_bundle, validate_bundles_from_directory now accept allow_signatures: bool = False; ValidateBundleError gained signature_check_error: SignaturesNotAllowedError | None so the CLI renders the dep chain.

Merge of dev

This branch had diverged structurally from dev's validation/error-handling refactor (#943/#948/#949). The merge was resolved semantically:

• Adopted dev's _translate_to_validate_bundle_error context manager + library-lifecycle teardown, and re-applied the signature feature on top (re-enabled dry-run, threaded allow_signatures, single SignaturesNotAllowedError arm shared by all entry points).
• Honored dev's class-location convention: ValidateBundleError lives in pipelex/pipeline/exceptions.py, extended there with the signature fields.
• Combined both [Unreleased] CHANGELOG sections.

Verification

• make agent-check — pyright 0 errors / 0 warnings, mypy clean.
• make tb (boot/config) green.
• Signature/validate targeted tests green; make agent-test (full offline suite) passing.

🤖 Generated with Claude Code

---

Summary by cubic

Adds PipeSignature for contract-only pipes and makes validation strict by default across pipelex and pipelex-agent; pass --allow-signatures to dry-run with mocked outputs. Bumps pipelex to 0.31.0.

• New Features

  • PipeSignature: declares inputs/output; dry-run returns a mock (multiplicity supported); live-run raises PipeSignatureNotExecutableError.
  • --allow-signatures on pipelex validate and all pipelex-agent validate commands; summaries note signature count in lenient mode.
  • Strict pre-check walks dependencies to find reachable signatures (signature_walk); validation APIs accept allow_signatures; ValidateBundleError carries signature_check_error; CLI renders friendly messages.

• Migration

  • Validation is strict by default; pipelines that reach a PipeSignature fail unless you pass --allow-signatures. Live execution of a signature always fails.
  • validate bundle --pipe now dry-runs only the requested slice, so unrelated signatures elsewhere don’t block it.
  • This branch uses a branch-local .mthds schema that includes PipeSignature; the Makefile generates the schema before running plxt lint and merge checks.

^{Written for commit 58ca53b. Summary will update on new commits.}

[greptile-apps]

Greptile Summary

This PR adds contract-only signature pipes and validation controls for them. The main changes are:

• New PipeSignature spec, blueprint, factory, and runtime.
• Strict signature detection through dependency graph walking.
• --allow-signatures flags for validation commands.
• Dry-run support that mocks signature outputs in lenient mode.
• Docs and tests covering signature validation behavior.

Confidence Score: 3/5

This should be fixed before merging.

• Strict bundle validation can reject valid bundles that contain unrelated signature stubs.
• Agent validate bundle --pipe can fail before checking the selected pipe.
• Main validate method has no way to use the new lenient signature mode.

pipelex/pipe_run/dry_run.py, pipelex/cli/agent_cli/commands/validate/_validate_core.py, and pipelex/cli/commands/validate/method_cmd.py need follow-up.

Important Files Changed

Filename	Overview
pipelex/pipe_run/dry_run.py	Adds strict signature pre-checks, but batch validation treats standalone signatures as blockers.
pipelex/cli/agent_cli/commands/validate/_validate_core.py	Threads allow_signatures through agent validation, but selected-pipe bundle validation still runs whole-bundle strict checks first.
pipelex/cli/commands/validate/method_cmd.py	Main method validation was not updated with the new --allow-signatures option.

Prompt To Fix All With AI

Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 2
pipelex/pipe_run/dry_run.py:149-154
**Unreached signatures fail bundles**

`dry_run_pipes` raises whenever any pipe in the batch is a `PipeSignature`, even when no non-signature pipe depends on it. `validate_bundle` passes every loaded pipe from the bundle into this function, so a bundle with a complete `main_pipe` plus an unrelated draft signature fails strict validation. That contradicts the advertised contract that strict mode rejects pipelines whose dependency graph reaches a signature, while unreached signatures are allowed.

### Issue 2 of 2
pipelex/cli/agent_cli/commands/validate/_validate_core.py:164-168
**Selected pipe is blocked**

`validate_pipe_in_bundle_core` first calls `validate_bundle` in the same strict mode before it dry-runs the requested pipe. For `pipelex-agent validate bundle draft.mthds --pipe implemented_pipe`, an unrelated `PipeSignature` elsewhere in the bundle makes the preliminary bundle validation fail before the selected pipe is checked. This makes `--pipe` behave like whole-bundle validation for signatures instead of validating only the requested pipe.

_{Reviews (1): Last reviewed commit: "Merge branch 'dev' into feature/Validate..." | Re-trigger Greptile}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2d754e167d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[cubic-dev-ai]

5 issues found across 64 files

_{You’re at about 90% of the monthly reviewed-line limit. You may want to disable incremental reviews to conserve quota. Reviews will continue until that limit is exceeded. If you need help avoiding interruptions, please contact contact@cubic.dev.}

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>