Function-calling - enforcement guard (Phase 1)

[lchoquel]

Phase 1 — keyword-only-arguments enforcement guard

First phase of the keyword-only-arguments refactor (plan + tracker in TODOS.md). This PR is purely additive — a new dev CLI guard plus its wiring, no runtime behavior change — so it can merge ahead of the burn-down and start enforcing the convention on new code immediately.

What it does

check-keyword-only (a pipelex-dev AST command) enforces that non-subject function parameters across pipelex/ source are keyword-only, so call sites read do_thing(retries=3, timeout=30) instead of do_thing(3, 30). Only the subject (first param) may be positional — and that is a permission, not a requirement; all-keyword signatures are always fine.

It ships red-to-green: existing violations are recorded in a baseline (wip/keyword-only-args/violations-baseline.txt, keyed on relpath::qualified_name), and the guard fails only on NEW, non-baselined violations. The backlog is burned down package-by-package in later PRs (waves in TODOS.md).

Wired into both make agent-check (fast everyday gate) and make check (+ CI).

Carve-outs & exceptions

• Skipped entirely: dunders, pydantic validators/serializers, framework entrypoints (Typer/Temporal/pytest, incl. Typer call-style Annotated detection), and @override (sound because pyproject enforces reportImplicitOverride + reportIncompatibleMethodOverride).
• Exception 1: the subject param may stay positional.
• Exception 2: a short, explicit symmetric-tuple allowlist (set_env, unified_diff, diff_files, diff_dirs).
• Inline # kw-only: ignore escape hatch.

Verification

• make agent-check: pyright 0 errors, mypy clean, guard passes against baseline
• make agent-test: full suite green
• guard unit tests: all green

See wip/keyword-only-args/convention.md for the full spec and state.md for the cold-start log.

🤖 Generated with Claude Code

---

Summary by cubic

Add AST guard check-keyword-only to enforce keyword-only arguments across pipelex/ without changing runtime behavior. CI fails only on new violations, using a committed baseline to ship red-to-green.

• New Features

  • New dev CLI command check-keyword-only to enforce that non-subject params are keyword-only.
  • Wired into make check and make agent-check, with Make targets check-keyword-only/cko.
  • Baseline at wip/keyword-only-args/violations-baseline.txt; guard fails only on non-baselined violations. Key is relpath::qualified_name (signature-agnostic) to avoid penalizing partial improvements.
  • Added unit tests and docs: wip/keyword-only-args/convention.md (example fixed), state.md, inventory.json; TODOS.md is the tracker.

• Rules & Exceptions

  • Rule: subject may be positional-or-keyword; all other params must be after a bare *. All-keyword is fine.
  • Skipped: dunders, pydantic validators/serializers, framework entrypoints (Typer/Temporal/pytest), incl. bare @fixture and bare Typer Argument/Option, and @override.
  • Allowlist for symmetric tuples (e.g., set_env, unified_diff, diff_files, diff_dirs).
  • Escape hatch: inline # kw-only: ignore.

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

[greptile-apps]

Greptile Summary

This PR adds a keyword-only argument guard for Pipelex source. The main changes are:

• New pipelex-dev check-keyword-only AST command with baseline support.
• Makefile wiring into check, agent-check, and a cko shortcut.
• Carve-outs for framework entrypoints, overrides, dunders, pydantic hooks, and explicit symmetric helpers.
• Unit tests and rollout docs for the convention and burn-down plan.

Confidence Score: 5/5

This looks safe to merge.

• No blocking issues found in the changed code.

Important Files Changed

Filename	Overview
pipelex/cli/dev_cli/commands/check_keyword_only_cmd.py	Adds the AST-based keyword-only guard and latest carve-out handling for bare fixture and Typer annotation forms.
tests/unit/pipelex/cli/dev/test_check_keyword_only_cmd.py	Covers the guard behavior, including the latest bare fixture and bare Typer annotation cases.
wip/keyword-only-args/convention.md	Documents the enforced convention, rollout model, carve-outs, and known baseline limitation.

_{Reviews (2): Last reviewed commit: "refactor(dev): address PR review on keyw..." | Re-trigger Greptile}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d18a63fc45

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

4 issues found across 10 files

<sub>Tip: cubic can generate docs of your entire codebase and keep them up to date. Try it here.

Re-trigger cubic</sub>