feat: PipeSignature validation

[lchoquel]

Summary

• Introduces PipeSignature, a contract-only pipe type that declares inputs/outputs without an implementation — letting bundles validate against signatures of pipes that live elsewhere.
• Adds strict and lenient validation modes: strict rejects any signature placeholder at run time; lenient accepts signatures and reports them in the validation summary.
• Wires PipeSignature end-to-end: builder spec, blueprint union, runtime hydration, dry-run handling, CLI commands (validate bundle, validate pipe), and the agent CLI.
• Branch-local MTHDS schema rule in .pipelex/plxt.toml points at derived/mthds_schema.json so .mthds files on this branch validate against the schema that knows about PipeSignature. Removed at merge time once vscode-pipelex ships the updated bundled schema (tracked in TODOS Phase 7.4).
• Docs: new docs/building-methods/pipes/signature-pipes.md, updated validate CLI page, mkdocs nav entry.
• Tests: unit + integration + e2e coverage for spec/blueprint union, runtime, dry-run strict mode, CLI summary, signature-only and mixed bundles.

Test plan

• make agent-check
• make agent-test
• Verify signature-only bundle validates in lenient mode and fails in strict mode
• Verify mixed bundle (signatures + real pipes) reports signature count in summary
• Spot-check generated docs page renders in mkdocs

🤖 Generated with Claude Code

---

Summary by cubic

Adds PipeSignature, a contract-only pipe for designing pipelines before implementation, with strict-by-default validation, lenient mode via --allow-signatures, dry-run mocks, and clearer CLI reporting. Also moves signature detection into pipelex/pipe_signature/signature_walk.py to avoid import cycles and keep PipeAbstract minimal.

• New Features

  • Builder/runtime split: PipeSignatureSpec added to PipeSpecUnion; runtime PipeSignature + PipeSignatureFactory/PipeSignatureBlueprint registered end-to-end (schema, unions, registries).
  • Validation: strict (default) rejects reachable signatures; lenient via --allow-signatures on pipelex and pipelex-agent for pipe/method/bundle. Lenient summaries append a signature count.
  • Dry-run mints mock outputs (honors multiplicity); live-run raises PipeSignatureNotExecutableError.
  • CLI: validate pipe|method|bundle accept --allow-signatures in both CLIs, with improved output. Branch-local .pipelex/plxt.toml points to derived/mthds_schema.json.
  • Docs: archived signature TDD plan synced with the signature_walk.py refactor.

• Bug Fixes

  • Reject signature_for=PipeSignature at both spec and blueprint layers.
  • SignaturesNotAllowedError aggregates all offending pipe refs; both single-pipe and bundle paths show a Rich-formatted “Unimplemented Signatures” section and exit cleanly.
  • Makefile: plxt-lint and merge-check-plxt-lint generate the MTHDS schema first to fix CI on clean checkouts.
  • Move signature-graph walk off PipeAbstract into pipelex/pipe_signature/signature_walk.py; update all call sites and tests.

^{Written for commit a10ba98. Summary will update on new commits. Review in cubic}

Documentation

Audited every docs file against the diff. Feature documentation was already thorough — the branch shipped a new page, nav entry, cross-links, and CLI reference. /document-release found one gap and fixed it:

• docs/tools/cli/agent-cli.md: added a "Signature pipes" note to the Validate section — pipelex-agent validate runs lenient validation by default (accepts PipeSignature placeholders, no flag to make it strict), unlike pipelex validate which is strict by default. This behavioral difference was undocumented.

Already in place on the branch, verified accurate:

• docs/building-methods/pipes/signature-pipes.md — new page: when to use, runtime behavior table, MTHDS parameters, examples (single contract, signature in a sequence, multiplicity), CLI usage, replacement workflow.
• docs/building-methods/pipes/index.md — paragraph introducing signature pipes as the third kind of pipe.
• docs/tools/cli/validate.md — --allow-signatures flag documented for both validate pipe and validate bundle, with examples.
• mkdocs.yml — nav + plugin entry for the new page.
• pipelex/builder/CLAUDE.md — pipe_signature.py → pipe_signature_spec.py rename reflected.
• CHANGELOG.md — [Unreleased] Added/Changed entries cover PipeSignature, --allow-signatures, the graph walk, and the threaded allow_signatures parameter.

Documentation coverage

entity              reference  how-to  tutorial  explanation
PipeSignature       ✅         ✅      ❌        ✅
--allow-signatures  ✅         ✅      ❌        ✅
agent CLI lenient   ✅         ❌      ❌        ✅

