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.

The Commands rules are a compact list: the generated CLAUDE.md costs a session a third of what it did (#1194)

Louis Choquelb481bd058b3e
diff --git a/.claude/settings.json b/.claude/settings.json
index 4dda9cc6f..5c08a5473 100644
--- a/.claude/settings.json
+++ b/.claude/settings.json
@@ -27,7 +27,31 @@
"Bash(make v)",
"Bash(make build)",
"Bash(make ukc)",
- "Bash(make docs-check)"
+ "Bash(make docs-check)",
+ "Bash(make t TEST=:*)",
+ "Bash(make agent-test-debug)",
+ "Bash(make atd)",
+ "Bash(make test-ts-gates)",
+ "Bash(make ttg)",
+ "Bash(make check-keyword-only)",
+ "Bash(make cko)",
+ "Bash(make fix-keyword-only)",
+ "Bash(make fko)",
+ "Bash(make subject-grant:*)",
+ "Bash(make sgr:*)",
+ "Bash(make check-ledger)",
+ "Bash(make cl)",
+ "Bash(make drift-check)",
+ "Bash(make drift-plan)",
+ "Bash(make drift-ack:*)",
+ "Bash(make rules)",
+ "Bash(make check-rules)",
+ "Bash(make generate-mthds-schema)",
+ "Bash(make gms)",
+ "Bash(make generate-error-pages)",
+ "Bash(make gep)",
+ "Bash(make generate-error-identity)",
+ "Bash(make gei)"
]
},
"hooks": {
@@ -54,4 +78,4 @@
}
]
}
-}
\ No newline at end of file
+}
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b703fc093..abcc9da46 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,8 @@
### Changed
+- **The Commands section of the agent rules is a compact list, so the generated `CLAUDE.md` costs every session a third of what it did.** `pipelex/kit/agent_rules/commands.md` drops its long-form headings and code blocks for one bullet per gate, each naming the target, its alias, when to run it and where the full rationale lives; `make rules` regenerates `CLAUDE.md` from it. It also now says the one thing a session could not learn from the file itself: that `CLAUDE.md` and `AGENTS.md` are generated, that `make rules` is how they move, and that `make check-rules` is a CI gate `make agent-check` does not run. The repo's Claude Code permission allowlist pre-approves the targets the rules recommend (`atd`, `ttg`, `cko`, `sgr`, the drift and rules targets, the generator aliases), so following the rules does not prompt.
+
- **The MTHDS standard version this runtime implements is now `2.0.0` (breaking):** `mthds` moves to `==0.14.0`, whose `MTHDS_STANDARD_VERSION` was cut from `1.0.0` to `2.0.0` — the standard's first cut under its own versioning rule, accounting for breaking changes to the native set and to the manifest, lock and resolution rules that had already shipped unversioned. Two things follow for users, and no pipelex line caused either: every normalized crate this engine emits is stamped `2.0.0` instead of `1.0.0` (crate fingerprints are unaffected — `mthds_version` is excluded from the hashed payload by design), and a `METHODS.toml` whose `mthds_version` pinned the old major, such as `^1.0.0`, now warns where it did not before. A plain floor like `>=1.0.0` is still satisfied. The protocol version is unchanged at `0.6.0`. The pin stays exact, so everyone downstream inherits `mthds==0.14.0`; a consumer depending on `mthds` directly must move in step.
### Fixed
diff --git a/CLAUDE.md b/CLAUDE.md
index c9514ec5c..e32296030 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -2,184 +2,16 @@
## Commands
-### Linting
-
- After making code changes, you must always lint using `make agent-check`.
-
- ```bash
- make agent-check
- # If the current system doesn't have the `make` command,
- # lookup the "agent-check" target in the Makefile and run the commands one by one (targets fix-unused-imports fix-keyword-only format lint pyright mypy check-ledger check-keyword-only check-hub-layering drift-check)
- ```
-
- This runs multiple code quality tools:
- - Pyright: Static type checking
- - Ruff: Fix unused imports, lint, format
- - Mypy: Static type checker
- - plxt: Format and lint TOML, MTHDS, and PLX files
- - Migration ledgers: every checked-in ledger must be legal and replay harmlessly over its reference documents (`make check-ledger`, alias `cl`)
- - Drift contracts: open code↔docs review obligations fail the gate (note the digest reads the git index, so stage your changes for the check to see them; resolve with the drift workflow below)
-
- Always fix any issues reported by these tools before proceeding.
-
-### Keyword-only arguments check
-
- Non-subject function parameters across `pipelex/` source must be keyword-only, and a positional subject is legal only under a grant recorded in `subject_grants.toml`. The convention is mechanically enforced and already runs as part of `make agent-check`, but you can invoke it on its own:
-
- ```bash
- make check-keyword-only # alias: make cko — read-only gate; hard-blocks on any violation
- make fix-keyword-only # alias: make fko — auto-insert a bare * for mechanically-fixable violations
- make subject-grant FUNC="<path>::<qualname>" RATIONALE="…" # alias: make sgr — grant a positional subject
- ```
-
- `check-keyword-only` owns the pass/fail gate; `fix-keyword-only` rewrites what it can (including ungranted subjects — grant BEFORE running checks if the subject should stay positional) and reports the shapes it can't fix mechanically (resolve those by hand). See [`docs/contribute/keyword-only-arguments.md`](docs/contribute/keyword-only-arguments.md) for the full convention.
-
-### Cleaning Derived Files
-
- If you need to clean derived files and caches, typically after you erased files or moved tests, the linters can get confused, the pytest collection can be off...
-
- ```bash
- make cleanderived
- ```
-
-### Running Tests
-
- `make agent-test` runs the test suite and is **critical at the end of a coding session** to verify everything is good before wrapping up.
-
- At intermediate steps during LOCAL development, it's OK to run only the tests relevant to your changes — either by calling pytest directly from the `.venv` (e.g. `.venv/bin/pytest -x -q tests/unit/path/to/test_module.py`) or using `make t TEST=TestClassName`. This applies only to local setups, not cloud agents.
-
- ```bash
- make agent-test
- # If the current system doesn't have the `make` command, lookup the "agent-test" target in the Makefile and run the command manually.
- # Heartbeat progress lines while running; full output only on failure.
- ```
-
-### When `make agent-test` hangs or fails opaquely
-
- Use **`make agent-test-debug`** (alias: `make atd`). Same suite, but with stale-process cleanup upfront, an outer wall-clock `timeout` so fixture-teardown hangs and xdist worker-replace loops can't run forever, direct file redirect for live progress (`tail -f /tmp/pytest-agent-test-debug.log`), and `-v` so each test name lands in the log as it runs. On failure it prints the failed tests, the log path, and a grep hint; on timeout, the tail of the log and the log path.
-
- For the full debugging methodology — clean-state protocol, when to bail to the user, how to grep failures by error class name, when xdist failures are flakes vs real bugs — see [`docs/agents/debugging-hanging-pytest-runs.md`](docs/agents/debugging-hanging-pytest-runs.md).
-
-#### Changing a codegen emitter: `make test-ts-gates`
-
- ⚠ **`make agent-test` does not cover the TypeScript emission.** The two tests that read the emitted TypeScript *as TypeScript* — `prettier --check` over it, and running the emitted schema under a real zod — need a node toolchain, so in an ordinary run they skip and the suite still reports green. Everything else about the ts-zod target is measured structurally (line width, trailing whitespace, blank-line runs, unterminated literals), which is blind to a wrong quote style or a member chain broken where prettier would not break it.
-
- So after touching anything under `pipelex/codegen/emitters/`, run:
-
- ```bash
- make test-ts-gates # alias: make ttg
- ```
-
- It provisions a pinned prettier and zod into the gitignored `.ts-toolchain/` (needs npm and node >= 22.6), then runs the codegen suite with `PIPELEX_REQUIRE_TS_GATES=1`, under which those two gates **fail** instead of skipping. CI runs the same target as the `Tests (ts emission gates)` job, so skipping it locally means finding out on the pull request. Moving the pinned prettier version is an emitter change rather than a dependency bump — the emitter models that formatter's exact behaviour. Full rationale in [`docs/contribute/typescript-emission-gates.md`](docs/contribute/typescript-emission-gates.md).
-
-### Running Tests with Prints
-
- > **LOCAL ONLY**: The commands below are meant for a human developer running on their local machine. If you are an AI agent (Claude Code, Cursor, Codex, or any other agent running in the cloud or in a sandboxed environment), **do NOT use these commands**. Use `make agent-test` instead.
-
- If anything went wrong, you can run the tests with prints to see the error:
-
- ```bash
- make test-with-prints
- # If the current system doesn't have the `make` command, lookup the "test-with-prints" target in the Makefile and run the command manually.
- ```
-
-### Running specific Tests
-
- > **LOCAL ONLY**: The commands below are meant for a human developer running on their local machine. If you are an AI agent (Claude Code, Cursor, Codex, or any other agent running in the cloud or in a sandboxed environment), **do NOT use these commands**. Use `make agent-test` instead.
-
- ```bash
- make tp TEST=TestClassName
- # or
- make tp TEST=test_function_name
- ```
- Note: Matches names containing the provided string (pytest `-k` substring matching).
-
-### Running Last Failed Tests
-
- > **LOCAL ONLY**: The commands below are meant for a human developer running on their local machine. If you are an AI agent (Claude Code, Cursor, Codex, or any other agent running in the cloud or in a sandboxed environment), **do NOT use these commands**. Use `make agent-test` instead.
-
- To rerun only the tests that failed in the previous run, use:
-
- ```bash
- make tp TEST=LF
- # or with any test target
- make test TEST=LF
- make t TEST=LF
- ```
- Note: `TEST=LF` (or `TEST=lf`) will use pytest's `--lf` flag instead of name filtering.
-
-### Prerequisites for running command lines: use virtual environment
-
- **CRITICAL**: Before running any `pipelex` commands or `pytest`, you MUST use the appropriate Python virtual environment. The only exceptions are our `make` commands which already include the env activation.
-
- Call the CLI directly from the virtual environment:
-
- ```bash
- .venv/bin/pytest -s -v -k test_render_jinja2_from_text
- .venv/bin/pipelex validate --all
- ```
-
- For standard installations, the virtual environment is named `.venv`. Always check this first. On Windows, the path is `.venv\Scripts\` instead of `.venv/bin/`.
-
-### Pipelex Dev CLI (`pipelex-dev`)
-
- The `pipelex-dev` CLI provides internal development tools that are not distributed with the package. It is available in the virtual environment.
-
- ```bash
- .venv/bin/pipelex-dev --help
- ```
-
- Key commands:
-
- - **`generate-mthds-schema`**: Regenerate the MTHDS JSON Schema (`derived/mthds_schema.json`). Run this after modifying `mthds_schema_generator.py`.
-
- ```bash
- .venv/bin/pipelex-dev generate-mthds-schema
- ```
-
- - **`generate-error-pages`**: Regenerate the per-class error reference pages under `docs/errors/` — one Markdown page per `PipelexError` subclass, which is what each error's `type_uri` dereferences to. Run after adding or renaming an error class. Pages a maintainer claims with a `<!-- pipelex:authored -->` marker are preserved across runs. Also available as `make generate-error-pages` (alias `make gep`).
-
- ```bash
- .venv/bin/pipelex-dev generate-error-pages
- ```
-
- - **`generate-error-identity`**: Regenerate the committed `(error_type, title, type_uri)` snapshot of every `PipelexError` subclass at `tests/data/errors/error_identity.txt`. `error_type` is the bare class name and consumers outside this repo branch on it, so a rename is a silent wire break — the snapshot turns it into a reviewable diff, gated by `tests/unit/pipelex/errors/test_error_identity_snapshot.py`. Run after adding, renaming or removing an error class. Also available as `make generate-error-identity` (alias `make gei`).
-
- ```bash
- .venv/bin/pipelex-dev generate-error-identity
- ```
-
- - **`refresh-graph-ui-sri`**: Refetch the pinned graph viewer assets from jsDelivr (`@pipelex/mthds-ui` standalone JS+CSS, `elkjs`) and rewrite `pipelex/graph/reactflow/standalone_assets.py` with new `sha384` Subresource Integrity hashes. Use when bumping the pinned mthds-ui or elkjs version.
-
- ```bash
- .venv/bin/pipelex-dev refresh-graph-ui-sri --mthds-ui-version 0.6.3
- # or rotate elkjs alongside:
- .venv/bin/pipelex-dev refresh-graph-ui-sri --mthds-ui-version 0.6.3 --elkjs-version 0.11.1
- ```
-
- - **`trace-input-semantics`**: Capture harness for the input-schema emission chain — given one or more `.mthds` bundles, dumps one artifact per hop (parse blueprint, generated class source, raw pydantic schema, SCHEMA render, wire contract) plus a manifest of each pipe input's wire framing, so a lost or mangled authored fact is localized to exactly one hop. Use when changing the structure blueprint, the structure generator, the schema render, or the contract builder. See `docs/contribute/trace-input-semantics.md`.
-
- ```bash
- .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/hinted_bundle.mthds \
- tests/data/input_semantics/probe_bundle.mthds \
- tests/data/input_semantics/scaffold_bundle.mthds \
- tests/data/input_semantics/output_bundle.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
- make drift-plan
- make drift-ack CONTRACT=config-docs RATIONALE="Documented the new setting; other config pages unaffected."
- ```
+`make` targets activate the virtual environment themselves; anything else (`pytest`, `pipelex`, `pipelex-dev`) runs from `.venv/bin/` (`.venv\Scripts\` on Windows), never bare. The Makefile is the reference for every target and alias; without `make`, read the target there and run its prerequisites one by one.
+
+- **`make agent-check` after every code change, and fix everything it reports.** Its prerequisites are `fix-unused-imports fix-keyword-only format lint pyright mypy check-ledger check-keyword-only check-hub-layering drift-check`: the import and keyword-only fixers, ruff, pyright, mypy, `plxt` over TOML/MTHDS/PLX, the migration-ledger replay (`cl`), the hub-layering check and the drift contracts. The drift digest reads the git index, so stage your changes before the check.
+- **Keyword-only arguments** (the convention is in the standards and in `docs/contribute/keyword-only-arguments.md`): `make check-keyword-only` (`cko`) is the gate, `make fix-keyword-only` (`fko`) inserts the bare `*` where it can — on ungranted subjects too — and reports the shapes it cannot fix, and `make subject-grant FUNC="<path>::<qualname>" RATIONALE="…"` (`sgr`) grants a positional subject. Grant before `make agent-check`, which runs the fixer.
+- **Drift contracts.** When `make drift-check` reports an open contract: `make drift-plan`, review and fix the stale targets, `git add` the trigger files, then `make drift-ack CONTRACT=<id> RATIONALE="…"`. No bypass flag; "reviewed, no doc change needed" is a legitimate rationale. See `docs/contribute/drift-contracts.md`.
+- **`make agent-test` at the end of every coding session.** Heartbeat lines while running, full output only on failure. If it hangs or fails opaquely, `make agent-test-debug` (`atd`) adds stale-process cleanup, an outer timeout and a live log; the methodology is `docs/agents/debugging-hanging-pytest-runs.md`. At intermediate steps in a local setup, running only the relevant tests is fine: `.venv/bin/pytest -x -q tests/unit/path/to/test_module.py`, or `make t TEST=<name>` (pytest `-k` substring matching; `TEST=LF` reruns the last failures). `make tp` / `make test-with-prints` are for a human at a terminal; an agent in the cloud or in a sandbox uses `make agent-test` only.
+- **`make test-ts-gates` (`ttg`) after touching anything under `pipelex/codegen/emitters/`, or moving the pinned prettier version.** `make agent-test` does not cover the TypeScript emission: the two gates that read the emitted TypeScript as TypeScript need a node toolchain and skip silently without one. This target provisions a pinned prettier and zod into `.ts-toolchain/` (npm, node >= 22.6) and makes those gates fail instead of skip, as CI does. See `docs/contribute/typescript-emission-gates.md`.
+- **`make cleanderived`** when linters or pytest collection get confused after files were erased or moved.
+- **`CLAUDE.md` and `AGENTS.md` are generated.** Edit the sources in `pipelex/kit/agent_rules/` (assembled per `pipelex/kit/index.toml`) and run `make rules`; `make check-rules` is the CI gate, and `make agent-check` does not include it.
+- **`pipelex-dev`** (`.venv/bin/pipelex-dev --help`) holds the internal generators, most with a `make` alias. `generate-mthds-schema` (`gms`) after modifying `mthds_schema_generator.py`. `generate-error-pages` (`gep`) and `generate-error-identity` (`gei`) after adding, renaming or removing an error class: consumers outside this repo branch on `error_type`, so a rename is a silent wire break that the committed snapshot turns into a reviewable diff. `refresh-graph-ui-sri --mthds-ui-version <v> [--elkjs-version <v>]` when bumping the pinned mthds-ui or elkjs. `trace-input-semantics` when changing the structure blueprint, the structure generator, the schema render or the contract builder (`docs/contribute/trace-input-semantics.md`). `generate-projection-corpus` to rewrite the fixture corpus committed byte-identically in `mthds-js` and `mthds-python` (`docs/contribute/generate-projection-corpus.md`). `drift` carries the drift-contract commands above.
## Standards related to developing the Pipelex codebase
diff --git a/pipelex/kit/agent_rules/commands.md b/pipelex/kit/agent_rules/commands.md
index 2385c0223..c9670cb09 100644
--- a/pipelex/kit/agent_rules/commands.md
+++ b/pipelex/kit/agent_rules/commands.md
@@ -1,180 +1,12 @@
# Commands
-## Linting
-
- After making code changes, you must always lint using `make agent-check`.
-
- ```bash
- make agent-check
- # If the current system doesn't have the `make` command,
- # lookup the "agent-check" target in the Makefile and run the commands one by one (targets fix-unused-imports fix-keyword-only format lint pyright mypy check-ledger check-keyword-only check-hub-layering drift-check)
- ```
-
- This runs multiple code quality tools:
- - Pyright: Static type checking
- - Ruff: Fix unused imports, lint, format
- - Mypy: Static type checker
- - plxt: Format and lint TOML, MTHDS, and PLX files
- - Migration ledgers: every checked-in ledger must be legal and replay harmlessly over its reference documents (`make check-ledger`, alias `cl`)
- - Drift contracts: open code↔docs review obligations fail the gate (note the digest reads the git index, so stage your changes for the check to see them; resolve with the drift workflow below)
-
- Always fix any issues reported by these tools before proceeding.
-
-## Keyword-only arguments check
-
- Non-subject function parameters across `pipelex/` source must be keyword-only, and a positional subject is legal only under a grant recorded in `subject_grants.toml`. The convention is mechanically enforced and already runs as part of `make agent-check`, but you can invoke it on its own:
-
- ```bash
- make check-keyword-only # alias: make cko — read-only gate; hard-blocks on any violation
- make fix-keyword-only # alias: make fko — auto-insert a bare * for mechanically-fixable violations
- make subject-grant FUNC="<path>::<qualname>" RATIONALE="…" # alias: make sgr — grant a positional subject
- ```
-
- `check-keyword-only` owns the pass/fail gate; `fix-keyword-only` rewrites what it can (including ungranted subjects — grant BEFORE running checks if the subject should stay positional) and reports the shapes it can't fix mechanically (resolve those by hand). See [`docs/contribute/keyword-only-arguments.md`](docs/contribute/keyword-only-arguments.md) for the full convention.
-
-## Cleaning Derived Files
-
- If you need to clean derived files and caches, typically after you erased files or moved tests, the linters can get confused, the pytest collection can be off...
-
- ```bash
- make cleanderived
- ```
-
-## Running Tests
-
- `make agent-test` runs the test suite and is **critical at the end of a coding session** to verify everything is good before wrapping up.
-
- At intermediate steps during LOCAL development, it's OK to run only the tests relevant to your changes — either by calling pytest directly from the `.venv` (e.g. `.venv/bin/pytest -x -q tests/unit/path/to/test_module.py`) or using `make t TEST=TestClassName`. This applies only to local setups, not cloud agents.
-
- ```bash
- make agent-test
- # If the current system doesn't have the `make` command, lookup the "agent-test" target in the Makefile and run the command manually.
- # Heartbeat progress lines while running; full output only on failure.
- ```
-
-## When `make agent-test` hangs or fails opaquely
-
- Use **`make agent-test-debug`** (alias: `make atd`). Same suite, but with stale-process cleanup upfront, an outer wall-clock `timeout` so fixture-teardown hangs and xdist worker-replace loops can't run forever, direct file redirect for live progress (`tail -f /tmp/pytest-agent-test-debug.log`), and `-v` so each test name lands in the log as it runs. On failure it prints the failed tests, the log path, and a grep hint; on timeout, the tail of the log and the log path.
-
- For the full debugging methodology — clean-state protocol, when to bail to the user, how to grep failures by error class name, when xdist failures are flakes vs real bugs — see [`docs/agents/debugging-hanging-pytest-runs.md`](docs/agents/debugging-hanging-pytest-runs.md).
-
-### Changing a codegen emitter: `make test-ts-gates`
-
- ⚠ **`make agent-test` does not cover the TypeScript emission.** The two tests that read the emitted TypeScript *as TypeScript* — `prettier --check` over it, and running the emitted schema under a real zod — need a node toolchain, so in an ordinary run they skip and the suite still reports green. Everything else about the ts-zod target is measured structurally (line width, trailing whitespace, blank-line runs, unterminated literals), which is blind to a wrong quote style or a member chain broken where prettier would not break it.
-
- So after touching anything under `pipelex/codegen/emitters/`, run:
-
- ```bash
- make test-ts-gates # alias: make ttg
- ```
-
- It provisions a pinned prettier and zod into the gitignored `.ts-toolchain/` (needs npm and node >= 22.6), then runs the codegen suite with `PIPELEX_REQUIRE_TS_GATES=1`, under which those two gates **fail** instead of skipping. CI runs the same target as the `Tests (ts emission gates)` job, so skipping it locally means finding out on the pull request. Moving the pinned prettier version is an emitter change rather than a dependency bump — the emitter models that formatter's exact behaviour. Full rationale in [`docs/contribute/typescript-emission-gates.md`](docs/contribute/typescript-emission-gates.md).
-
-## Running Tests with Prints
-
- > **LOCAL ONLY**: The commands below are meant for a human developer running on their local machine. If you are an AI agent (Claude Code, Cursor, Codex, or any other agent running in the cloud or in a sandboxed environment), **do NOT use these commands**. Use `make agent-test` instead.
-
- If anything went wrong, you can run the tests with prints to see the error:
-
- ```bash
- make test-with-prints
- # If the current system doesn't have the `make` command, lookup the "test-with-prints" target in the Makefile and run the command manually.
- ```
-
-## Running specific Tests
-
- > **LOCAL ONLY**: The commands below are meant for a human developer running on their local machine. If you are an AI agent (Claude Code, Cursor, Codex, or any other agent running in the cloud or in a sandboxed environment), **do NOT use these commands**. Use `make agent-test` instead.
-
- ```bash
- make tp TEST=TestClassName
- # or
- make tp TEST=test_function_name
- ```
- Note: Matches names containing the provided string (pytest `-k` substring matching).
-
-## Running Last Failed Tests
-
- > **LOCAL ONLY**: The commands below are meant for a human developer running on their local machine. If you are an AI agent (Claude Code, Cursor, Codex, or any other agent running in the cloud or in a sandboxed environment), **do NOT use these commands**. Use `make agent-test` instead.
-
- To rerun only the tests that failed in the previous run, use:
-
- ```bash
- make tp TEST=LF
- # or with any test target
- make test TEST=LF
- make t TEST=LF
- ```
- Note: `TEST=LF` (or `TEST=lf`) will use pytest's `--lf` flag instead of name filtering.
-
-## Prerequisites for running command lines: use virtual environment
-
- **CRITICAL**: Before running any `pipelex` commands or `pytest`, you MUST use the appropriate Python virtual environment. The only exceptions are our `make` commands which already include the env activation.
-
- Call the CLI directly from the virtual environment:
-
- ```bash
- .venv/bin/pytest -s -v -k test_render_jinja2_from_text
- .venv/bin/pipelex validate --all
- ```
-
- For standard installations, the virtual environment is named `.venv`. Always check this first. On Windows, the path is `.venv\Scripts\` instead of `.venv/bin/`.
-
-## Pipelex Dev CLI (`pipelex-dev`)
-
- The `pipelex-dev` CLI provides internal development tools that are not distributed with the package. It is available in the virtual environment.
-
- ```bash
- .venv/bin/pipelex-dev --help
- ```
-
- Key commands:
-
- - **`generate-mthds-schema`**: Regenerate the MTHDS JSON Schema (`derived/mthds_schema.json`). Run this after modifying `mthds_schema_generator.py`.
-
- ```bash
- .venv/bin/pipelex-dev generate-mthds-schema
- ```
-
- - **`generate-error-pages`**: Regenerate the per-class error reference pages under `docs/errors/` — one Markdown page per `PipelexError` subclass, which is what each error's `type_uri` dereferences to. Run after adding or renaming an error class. Pages a maintainer claims with a `<!-- pipelex:authored -->` marker are preserved across runs. Also available as `make generate-error-pages` (alias `make gep`).
-
- ```bash
- .venv/bin/pipelex-dev generate-error-pages
- ```
-
- - **`generate-error-identity`**: Regenerate the committed `(error_type, title, type_uri)` snapshot of every `PipelexError` subclass at `tests/data/errors/error_identity.txt`. `error_type` is the bare class name and consumers outside this repo branch on it, so a rename is a silent wire break — the snapshot turns it into a reviewable diff, gated by `tests/unit/pipelex/errors/test_error_identity_snapshot.py`. Run after adding, renaming or removing an error class. Also available as `make generate-error-identity` (alias `make gei`).
-
- ```bash
- .venv/bin/pipelex-dev generate-error-identity
- ```
-
- - **`refresh-graph-ui-sri`**: Refetch the pinned graph viewer assets from jsDelivr (`@pipelex/mthds-ui` standalone JS+CSS, `elkjs`) and rewrite `pipelex/graph/reactflow/standalone_assets.py` with new `sha384` Subresource Integrity hashes. Use when bumping the pinned mthds-ui or elkjs version.
-
- ```bash
- .venv/bin/pipelex-dev refresh-graph-ui-sri --mthds-ui-version 0.6.3
- # or rotate elkjs alongside:
- .venv/bin/pipelex-dev refresh-graph-ui-sri --mthds-ui-version 0.6.3 --elkjs-version 0.11.1
- ```
-
- - **`trace-input-semantics`**: Capture harness for the input-schema emission chain — given one or more `.mthds` bundles, dumps one artifact per hop (parse blueprint, generated class source, raw pydantic schema, SCHEMA render, wire contract) plus a manifest of each pipe input's wire framing, so a lost or mangled authored fact is localized to exactly one hop. Use when changing the structure blueprint, the structure generator, the schema render, or the contract builder. See `docs/contribute/trace-input-semantics.md`.
-
- ```bash
- .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/hinted_bundle.mthds \
- tests/data/input_semantics/probe_bundle.mthds \
- tests/data/input_semantics/scaffold_bundle.mthds \
- tests/data/input_semantics/output_bundle.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
- make drift-plan
- make drift-ack CONTRACT=config-docs RATIONALE="Documented the new setting; other config pages unaffected."
- ```
+`make` targets activate the virtual environment themselves; anything else (`pytest`, `pipelex`, `pipelex-dev`) runs from `.venv/bin/` (`.venv\Scripts\` on Windows), never bare. The Makefile is the reference for every target and alias; without `make`, read the target there and run its prerequisites one by one.
+
+- **`make agent-check` after every code change, and fix everything it reports.** Its prerequisites are `fix-unused-imports fix-keyword-only format lint pyright mypy check-ledger check-keyword-only check-hub-layering drift-check`: the import and keyword-only fixers, ruff, pyright, mypy, `plxt` over TOML/MTHDS/PLX, the migration-ledger replay (`cl`), the hub-layering check and the drift contracts. The drift digest reads the git index, so stage your changes before the check.
+- **Keyword-only arguments** (the convention is in the standards and in `docs/contribute/keyword-only-arguments.md`): `make check-keyword-only` (`cko`) is the gate, `make fix-keyword-only` (`fko`) inserts the bare `*` where it can — on ungranted subjects too — and reports the shapes it cannot fix, and `make subject-grant FUNC="<path>::<qualname>" RATIONALE="…"` (`sgr`) grants a positional subject. Grant before `make agent-check`, which runs the fixer.
+- **Drift contracts.** When `make drift-check` reports an open contract: `make drift-plan`, review and fix the stale targets, `git add` the trigger files, then `make drift-ack CONTRACT=<id> RATIONALE="…"`. No bypass flag; "reviewed, no doc change needed" is a legitimate rationale. See `docs/contribute/drift-contracts.md`.
+- **`make agent-test` at the end of every coding session.** Heartbeat lines while running, full output only on failure. If it hangs or fails opaquely, `make agent-test-debug` (`atd`) adds stale-process cleanup, an outer timeout and a live log; the methodology is `docs/agents/debugging-hanging-pytest-runs.md`. At intermediate steps in a local setup, running only the relevant tests is fine: `.venv/bin/pytest -x -q tests/unit/path/to/test_module.py`, or `make t TEST=<name>` (pytest `-k` substring matching; `TEST=LF` reruns the last failures). `make tp` / `make test-with-prints` are for a human at a terminal; an agent in the cloud or in a sandbox uses `make agent-test` only.
+- **`make test-ts-gates` (`ttg`) after touching anything under `pipelex/codegen/emitters/`, or moving the pinned prettier version.** `make agent-test` does not cover the TypeScript emission: the two gates that read the emitted TypeScript as TypeScript need a node toolchain and skip silently without one. This target provisions a pinned prettier and zod into `.ts-toolchain/` (npm, node >= 22.6) and makes those gates fail instead of skip, as CI does. See `docs/contribute/typescript-emission-gates.md`.
+- **`make cleanderived`** when linters or pytest collection get confused after files were erased or moved.
+- **`CLAUDE.md` and `AGENTS.md` are generated.** Edit the sources in `pipelex/kit/agent_rules/` (assembled per `pipelex/kit/index.toml`) and run `make rules`; `make check-rules` is the CI gate, and `make agent-check` does not include it.
+- **`pipelex-dev`** (`.venv/bin/pipelex-dev --help`) holds the internal generators, most with a `make` alias. `generate-mthds-schema` (`gms`) after modifying `mthds_schema_generator.py`. `generate-error-pages` (`gep`) and `generate-error-identity` (`gei`) after adding, renaming or removing an error class: consumers outside this repo branch on `error_type`, so a rename is a silent wire break that the committed snapshot turns into a reviewable diff. `refresh-graph-ui-sri --mthds-ui-version <v> [--elkjs-version <v>]` when bumping the pinned mthds-ui or elkjs. `trace-input-semantics` when changing the structure blueprint, the structure generator, the schema render or the contract builder (`docs/contribute/trace-input-semantics.md`). `generate-projection-corpus` to rewrite the fixture corpus committed byte-identically in `mthds-js` and `mthds-python` (`docs/contribute/generate-projection-corpus.md`). `drift` carries the drift-contract commands above.