Skip to content

Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.

fix: author the generate-projection-corpus entry in the agent-rules templates (#1171)

Louis Choquel3593c46ccc48
diff --git a/.github/workflows/lint-check.yml b/.github/workflows/lint-check.yml
index ad54db297..edc19967e 100644
--- a/.github/workflows/lint-check.yml
+++ b/.github/workflows/lint-check.yml
@@ -157,9 +157,11 @@ jobs:
# --------------------------------------------------------------------------
# 6. Drift contracts — single job, version-independent
-# ADVISORY: deliberately NOT in lint-all's `needs`, so an open contract is
-# visible on the PR but does not block merges. Promote it into lint-all's
-# `needs` once the current open-PR backlog has landed.
+# BLOCKING, but through the ruleset rather than through lint-all: `Lint
+# (drift-contracts)` is named as a required status check on both `dev` and
+# `main`, so an open contract already stops the merge. It stays out of
+# lint-all's `needs` so that it reports under its own name — do not "promote"
+# it there expecting that to change what blocks.
# --------------------------------------------------------------------------
lint-drift:
name: Lint (drift-contracts)
@@ -183,12 +185,40 @@ jobs:
run: make drift-check
# --------------------------------------------------------------------------
-# 7. Aggregator job — the *single* required status check
+# 7. Agent rules sync — single job, version-independent
+# --------------------------------------------------------------------------
+ lint-agent-rules:
+ name: Lint (agent-rules)
+ runs-on: ubuntu-latest
+ env:
+ VIRTUAL_ENV: ${{ github.workspace }}/.venv
+
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Install uv (with cache)
+ uses: astral-sh/setup-uv@v7
+ with:
+ enable-cache: true
+ cache-dependency-glob: "uv.lock"
+
+ - name: Install dependencies
+ run: PYTHON_VERSION=3.11 TEST_PROFILE=ci make install
+
+ - name: Run agent rules sync check
+ run: make check-rules
+
+# --------------------------------------------------------------------------
+# 8. Aggregator job — the required status check that covers every lint job,
+# including the ones the rulesets do not name individually
+# (`Lint (hub layering)`, `Lint (agent-rules)`). It is not the only
+# required lint check: the rulesets name several of the jobs above by
+# name as well. Anything added to `needs` becomes blocking through here.
# --------------------------------------------------------------------------
lint-all:
name: Lint (all)
runs-on: ubuntu-latest
- needs: [lint-ruff-plxt, lint-typecheck, lint-config-sync, lint-keyword-only, lint-hub-layering]
+ needs: [lint-ruff-plxt, lint-typecheck, lint-config-sync, lint-keyword-only, lint-hub-layering, lint-agent-rules]
if: always()
steps:
@@ -198,7 +228,8 @@ jobs:
[ "${{ needs.lint-typecheck.result }}" != "success" ] || \
[ "${{ needs.lint-config-sync.result }}" != "success" ] || \
[ "${{ needs.lint-keyword-only.result }}" != "success" ] || \
- [ "${{ needs.lint-hub-layering.result }}" != "success" ]; then
+ [ "${{ needs.lint-hub-layering.result }}" != "success" ] || \
+ [ "${{ needs.lint-agent-rules.result }}" != "success" ]; then
echo "::error::At least one lint job failed."
exit 1
fi
diff --git a/.github/workflows/lint-fresh-check.yml b/.github/workflows/lint-fresh-check.yml
index dbf2bf314..eca40c29b 100644
--- a/.github/workflows/lint-fresh-check.yml
+++ b/.github/workflows/lint-fresh-check.yml
@@ -1,12 +1,15 @@
name: Lint fresh (pre-main gate)
-# Gate on PRs targeting main (the release PRs, dev -> main). The FULL lint suite
-# (the read-only equivalent of `make c`: ruff, plxt, config-sync, keyword-only,
-# drift, pyright, mypy) across every supported Python version, with NO mypy
-# cache. Feature PRs to dev run the same suite fast on py3.11 with a warm cache
-# (lint-check.yml); before anything reaches main it must also pass this clean,
-# all-versions, cache-free run — so incremental-mypy drift or a version-specific
-# break can never land on main.
+# Gate on PRs targeting main (the release PRs, dev -> main). Re-runs the
+# read-only lint suite across every supported Python version with NO mypy cache
+# — the step list below is the authority on which checks that is; do not restate
+# it here, an enumeration in a comment goes stale the next time a check is added.
+# Feature PRs to dev run it fast on py3.11 with a warm cache (lint-check.yml);
+# before anything reaches main it must also pass this clean, all-versions,
+# cache-free run, so incremental-mypy drift or a version-specific break can never
+# land on main. A version-independent check needs no place here to be enforced on
+# main: lint-check.yml runs on every pull request and its `Lint (all)` aggregate
+# is a required status check on `main` as well as on `dev`.
on:
pull_request:
diff --git a/AGENTS.md b/AGENTS.md
index 4fe056dae..62313f62d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -100,6 +100,12 @@
.venv/bin/pipelex-dev trace-input-semantics tests/data/input_semantics/probe_bundle.mthds -o /tmp/probe-trace
```
+ - **`generate-projection-corpus`**: Write the shared inputs-template projection fixture corpus — the descriptors, the expected fill-in templates in both shapes and both formats, and the record of where the expectation deliberately differs from the engine's own renderer. Sole producer of the capture committed byte-identically in `mthds-js/tests/fixtures/protocol/` and `mthds-python/tests/fixtures/protocol/`, which is what pins the TypeScript and Python projections against each other. See `docs/contribute/generate-projection-corpus.md`.
+
+ ```bash
+ .venv/bin/pipelex-dev generate-projection-corpus tests/data/input_semantics/*.mthds -o /tmp/projection-corpus
+ ```
+
### Pipelex CLI Commands
To run the Pipelex CLI commands without the logo, you can use the `--no-logo` flag, this will avoid useless tokens in the console output.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 572d4de6c..22b1a58bc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -21,6 +21,7 @@
- **`--help` works again on every `method` subcommand**: `pipelex validate method`, `pipelex run method`, the three `pipelex build ... method` commands and their agent-CLI twins all crashed with a rich `MarkupError` traceback instead of printing their help. The method-address example in each command's `NAME` argument help — `github.com/owner/repo[/name][@tag]` — reaches rich's markup parser through typer, which read `[/name]` as a closing tag with no opening one. The brackets are escaped at each of the sites, so the example renders as written and the help exits zero.
- **Class-backed concepts reflect field by field in the input-form descriptor**: a concept declaring `structure = "SomeClass"` used to collapse to `kind: "unknown"` the moment one field annotation could not be mapped, taking every sibling field with it — and a nested non-native pydantic model was reported as an opaque payload rather than walked into. Every `document` and `image` position beneath such a concept disappeared from the descriptor, so a consumer preparing inputs from it passed a local file path at one of those positions through un-uploaded and the run failed on the unresolved path. Reflection is now partial: each annotation is mapped on its own, an unmappable one is `unknown` at that field alone, a nested model is an `object` the reflection walks into, a `list[X]` reports its element node, and a class that holds itself is cut at the revisit instead of recursing. A `RootModel` is reported as its root annotation's node wherever it appears — as a field of a reflected class, and as the registered class backing the concept itself — because the value it accepts is the root value, so the descriptor no longer states an object over a synthetic `root` key that contradicts the `json_schema` derived beside it. The native consistency probe keeps its faithful-or-absent rule — it is compared against a normative pinned blueprint, where a plausible-looking partial answer would be the failure — and the two reflections now share one annotation vocabulary (`pipelex/core/concepts/annotation_shapes.py`) instead of one calling the other. See [Input-Form Descriptor](under-the-hood/input-form-descriptor.md).
- **Generated-image storage key extension follows the actual mime type**: a generated image could be stored under a `.png` key while its bytes and reported `mime_type` were `image/jpeg`, because `GeneratedContentFactory` picked the key's extension from the *requested* image format while `mime_type` came from the provider's *actual* answer — and a provider may return a different format than requested. The factory now resolves the effective mime type once (provider-reported, then base64-extracted, then the requested format, then the `image/jpeg` default) and derives the storage-key extension from that same value, on every path (stored bytes and fetched remote content alike), so the key and the `mime_type` can no longer diverge and anything inferring a type from the extension sees the truth.
+- **The agent-rules templates carry the `generate-projection-corpus` entry, and the sync check now runs in CI**: the command's documentation was written straight into the generated repo-root `CLAUDE.md` instead of into the template it is generated from, so the installed rules and the kit disagreed and `make check-rules` — and with it the whole `make check` aggregate — was red on `dev` and on every branch cut from it. The entry now lives in `pipelex/kit/agent_rules/commands.md` and in its Codex twin `codex_commands.md`, which also gives `AGENTS.md` the command it was missing altogether. The check ran in no workflow, which is how a hand-edited generated file merged in the first place; it is now the `lint-agent-rules` job and part of the required `Lint (all)` aggregate, so an installed target that has drifted from its template fails the pull request.
## [v0.55.0] - 2026-08-29
diff --git a/pipelex/kit/agent_rules/codex_commands.md b/pipelex/kit/agent_rules/codex_commands.md
index 99259bc89..f90c971d5 100644
--- a/pipelex/kit/agent_rules/codex_commands.md
+++ b/pipelex/kit/agent_rules/codex_commands.md
@@ -98,6 +98,12 @@
.venv/bin/pipelex-dev trace-input-semantics tests/data/input_semantics/probe_bundle.mthds -o /tmp/probe-trace
```
+ - **`generate-projection-corpus`**: Write the shared inputs-template projection fixture corpus — the descriptors, the expected fill-in templates in both shapes and both formats, and the record of where the expectation deliberately differs from the engine's own renderer. Sole producer of the capture committed byte-identically in `mthds-js/tests/fixtures/protocol/` and `mthds-python/tests/fixtures/protocol/`, which is what pins the TypeScript and Python projections against each other. See `docs/contribute/generate-projection-corpus.md`.
+
+ ```bash
+ .venv/bin/pipelex-dev generate-projection-corpus tests/data/input_semantics/*.mthds -o /tmp/projection-corpus
+ ```
+
## Pipelex CLI Commands
To run the Pipelex CLI commands without the logo, you can use the `--no-logo` flag, this will avoid useless tokens in the console output.
diff --git a/pipelex/kit/agent_rules/commands.md b/pipelex/kit/agent_rules/commands.md
index dcac95f5a..938844dba 100644
--- a/pipelex/kit/agent_rules/commands.md
+++ b/pipelex/kit/agent_rules/commands.md
@@ -149,6 +149,12 @@
.venv/bin/pipelex-dev trace-input-semantics tests/data/input_semantics/probe_bundle.mthds -o /tmp/probe-trace
```
+ - **`generate-projection-corpus`**: Write the shared inputs-template projection fixture corpus — the descriptors, the expected fill-in templates in both shapes and both formats, and the record of where the expectation deliberately differs from the engine's own renderer. Sole producer of the capture committed byte-identically in `mthds-js/tests/fixtures/protocol/` and `mthds-python/tests/fixtures/protocol/`, which is what pins the TypeScript and Python projections against each other. See `docs/contribute/generate-projection-corpus.md`.
+
+ ```bash
+ .venv/bin/pipelex-dev generate-projection-corpus tests/data/input_semantics/*.mthds -o /tmp/projection-corpus
+ ```
+
- **`drift`**: Drift contracts — deterministic review obligations between code and docs, declared in the root `drift.toml` (see `docs/contribute/drift-contracts.md`). When `make drift-check` (part of `make agent-check`, `make check`, and CI) reports an open contract: run `make drift-plan` to see what changed and what to review, actually review the targets and fix what is stale, `git add` the trigger files (the digest reads the git index, not the working tree), then record the review with `make drift-ack CONTRACT=<id> RATIONALE="…"`. The rationale is the on-the-record review decision — write an honest sentence. There is no bypass flag; "reviewed, no doc change needed" is a legitimate rationale.
```bash