Common gap (not blocking): no step-by-step tutorial walkthrough for newcomers building their first signature-stubbed pipeline. The signature-pipes.md examples cover the how-to quadrant well; a guided tutorial could be added later via /document-generate if signature-first authoring becomes a promoted workflow.

No architecture diagrams reference signature internals — no diagram drift.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6f0c25e161

ℹ️ 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]

3 issues found across 54 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="pipelex/pipe_signature/pipe_signature_blueprint.py">

<violation number="1" location="pipelex/pipe_signature/pipe_signature_blueprint.py:19">
P2: `signature_for` is missing blueprint-level validation to reject `PipeType.PIPE_SIGNATURE`, so invalid bundles can bypass the spec guard.</violation>
</file>

<file name="pipelex/cli/agent_cli/commands/validate/_validate_core.py">

<violation number="1" location="pipelex/cli/agent_cli/commands/validate/_validate_core.py:47">
P1: Strict mode silently skips signature pipes instead of rejecting them, which can incorrectly report successful validation when placeholders are present.</violation>
</file>

<file name="pipelex/pipe_run/dry_run.py">

<violation number="1" location="pipelex/pipe_run/dry_run.py:148">
P2: The aggregated strict-mode error can report the wrong `pipe_ref` by always using `pipes[0]`, which may misidentify the offending pipe in the message.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[greptile-apps]

Greptile Summary

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

• New PipeSignature spec, blueprint, runtime, factory, schema, and registry support.
• Strict signature rejection by default during dry-run validation.
• --allow-signatures lenient mode for main CLI and agent CLI validation commands.
• Mock dry-run output for signatures and live-run rejection.
• Documentation, fixtures, and tests for signature-only and mixed bundles.

Confidence Score: 4/5

This is close, but the scoped agent validation path should be fixed before merging.

• Most signature handling is wired consistently through specs, blueprints, runtime, and CLI flags.

• The agent bundle --pipe path can reject a selected implemented pipe because it dry-runs unrelated bundle pipes first.

• The issue is contained to validation behavior, but it affects a documented command path for mixed draft bundles.

• pipelex/cli/agent_cli/commands/validate/_validate_core.py

Important Files Changed

Filename	Overview
pipelex/cli/agent_cli/commands/validate/_validate_core.py	Threads allow_signatures through agent validation, but the pipe-in-bundle path validates the whole bundle before the selected pipe.
pipelex/pipeline/validate_bundle.py	Restores bundle dry-run and wraps strict signature failures into ValidateBundleError.
pipelex/pipe_run/dry_run.py	Adds strict signature prechecks and lenient dry-run support for signature placeholders.

Prompt To Fix All With AI

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

---

### Issue 1 of 1
pipelex/cli/agent_cli/commands/validate/_validate_core.py:161-172
**Scoped validation dry-runs everything**

`validate_pipe_in_bundle_core` is meant to validate one selected pipe from a bundle, but it first calls `validate_bundle` with the same strict signature setting. This PR changed `validate_bundle` to dry-run every loaded pipe, so `pipelex-agent validate bundle draft.mthds --pipe real_pipe` can fail before reaching `real_pipe` when the bundle contains an unrelated `PipeSignature`. A user asking to validate an implemented pipe in a mixed draft bundle receives a strict-mode signature failure for pipes outside the requested scope.

_{Reviews (5): Last reviewed commit: "docs: Sync archived signature TDD plan w..." | Re-trigger Greptile}

[greptile-apps]

Scoped validation dry-runs everything

validate_pipe_in_bundle_core is meant to validate one selected pipe from a bundle, but it first calls validate_bundle with the same strict signature setting. This PR changed validate_bundle to dry-run every loaded pipe, so pipelex-agent validate bundle draft.mthds --pipe real_pipe can fail before reaching real_pipe when the bundle contains an unrelated PipeSignature. A user asking to validate an implemented pipe in a mixed draft bundle receives a strict-mode signature failure for pipes outside the requested scope.

Prompt To Fix With AI

This is a comment left during a code review.
Path: pipelex/cli/agent_cli/commands/validate/_validate_core.py
Line: 161-172

Comment:
**Scoped validation dry-runs everything**

`validate_pipe_in_bundle_core` is meant to validate one selected pipe from a bundle, but it first calls `validate_bundle` with the same strict signature setting. This PR changed `validate_bundle` to dry-run every loaded pipe, so `pipelex-agent validate bundle draft.mthds --pipe real_pipe` can fail before reaching `real_pipe` when the bundle contains an unrelated `PipeSignature`. A user asking to validate an implemented pipe in a mixed draft bundle receives a strict-mode signature failure for pipes outside the requested scope.

How can I resolve this? If you propose a fix, please make it concise.