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.
Migrator Phase 3, part 3: the review obligation, the two skills, and a remedy named only where it would write (#1115)
Louis Choquel6264de0fd10f
diff --git a/.claude/skills/add-migration/SKILL.md b/.claude/skills/add-migration/SKILL.mdnew file mode 100644index 000000000..8b4f648c9--- /dev/null+++ b/.claude/skills/add-migration/SKILL.md@@ -0,0 +1,236 @@+---+name: add-migration+description: >+ Write a migration ledger entry for a configuration schema change in pipelex, so+ that a user's existing file can be repaired instead of thrown away. Use when+ `make check-migration-schemas` (alias `cmig`) or `make check-ledger` (alias `cl`)+ refuses a change, when the user says "add a migration", "write the ledger entry",+ "the coverage gate is failing", "bump the schema version", "migration entry",+ "the migration gate won't let me", "account for this schema change", or after any+ edit to a configuration model that removed a key, renamed one, moved one, retired+ an enum member, or tightened what a value may be. This is the only skill that+ writes a ledger.+---++# Add a Migration Entry++A configuration **surface** — `pipelex.toml` and its tiers, `telemetry.toml`,+`pipelex_service.toml` — ships a checked-in ledger at+`pipelex/migration/ledgers/<surface-id>.toml` recording, as data, every shape+change it has ever undergone. A user's existing file is repaired by replaying that+ledger over it, so a schema change with no entry is a schema change that breaks+every machine in the field.++`docs/migration-ledger.md` is the normative contract. **Read it before writing an+entry** — this skill is the procedure, that document is the law, and where the two+disagree the contract wins.++## The one rule++**Derive the entry from the gate's refusal, never from memory.** The coverage+check recomputes the surface's fingerprint and names every path, every enumerated+spelling and every value domain the change moved. That output is the fingerprint+diff, already rendered. Composing an entry by hand from your own reading of the+diff is how a rename gets misspelled and every user's file is migrated onto a key+the schema rejects, with the tool reporting success.++## Step 1: See what the gate says++`make check-migration-schemas` (alias `cmig`) is deliberately **not** in+`make agent-check` — it is a golden check, and a fail-regenerate-fail cycle in the+loop agents run constantly is how a gate goes permanently green while catching+nothing. So run both gates explicitly:++```bash+make cl # check-ledger: is the ledger legal, and is replaying it harmless?+make cmig # check-migration-schemas: is every schema change accounted for?+```++Each failure names the surface and a `kind`, and every message says what to do. The table below is not the whole list of kinds — it is the map of which ones mean **an entry is owed**, and what it owes:++| Kind | What the change did | What the entry owes |+|---|---|---|+| `removal_needs_a_bump` | a path, an enumerated spelling or a value domain is gone from the models but still in the head golden | a version bump plus the operation that removes or repairs it |+| `unaccounted_path` | a path the diff removed that no operation in the entry acts on | an operation naming that path |+| `enum_member_not_remapped` | an enumerated spelling disappeared | a `remap_value` from the old spelling to the new one |+| `value_domain_narrowed` | the type or a bound got stricter — nothing was removed, but a legal value stopped being legal | a `remap_value` per narrowed path, or an `unsafe` entry naming them in `declared_narrowed_paths` |+| `dead_op` | an operation whose source no schema version ever removed, or a `delete_table` pointed at a key | fix the path or the kind — the applier would skip it forever while looking like an accounting |+| `destination_occupied` / `destination_not_in_new_shape` | an operation's destination is wrong | fix the destination — this is usually a typo, and it is the defect the transform goldens exist to catch |+| `over_deletion` | the entry removes a path the schema still has | narrow the operation; a parent is deleted only when the parent itself retires |+| `required_path_without_default` | an added required path has no value in the defaults layer | give it a default — an added key is absorbable only because the defaults layer carries it |+| `snapshot_pending` / `fingerprint_drifted` | the goldens predate the models | usually just step 5; if it is the only failure, no entry is owed |+| `reserved_path_reused` / `reserved_value_reused` | the new name was retired by an earlier version | **pick another name** — see step 4 |+| `convergence_broken` | replaying the ledger over a healthy reference document is not a no-op | the operation acts on live material, or on the wrong path |++**A gate that only asks for a regeneration is not asking for an entry.** An+additive change — a new optional key, a widened type, a relaxed bound — costs a+`make umig` and nothing else. Stop at step 5 in that case.++## Step 2: Decide the safety++`safety` governs whether the applier may act, and it is not a matter of taste:++- **`safe`** — the operations mechanically complete the repair. The file is+ rewritten after one confirmation. Everything structural is safe: renames, moves,+ deletions, and a `remap_value` whose old spelling is genuinely no longer legal.+- **`unsafe`** — no operation in the vocabulary can repair the file, so the entry+ is *reported and never applied*. This is the form for a tightened numeric bound,+ a completeness rule a validator expresses, anything where the tool would have to+ choose a value on the user's behalf.++An `unsafe` entry may legitimately carry no operations at all — and then+`declared_narrowed_paths` is **mandatory**, because the engine questions a+document before reporting an entry, and an entry with neither operations nor a+declaration answers "nothing to say" for every file there will ever be. The+declaration is spelled as the fingerprint at the entry's own version records the+paths, `*` segments included, and `make cl` refuses a path that version does not+have.++`guidance` is independent of `safety`: any entry may carry it, and it is the+explanation a person reads, **never the mechanism**. Anything expressible as+operations must be operations.++## Step 3: Write the entry++Two edits to `pipelex/migration/ledgers/<surface-id>.toml`, in one change:++1. In `[surface]`, raise `current_schema_version` to N.+2. Append a `[[migration]]` block. Entries are contiguous and named for their+ version — the id **must** be `<surface-id>@<N>` and `to_schema_version` **must**+ be N, or the file is refused when it is parsed.++```toml+[[migration]]+id = "example-config@2"+to_schema_version = 2+introduced_in = "0.46.0"+breaking = true+safety = "safe"+title = "Short imperative summary of the shape change"+description = "One or two sentences a release note can quote."+guidance = """+What a user should understand or decide. Never the mechanism.+"""++[[migration.ops]]+kind = "rename_table_key"+table_path = ["reporting"]+key = "output_config"+new_key = "output"+```++`introduced_in` is orientation only — nothing branches on it. A breaking entry+ships in a **minor** bump per the house convention, so write the next minor above+the current `pyproject.toml` version. `/release` step 3b confirms it against the+version actually being cut.++The operation vocabulary is structural only — `rename_table_key`, `move_key`,+`delete_key`, `delete_table`, `remap_value`. There is deliberately no operation+that writes a value into a user's file; one would be refused when the ledger is+parsed. `docs/migration-ledger.md` → "The operation vocabulary" has each kind's+fields, the `move_key` placement rule, and what the `*` wildcard segment means+(and where it is legal, which is only at an open node — and as a `remap_value`+key, which is the one shape that can repair a member renamed beneath an open+mapping).++**Operations target the narrowest path that expresses the change.** A ledger entry+is permanent data that outlives the current field census of its parent table, so+deleting a parent because it happens to hold one field today is wrong — unless the+parent itself is what retires, in which case its name becomes reserved too.++## Step 4: When the reserved-path rule fires++`make cl` refuses a name an earlier version retired:++> schema version 4 has 'reporting.output' again, but schema version 2 retired it —+> a retired path stays retired, because reusing the name makes removed material+> legal again. Pick another name++There is no escape hatch and there should not be one. Propose a replacement to the+user, and propose a *good* one: prefer a name that reads naturally for what the+field now means over a decorated variant of the retired one (`output_target`, not+`output_v2` or `output_`). The same rule applies to enumerated spellings — a value+a `remap_value` moved away from can never come back.++Renaming the field means changing the model, so the fingerprint moves again: go+back to step 1 rather than patching the entry.++## Step 5: Regenerate the goldens++```bash+make umig+```++This writes `[email protected]` and `[email protected]` for every surface, at the+version its ledger now declares. Older versions are never rewritten — they are the+frozen history the chain is made of — and the new version's files are new files,+so nothing is erased.++**Read the diff.** It is the only signal this command produces: line by line,+which paths the change added, removed or renamed. Running `umig` without reading+its diff throws that away.++**If `umig` refuses**, it is the guard doing its job: you are about to overwrite a+head golden that records material the models no longer have, which would erase+exactly what the coverage gate exists to catch. Read what it names. Almost always+the answer is that step 3 has not happened yet — bump the version and write the+entry, and the refusal disappears because there is no stored golden at N to erase.+`make umigf` is **not** the general escape: it is for one situation only, a golden+that predates a change to the fingerprint *format* over a schema version that has+not been released. Never hand-edit a golden.++## Step 6: Prove it++```bash+make cl && make cmig+```++Both green means three separate claims hold: the entry is legal and replaying it+over a healthy file changes nothing (`cl`), every path the change moved is+accounted for, and — the transform goldens — the operations *actually perform* the+migration from `defaults@N-1` to `defaults@N`, and the migrated document is+accepted by the current model.++Then the usual gates: `make agent-check`, and `make agent-test` before wrapping up.++## Step 7: The changelog++The ledger and the changelog are deliberately separate artifacts saying the same+thing to different readers, and `/release` step 3b is where they are checked+against each other. For each entry with `breaking = true`, add a bullet to+`## [Unreleased]` beginning with the literal label:++```markdown+- **Migration:** `telemetry-config@2` lifts the flat first-generation telemetry+ file into today's `[custom_posthog]` section, keeping every value the user+ chose. Four settings the current shape has no home for are dropped, and the+ entry says which and why. Run `pipelex migrate`.+```++House style: a bold label, then two to four complete sentences. Say what moved and+what a user has to do; do not restate the operation list.++## Special case: a change that predates the first fingerprint++An entry may carry `pre_history = true` when the change it describes happened+before the surface had a fingerprint, so no diff accounts for it. Such an entry+declares its own `declared_removed_paths` (an empty declaration is refused), none+of those paths may appear in any fingerprint at or below its version, and it ships+a hand-authored `goldens/<surface-id>/[email protected]` so the transform check has a+pair to verify. This is rare and it is not a way past the gate — reach for it only+when there genuinely is no diff, and read+`docs/migration-ledger.md` → "Pre-history entries" first.++## What this skill must never do++- **Never hand-edit a fingerprint or defaults golden.** They are generated; the+ generator is `make umig` and the diff is the review artifact.+- **Never make a gate green by widening it.** If a check refuses the change,+ either the change owes an entry or the check found a real defect. Editing the+ check is a separate decision with its own review.+- **Never reuse a retired path or spelling** to make the reserved-path rule quiet.+- **Never invent a value.** A `remap_value` mapping carries the new spelling of an+ old one — a translation the user's own file determines, which is why it can be+ `safe`. What no operation may do is write a value the file does not already fix:+ a default, or a replacement for a value a tightened bound now refuses. If the+ repair needs one of those, the entry is `unsafe` and a person makes the choice.diff --git a/.claude/skills/release/SKILL.md b/.claude/skills/release/SKILL.mdindex b0661898d..0ce1b1652 100644--- a/.claude/skills/release/SKILL.md+++ b/.claude/skills/release/SKILL.md@@ -22,6 +22,7 @@ This skill handles the full release cycle for the `pipelex` Python package.- **`uv.lock`** — regenerated via `make li` (lock + install)- **`.badges/tests.json`** — test count updated to match actual count- **`.test_durations`** — regenerated via `make store-test-durations` so the CI test shards stay balanced (see step 8b)+- **`pipelex/migration/ledgers/*.toml`** and **`pipelex/migration/goldens/`** — only when step 3b finds an unaccounted schema change; written by the `add-migration` skill, never by hand## Workflow@@ -47,6 +48,51 @@ Run `make agent-check`. This is the gate — if it fails, stop and report theerrors so they can be fixed before retrying. Do not proceed past this step onfailure.+### 3b. Ledger completeness++`make agent-check` does not run the coverage gate — it is a golden check and lives+in `make check` only — so a schema change that has not been accounted for reaches+here unseen. This step is what makes it impossible for a release to ship a moved+configuration schema without the migration that repairs a user's file.++Run:++```bash+make check-migration-schemas+```++- **If it fails**, the release is blocked. Invoke the **`add-migration`** skill: it+ derives the entry from the fingerprint diff the gate just printed, bumps the+ surface's schema version, regenerates the goldens and adds the changelog bullet.+ Then re-run this step. Do not proceed on a red gate, and do not regenerate the+ goldens to make it quiet — a green gate over an unaccounted removal is exactly+ the failure the gate exists to prevent.+- **If it passes**, check whether any schema version moved in this release. Diff+ the ledgers against the tag of the version read in step 1 — the previous+ release, whichever branch the skill was invoked from (`origin/main` is not a+ safe baseline: from `main` itself that diff is empty):++ ```bash+ git diff v<current version> -- pipelex/migration/ledgers/+ ```++ For each entry that is new since that release and carries `breaking = true`, confirm+ the changelog carries a matching `**Migration:**` bullet naming the entry id and+ what a user has to do. The ledger and the changelog are deliberately separate+ artifacts saying the same thing to different readers, and this is the only place+ they are checked against each other — if the bullet is missing, write it now+ (house style: bold label, then two to four complete sentences).++ **A breaking ledger entry makes this a minor release**, per the house+ convention — if step 2 chose a patch bump and this step found one, go back and+ settle the bump first, because the next check writes the new version into the+ entry.++ Then confirm each such entry's `introduced_in` matches the version being cut.+ It is written when the entry is authored, before the release number is known, so+ it is routinely one bump off. Nothing branches on it, but it is what a reader+ correlates the changelog against, so fix it here rather than leaving it wrong.+### 4. Ensure we're on the right branchThe release branch must be named `release/vX.Y.Z` where X.Y.Z is the **new**@@ -170,6 +216,9 @@ Report the PR URL back to the user.- Always confirm the bump type with the user before making changes.- If `make agent-check` fails, the release is blocked — help the user fix theissues rather than skipping the checks.+- If `make check-migration-schemas` fails (step 3b), the release is blocked too,+ and the fix is an entry written by the `add-migration` skill — never a golden+ regeneration that makes the gate quiet.- The CI will validate that:- The `pyproject.toml` version matches the branch name (`version-check.yml`)- The `CHANGELOG.md` has an entry for the version (`changelog-check.yml`)diff --git a/.drift/acks/cli-docs.toml b/.drift/acks/cli-docs.tomlindex 8827432e2..79a78f50f 100644--- a/.drift/acks/cli-docs.toml+++ b/.drift/acks/cli-docs.toml@@ -1,8 +1,8 @@contract = "cli-docs"-digest = "sha256:7d39d2644991dae40be1f456c4b7ae9ece82178b60399f2836858421e835e47a"+digest = "sha256:61a24bbc7b269beabac81b4d4b01d693e78c19acb26f1617b654d942eb98822f"reviewed_by = "Louis Choquel"-reviewed_at = "2026-08-16T21:01:37Z"-rationale = "Second bot-review round on PR 1114: the doctor telemetry row reads the verdict off the plan of the file it validated instead of the whole directory; pipelex migrate's cancel path now exits through _exit_on_attention, and the closing panel tests an unconfirmed write before the written count. No flag, field, format, finding value or exit-code rule moved. docs/tools/cli/migrate.md's claim that the command exits non-zero when it leaves something to look at is now true on every path including cancel; the finding semantics are documented in docs/migration-ledger.md, updated in the same change. agent-cli.md only had its stderr single-object sentence scoped to the structured commands."+reviewed_at = "2026-08-16T23:26:20Z"+rationale = "Third trigger on this branch, from the PR #1115 review: the PowerShell line of the doctor's manual-fix guidance was the one platform example still interpolating a credential variable name without rich.markup.escape, and now goes through it like its three siblings. Presentation only — no command, flag, output format, finding value or structured field moved, and neither review target mentions the platform examples, so both were read and neither is stale."[trigger_files]"pipelex/cli/__init__.py" = "blob:8b137891791fe96927ad78e64b0aad7bded08bdc"@@ -12,7 +12,7 @@ rationale = "Second bot-review round on PR 1114: the doctor telemetry row reads"pipelex/cli/agent_cli/commands/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391""pipelex/cli/agent_cli/commands/accept_gateway_terms_cmd.py" = "blob:a1fc438119dd10607252c08390ebd6384d999678""pipelex/cli/agent_cli/commands/agent_cli_factory.py" = "blob:caba5ab957e4a2bbb62e329ba6722a441dff781e"-"pipelex/cli/agent_cli/commands/agent_output.py" = "blob:b73cdb4738c7a64a9ae54665bb20d040a81beb41"+"pipelex/cli/agent_cli/commands/agent_output.py" = "blob:19cb8df5cf764c85aeaf91d24ce13b26607fff1c""pipelex/cli/agent_cli/commands/bundle_path_resolver.py" = "blob:30339c5d91048f4e67312d5691ed9a65d57472e0""pipelex/cli/agent_cli/commands/check_model_cmd.py" = "blob:f4bdc5f3732b067e397dde384b511f436f95e526""pipelex/cli/agent_cli/commands/codegen/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"@@ -82,7 +82,7 @@ rationale = "Second bot-review round on PR 1114: the doctor telemetry row reads"pipelex/cli/commands/codegen/inputs_cmd.py" = "blob:20738a9e42f0e5ef7ffc489093348af3cb4643a0""pipelex/cli/commands/codegen/types_cmd.py" = "blob:b7c9c7a3664c9fbe66f9b4c3c5ebf9ea1322445c""pipelex/cli/commands/crate_loading.py" = "blob:3d7d651931ecf1a15a3e2d72411b3212b55d74ef"-"pipelex/cli/commands/doctor_cmd.py" = "blob:6484b5da59af0f978fe79d675089e05da9d7ac81"+"pipelex/cli/commands/doctor_cmd.py" = "blob:0802df0148d1f880f3b244ebb339fd4419ec528d""pipelex/cli/commands/fix/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391""pipelex/cli/commands/fix/_diff_sandbox.py" = "blob:2113f7e7ffd373177a3104ce5b5dfb7f657dd186""pipelex/cli/commands/fix/_fix_core.py" = "blob:8f6a187a0fb42c498629b177753d81620800b0da"@@ -127,7 +127,7 @@ rationale = "Second bot-review round on PR 1114: the doctor telemetry row reads"pipelex/cli/commands/validate/pipe_cmd.py" = "blob:d67267571559006459628180f2c8b216ba7fee31""pipelex/cli/commands/which_cmd.py" = "blob:68661d4bab22e2c4dab183d59bd9f2c6dd573472""pipelex/cli/deck_notice.py" = "blob:542877125e89e35b02bc969cfee952155b0d7c2c"-"pipelex/cli/error_handlers.py" = "blob:c491c7f72e1d00017dbc9b08f092b788b81b521e"+"pipelex/cli/error_handlers.py" = "blob:7a925ef0517bf9b01c3ca4b91ae54a70f57123a6""pipelex/cli/exceptions.py" = "blob:1d51c3a53ddd3f6cf8de566fa2ade3fa75ab7a3a""pipelex/cli/installed_methods.py" = "blob:2a1adeda25082bd2bef44887b9af60c29dab8d7b""pipelex/cli/method_resolver.py" = "blob:850ad43ee2c6fb0ffc3f449f62ceea1ab6f17297"diff --git a/.drift/acks/config-docs.toml b/.drift/acks/config-docs.tomlindex 919543457..ab38ac097 100644--- a/.drift/acks/config-docs.toml+++ b/.drift/acks/config-docs.toml@@ -1,8 +1,8 @@contract = "config-docs"-digest = "sha256:31b470d034b3bcd4072bb4b286a4e1cf37b4414d5b884c42cd78f421fe72a679"+digest = "sha256:9de76c70a5219d0073dacc6b93f3336c9ee9e9d37b798ca2dc025c97b03c19d5"reviewed_by = "Louis Choquel"-reviewed_at = "2026-08-16T20:18:24Z"-rationale = "Review of the PR 1114 fixes to config_loader.py and config_surface.py: the main-configuration stale warning is now parked on the loader and emitted after logging is configured, and the in-memory retry declines a file declaring a schema version below the ledger floor. Both are boot-tolerance mechanics documented in docs/migration-ledger.md, which was updated in the same change; docs/configuration/ describes files and keys, and telemetry-config.md's out-of-date section still says exactly what a user sees - a boot that warns and names pipelex migrate. No configuration key, default or file moved, so no page under docs/configuration/ is stale."+reviewed_at = "2026-08-16T22:14:43Z"+rationale = "The contract definition itself changed: its review list now carries pipelex/migration/ledgers/ and the two modules holding the four validators that narrow a configuration value domain (KitConfig._validate_targets, DryRunConfig.validate_image_urls, ImgGenConfig.validate_quality_mapping, LLMConfig.validate_effort_to_budget_mapping), which R8 established the fingerprint projection cannot see. No trigger file moved, so this is the first read of the new targets rather than a review of a change: the three ledgers are legal and convergent and the three surfaces are accounted for (make cl, make cmig both green), and none of the four validators narrowed anything in this change, so no unsafe entry with declared_narrowed_paths is owed. docs/configuration/ is unaffected - no key, default or file moved."[trigger_files]"pipelex/cogt/config_cogt.py" = "blob:ee1ee2d0c1474dcef5e07690268de37ae3ff0987"diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 97909e70d..9c8b2404a 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -4,7 +4,7 @@### Added-- **A configuration that will not load now says whether it is wrong or merely old**: A validation error is raised against the merged configuration and carries no provenance — it names a key, not which file put it there, and certainly not whether that key was correct last month. When a configuration surface's model refuses, the error now also carries a dry-run scan of that surface over the same directories `pipelex migrate` walks: a structured `migration` block naming the remedy, whether anything there is a person's to resolve rather than the tool's, and the plan per file — the same shape `pipelex-agent migrate --dry-run --format json` emits, so an agent that parses one has already parsed the other. `error_domain` deliberately stays `config`: it is a closed cross-repo enum and the agent-hook specification routes anything else to BLOCK, so a stale configuration reported under a new domain would stop an agent instead of telling it what to run. Consumers branch on the block's presence — absent means the failure is not staleness — and the message gains a paragraph naming the files and the command. No value read from a user's file appears in the block, which is the third of the three channels that rule covers. A caller validating something that is not a configuration surface — a `.mthds` bundle, a backend file, a model deck — names no surface and pays for no walk.+- **A configuration that will not load now says whether it is wrong or merely old**: A validation error is raised against the merged configuration and carries no provenance — it names a key, not which file put it there, and certainly not whether that key was correct last month. When a configuration surface's model refuses, the error now also carries a dry-run scan of that surface over the same directories `pipelex migrate` walks: a structured `migration` block naming the remedy, whether that remedy would actually rewrite anything, whether anything there is a person's to resolve rather than the tool's, and the plan per file — the same shape `pipelex-agent migrate --dry-run --format json` emits, so an agent that parses one has already parsed the other. `error_domain` deliberately stays `config`: it is a closed cross-repo enum and the agent-hook specification routes anything else to BLOCK, so a stale configuration reported under a new domain would stop an agent instead of telling it what to run. Consumers branch on the block's presence — absent means the failure is not staleness — and then on `would_write`, because presence means the migration history has something to *say* about these files and not that a command repairs them: a block whose only finding is a path no entry explains, or an entry blocked before anything applied, has nothing to run, and naming the remedy there would send a reader to a run that writes nothing and leaves the same error standing. Every surface points that reader at `pipelex migrate --dry-run` instead, where the diagnosis is. The message gains a paragraph naming the files and the next move. No value read from a user's file appears in the block, which is the third of the three channels that rule covers. A caller validating something that is not a configuration surface — a `.mthds` bundle, a backend file, a model deck — names no surface and pays for no walk.- **A configuration file the ledger can explain no longer stops the boot**: A schema change used to leave every machine in the field with a boot that died on `extra="forbid"`, naming a key the user never chose to have. When a configuration surface fails to validate, its ledger is now replayed over the same files **in memory** and the result validated again; a boot that succeeds says so in a warning naming the files and the `pipelex migrate` remedy, and nothing is written — a tolerated boot leaves the file and its directory exactly as it found them, which is why the warning keeps coming back until the command is run. Tolerance widens what starts and never what is accepted: the re-validation is what decides, so material an `unsafe` entry is about still fails the boot because the model still refuses it. Anything that goes wrong inside the retry makes it decline rather than replace the error the user already has — theirs names the key to fix. A healthy configuration pays nothing: it reads no ledger, re-parses no document, and does not even import the migration engine, which is deferred for a second reason too, since the applier lives in the interpreter layer and the configuration loaders sit in the kernel layer that must not load it. The telemetry configuration is the surface this reaches today, because it carries the only entry the package ships.- **`pipelex migrate` and `pipelex-agent migrate`**: The migration engine now has commands, so a configuration that predates the installed pipelex can be repaired instead of re-initialized. Both walk the global `~/.pipelex/` and the project `.pipelex/` — those two directories only, and not recursively, because a subdirectory such as `inference/backends/` holds a different kind of file and one of them (`pipelex_gateway.toml`) matches the main configuration's tier glob exactly. Neither command boots: a broken configuration is the reason to reach for them, so they use the ledger, the applier and the filesystem and nothing else, and a test hands them a configuration that cannot load to keep it that way. The human command plans, shows the plan and asks; the machine one writes only with `--yes`, since it cannot ask, and passing `--dry-run` and `--yes` together is refused rather than resolved. Its answer is structured, and `needs_attention` is the verdict — *this run left something a person has to decide*, deliberately not *did anything get written* — with the exit code and the Markdown rendering as presentation. Every file rewritten is backed up beside itself first, and no value read from a user's file appears in either command's output or in the structured plan.@@ -28,7 +28,10 @@### Changed-- **A stale telemetry configuration is migrated instead of thrown away**: `telemetry.toml` failing to load used to get one answer everywhere — *the format has changed, run `pipelex init telemetry`* — written for the flat pre-`[custom_posthog]` file and then shown for every other way a file can fail. That command writes a fresh file, so on the very case it named it discarded the PostHog key, the Langfuse credentials and the OTLP exporters that the shipped `telemetry-config@2` entry carries forward. The telemetry loader now raises through the same reporting path as every other configuration surface, so its error carries the structured `migration` block and the human CLI, the agent envelope and `pipelex doctor` all say whether the file is *old* or *wrong* rather than each holding a hardcoded remedy. `TelemetryConfigError` is a `PipelexConfigError`, which is where its `error_domain = config` now comes from — its entry in the agent CLI's domain table is gone as redundant. The `doctor` telemetry row carries a structured `finding` (`healthy`, `not_found`, `unparseable`, `out_of_date`, `invalid`) that every caller branches on; writing a fresh file is offered for a missing file only, and regeneration is described as what it is, a way to start over that discards the file. The telemetry models stayed in `telemetry_config.py` and the loader moved into a new `telemetry_loader.py` beside it, because the loader's failure path reaches the migration registry and the registry imports every configuration model.+- **The migration ledger contract is published, and a config-model change now owes it a review**: `docs/migration-ledger.md` was written ahead of the engine it specifies and shipped built-but-unlisted; the commands it describes exist, so it joins the documentation navigation beside the other contributor contracts and loses its status banner. Alongside it, the `config-docs` drift contract's review list gains the migration ledgers and the two modules holding the four validators that narrow a configuration value domain — a narrowing expressed in a validator is invisible to the fingerprint projection the coverage gate reads, so no derived check can ever demand the ledger entry it owes, and a review obligation is the only place that can land. The migration goldens are deliberately not in that list: they are generator output, and their staleness is already `check-migration-schemas`' business.+- **Writing a migration entry is a skill, and a release checks one was written**: `.claude/skills/add-migration/` is the only thing that writes a ledger — it derives the entry from what the coverage gate refused rather than from a reading of the diff, bumps the surface's schema version, regenerates the goldens, and adds the changelog bullet. `/release` gains step 3b before the version bump: `make check-migration-schemas` does not run in `make agent-check`, so an unaccounted schema change would otherwise reach a release unseen; the step blocks on it, sends a failure to `add-migration`, and confirms a `**Migration:**` changelog bullet and a correct `introduced_in` for every new breaking entry.++- **A stale telemetry configuration is migrated instead of thrown away**: `telemetry.toml` failing to load used to get one answer everywhere — *the format has changed, run `pipelex init telemetry`* — written for the flat pre-`[custom_posthog]` file and then shown for every other way a file can fail. That command writes a fresh file, so on the very case it named it discarded the PostHog key, the Langfuse credentials and the OTLP exporters that the shipped `telemetry-config@2` entry carries forward. The telemetry loader now raises through the same reporting path as every other configuration surface, so its error carries the structured `migration` block and the human CLI, the agent envelope and `pipelex doctor` all say whether the file is *old*, *wrong*, or reported on by a migration that would not repair it — rather than each holding a hardcoded remedy. `TelemetryConfigError` is a `PipelexConfigError`, which is where its `error_domain = config` now comes from — its entry in the agent CLI's domain table is gone as redundant. The `doctor` telemetry row carries a structured `finding` (`healthy`, `not_found`, `unparseable`, `out_of_date`, `invalid`) that every caller branches on, and `out_of_date` is a promise the migration would rewrite that file, so a file it would only report on is `invalid` and keeps the dry run's pointer; writing a fresh file is offered for a missing file only, and regeneration is described as what it is, a way to start over that discards the file. The telemetry models stayed in `telemetry_config.py` and the loader moved into a new `telemetry_loader.py` beside it, because the loader's failure path reaches the migration registry and the registry imports every configuration model.- **The fingerprint records the bounds a file actually meets, and the enumerated spellings where an operation can reach them**: A bound in a field's own metadata *binds* — pydantic applies it on top of whatever a union member declares — so the two sources are now merged separately and intersected instead of pooled and widened; a field whose own `Field(le=6)` was the real ceiling used to be recorded as `le=100` because a member said so, and a later tightening of that ceiling then read as a change to an already-looser one. Enumerated members beneath an open mapping are now recorded only on the wildcard record, whose own value is the enumerated one: recording them on the container as well made the coverage gate demand a remap of a table value, a demand no operation could satisfy. Every other container is still descended into, since a `list[enum]` has no child record — and there the gate now names `unsafe` as the only remedy rather than crediting a remap that would skip on every run. One golden moved with it: the duplicated member set on `pipelex.log_config.package_log_levels`.- **The narrowing relation stopped crying wolf on four shapes**: A container whose argument widened (`list[int]` → `list[int | str]`) is read structurally instead of as one opaque string; `int` is absorbed by `float`, which accepts every integer in strict validation as well as lax; `enum` and `literal` absorb each other, because they are two renderings of one thing and what moved between two member *sets* is reported by the enumerated-spelling half; and over an integral type `gt=n` and `ge=n+1` are folded to the same bound, so swapping one spelling for the other stops reading as a tightening. Each was a false breaking verdict on a schema no user's file can tell apart, and the remedy the gate named — bump the version, write an `unsafe` entry — was work with no beneficiary.- **`make up-migration-schemas` left `make up`, and refuses to erase a removal**: Every other regenerator in that aggregate rewrites a derived artifact from a live source, so running them out of habit is harmless; the head fingerprint golden is the proof obligation the coverage gate compares against, and rewriting it after deleting a field erases the very removal the gate exists to catch. It is now run on purpose, and it stops before overwriting a head golden recording a path, an enumerated spelling or a value domain the models no longer have. The refusal names both readings — a real removal wants a bump and an entry; a golden that merely predates a change to the fingerprint format wants the new `make umigf` — because the code cannot tell them apart.@@ -45,6 +48,8 @@### Fixed+- **A bracket in a path no longer breaks the health report**: `pipelex doctor` printed almost every dynamic value through Rich's markup parser, so a directory named `[dev]` vanished from the output and a message quoting a `[/b]` — which a configuration validation error quotes back from the user's own file — raised a markup error and took the whole report down, worst exactly when the report is what the user came for. Every value the report interpolates is now escaped: the four row messages, the configuration paths, backend names, environment-variable names, deck filenames, the backend error line, and the text of every exception the `--fix` pass reports.+- **`pipelex doctor --fix` no longer offers to overwrite a telemetry configuration it could migrate**: The fix machinery decided what it could repair by searching the row's *message* for `"format has changed"` or `"invalid configuration"`, and on a match offered to write a fresh `telemetry.toml` — discarding every setting in it. It now branches on a structured finding, so an out-of-date file is answered with `pipelex migrate` and an invalid one is left to a person. Rewording the row can no longer switch the repair path off in silence, which the string search would have done without a test failing.- **The doctor's telemetry check strips the reserved `[meta]` table the way boot does**: A `telemetry.toml` carrying the migration machinery's reserved `[meta]` table boots perfectly well and was reported invalid by the health check, which validated the raw document.- **A boot that fails on the main configuration reports it instead of crashing**: `RuntimeBoot` and the doctor both caught `pydantic.ValidationError` around `setup_config`, and the main configuration does not raise one — `ConfigRoot` translates pydantic's error into `ConfigValidationError` before it leaves — so the arm never fired for the one configuration everything depends on, and a machine with a bad `pipelex.toml` got a bare traceback rather than the field-level translation the arm existed to produce. Both sites now catch either shape a refusal takes and share one helper, so the same refusal produces the same message and the same structured block wherever it is caught.diff --git a/docs/contribute/drift-contracts.md b/docs/contribute/drift-contracts.mdindex 66ff70816..a814aa6da 100644--- a/docs/contribute/drift-contracts.md+++ b/docs/contribute/drift-contracts.md@@ -10,9 +10,11 @@ Not every code↔doc relationship deserves a review contract. This repo distingu|---|---|---|| **Derived** | Regenerate and diff: `check-config-sync`, `check-mthds-schema`, `check-gateway-models`, `generate-error-pages`, `generate-error-identity` | None — the output is a pure function of its sources || **Linkage** | Referential integrity of declared cross-references (the spec ↔ verifying-test back-link pair) | None — links either resolve or they don't |-| **Review** | Drift contracts: "this changed → that must be looked at, and the look recorded" | Yes — someone must judge whether the prose still holds |+| **Review** | Drift contracts: "this changed → that must be looked at, and the look recorded" | Yes — someone must judge whether the target still holds |-The standing rule: **anything mechanizable becomes a derived check.** If a review contract keeps opening and the review is always the same mechanical comparison, delete the contract and write a derived check instead — it needs no judgment and can't be rubber-stamped. The best review contract is one you eventually mechanize out of existence. Corollary: generated artifacts (`docs/errors/`, `derived/`, `tests/data/errors/error_identity.txt`, gateway model docs) must never appear in a contract's `review` list — reviewing generator *output* is how you end up editing generated files.+The standing rule: **anything mechanizable becomes a derived check.** If a review contract keeps opening and the review is always the same mechanical comparison, delete the contract and write a derived check instead — it needs no judgment and can't be rubber-stamped. The best review contract is one you eventually mechanize out of existence. Corollary: generated artifacts (`docs/errors/`, `derived/`, `tests/data/errors/error_identity.txt`, gateway model docs, the migration goldens) must never appear in a contract's `review` list — reviewing generator *output* is how you end up editing generated files, and a generated artifact's staleness is already somebody's derived check.++**A review target does not have to be prose.** Most are docs, because most staleness is a sentence that stopped being true — but the obligation is "look at this and judge", and what has to be judged is sometimes source. `config-docs` carries the migration ledgers and the two modules holding the four validators that narrow a configuration value domain: a narrowing expressed in a validator is invisible to the fingerprint projection the coverage gate reads, so no derived check can ever demand the ledger entry it owes, and the review list is the only place that obligation can land. The bar is the same as for a doc — the target must be something a person reads and judges, never something a command regenerates.## How it worksdiff --git a/docs/migration-ledger.md b/docs/migration-ledger.mdindex 3644054be..1be6f3ced 100644--- a/docs/migration-ledger.md+++ b/docs/migration-ledger.md@@ -4,8 +4,6 @@ Pipelex configuration files live on users' machines and in users' repositories,This page is the contract: what a ledger may contain, what the engine may do with it, and what is guaranteed to a user whose files are migrated. It is normative. Everything asserted here has, or will have, a test behind it, and where a rule exists to prevent a specific failure the failure is named — a rule whose reason is forgotten is a rule that gets relaxed.-> **Status.** This specification was written before its implementation, deliberately: the guarantees below are what the engine is built against. The data format, the operation vocabulary and the checks land first; `pipelex migrate` and boot tolerance land last. Every check described here exists today: the coverage gate (`make check-migration-schemas`), its regenerator (`make up-migration-schemas`), the ledger check (`make check-ledger`), the transform-golden verifier inside the coverage gate, the neutrality property suite, and the verification of a [pre-history entry](#pre-history-entries). The ledgers themselves are nearly empty — `telemetry-config` carries the one entry the package ships, and the other two surfaces sit at schema version 1 — so over those two the neutrality property still exercises its sampler rather than the theorem. Until the commands exist, this page is built but kept out of the documentation navigation.-## What migrates, and what does notA **structural** change is a key renamed, moved or removed, or an enumerated value renamed. It breaks a user's file: the model rejects it, and no amount of re-reading helps. That is what the ledger describes and what the engine repairs.@@ -346,7 +344,7 @@ Two shapes are recorded as terminal rather than descended into, because no opera**What the fingerprint records is what the types say, and a validator can say something else.** Every recorded field is read from an annotation or from the metadata beside it, so a constraint expressed as a validator instead is invisible here — and that is not a corner case, it reaches the enum member set and the open-node marker alike. A telemetry mode is a member of the recorded set and is still rejected unless the document also carries the user id that mode requires. Several nodes typed `dict[str, X]` on the main configuration surface reject any key outside a fixed set, so the open-node marker claims a key space that is not the user's after all. A pair of validators demands every member of an enum as a key of every entry of an open mapping, which makes *adding* an enum member break a user's file — additively, as far as any projection can tell. Nothing here can be made to see any of it.-> **The gate does not claim what it cannot see.** Domain narrowing expressed in a validator — a non-empty check, a cross-field invariant, a completeness rule over user-supplied keys — is not visible from the schema and stays the author's responsibility. The [coverage gate](#coverage-every-schema-change-is-accounted-for) catches the mechanical subset: types and the whitelisted bounds. It does not catch the rest, and the coverage table would overclaim without this sentence.+> **The gate does not claim what it cannot see.** Domain narrowing expressed in a validator — a non-empty check, a cross-field invariant, a completeness rule over user-supplied keys — is not visible from the schema and stays the author's responsibility. The [coverage gate](#coverage-every-schema-change-is-accounted-for) catches the mechanical subset: types and the whitelisted bounds. It does not catch the rest, and the coverage table would overclaim without this sentence. **The responsibility is declared rather than left to memory:** the `config-docs` drift contract ([`docs/contribute/drift-contracts.md`](contribute/drift-contracts.md)) carries the migration ledgers and the two modules holding the four live validator sites in its review list, so a change to any configuration model opens an obligation to ask whether a validator narrowed a domain and, if one did, whether an `unsafe` entry carrying `declared_narrowed_paths` is owed.The consequence for the gates is mild where they compare a fingerprint against a fingerprint, because a blind spot on both sides cancels. The consequence for anything that tries to *decide schema membership* from a fingerprint is total, and it is why [the neutrality property test](#replay-neutrality) asks the models rather than the projection.@@ -565,9 +563,11 @@ A validation error cannot answer that by itself. It is raised against the mergedThe answer rides the error twice, and the two halves are not interchangeable:- **`error_domain` stays `"config"`.** It does not become a domain of its own. `ErrorDomain` is a closed cross-repo enum and the agent-hook specification routes any domain it does not know to BLOCK, so a stale configuration reported under a new domain would stop an agent rather than tell it what to run.-- **The structured `migration` block is the contract, and consumers branch on its presence.** Absent means the failure is not staleness. Present, it carries `remedy` (the command), `needs_attention` (whether anything here is a person's rather than the tool's), and `plans` — the same `MigrationPlan` shape `pipelex-agent migrate --dry-run --format json` emits under its own `plans` key, so an agent that parses one has already parsed the other. Only the files the scan found something in are listed: unlike the commands' report, which answers *what did the walk visit*, the block answers *what is wrong with this machine*.+- **The structured `migration` block is the contract, and consumers branch on its presence.** Absent means the failure is not staleness. Present, it carries `remedy` (the command), `would_write` (whether that command would rewrite any of these files), `needs_attention` (whether anything here is a person's rather than the tool's), and `plans` — the same `MigrationPlan` shape `pipelex-agent migrate --dry-run --format json` emits under its own `plans` key, so an agent that parses one has already parsed the other. Only the files the scan found something in are listed: unlike the commands' report, which answers *what did the walk visit*, the block answers *what is wrong with this machine*.- **The message is presentation.** It carries the pydantic analysis followed by a paragraph naming the files, what the command would carry forward, and what it cannot do for anyone. Nothing branches on its wording.+> **A remedy is named only where it would write, and `would_write` is what says so.** The block's presence means the migration history has something to report about these files — not that running the command repairs them. A file whose only finding is a path no entry explains, or an entry blocked before any of its operations landed, produces a block with nothing to apply; naming `remedy` there sends a reader to a run that visits the file, writes nothing, and leaves the same refusal in front of them. So every surface branches on the field rather than on the presence, and the ones with nothing to apply point at `pipelex migrate --dry-run`, where the diagnosis actually is. The two flags are independent and never both false: a file with nothing to write and nothing for a person is clean, and clean files are not in `plans`.+The agent loop this opens is the one the commands were built for: a command fails, the block is present, the agent runs `pipelex-agent migrate --dry-run --format json`, shows the user what would change, and runs `--yes` on confirmation. It never hand-edits a configuration file.> **No value read from a user's file appears in the block either.** This is the third of the three channels that rule covers, beside the command's own output and its structured plan. The block reports paths, operation kinds and ledger-supplied values — a key holding a live credential is named by its *path* and never by what it holds.@@ -581,9 +581,9 @@ A configuration error reaches a user through several surfaces at once — the huSo no surface holds its own answer any more:- Every configuration surface's loader raises through `report_validation_error`, so the `migration` block reaches the error wherever it is caught. `TelemetryConfigError` is a `PipelexConfigError` for this reason — it carries `error_domain = CONFIG` from the class rather than from the agent CLI's lookup table, and it can carry a block.-- The **human handler** prints the fields the model refused and then names `pipelex migrate` when the block is there, or an edit when it is not.-- The **agent envelope** carries `migration` as a field and its hint says which of the two readings applies; an agent branches on the field, never on the sentence.-- The **`doctor` row** carries a *finding* — `healthy`, `not_found`, `unparseable`, `out_of_date`, `invalid` — and every caller reads that instead of the row's wording. This one is a correctness fix and not only a tidy-up: `--fix` used to decide what it could repair by searching the message for `"format has changed"`, so rewording the row would have switched the whole repair path off in silence. The finding answers for the one file the row is about: the scan behind `out_of_date` runs over the directory that file lives in — which also holds the `telemetry_*.toml` tier — and the verdict is read off that file's own plan, so a stale tier file beside a wrong base file leaves the base file `invalid`, and the fields the model refused stay on the row.+- The **human handler** prints the fields the model refused and then names `pipelex migrate` when the block says it would write, the dry run when it says it would not, and an edit when there is no block at all.+- The **agent envelope** carries `migration` as a field and its hint says which of the three readings applies — no block, a block that would write, a block that would not; an agent branches on the fields, never on the sentence.+- The **`doctor` row** carries a *finding* — `healthy`, `not_found`, `unparseable`, `out_of_date`, `invalid` — and every caller reads that instead of the row's wording. This one is a correctness fix and not only a tidy-up: `--fix` used to decide what it could repair by searching the message for `"format has changed"`, so rewording the row would have switched the whole repair path off in silence. The finding answers for the one file the row is about: the scan behind `out_of_date` runs over the directory that file lives in — which also holds the `telemetry_*.toml` tier — and the verdict is read off that file's own plan, so a stale tier file beside a wrong base file leaves the base file `invalid`, and the fields the model refused stay on the row. **`out_of_date` means the plan would rewrite that file**, not merely that it is unclean: a file the migration would leave untouched is `invalid`, which is the finding that routes to a person and which `--fix` does not offer to run a command over, and the row keeps the dry run's pointer so the diagnosis is not lost with the finding.> **Writing a fresh file repairs exactly one finding: a missing one.** There is nothing in a file that is not there to lose. Every other unhealthy state has the user's own settings in it, so an out-of-date file is offered `pipelex migrate` and a broken one is left to a person. Regeneration is still reachable, and it is described as what it is — a way to start over that discards the file.@@ -688,4 +688,4 @@ A release can never ship a moved schema without its entry: the release procedure## Related- [Configuration Internals](contribute/configuration-defaults-and-overrides.md) — how the configuration layers merge, which this contract sits upstream of.-- [Drift Contracts](contribute/drift-contracts.md) — why the checks here are derived checks rather than review obligations: anything mechanizable becomes a derived check, and coverage, convergence, transform goldens and reserved-path checking all are.+- [Drift Contracts](contribute/drift-contracts.md) — why the checks here are derived checks rather than review obligations: anything mechanizable becomes a derived check, and coverage, convergence, transform goldens and reserved-path checking all are. The one part that is not mechanizable — [domain narrowing expressed in a validator](#the-fingerprint) — is a review obligation instead, and the `config-docs` contract carries these ledgers in its review list for it.diff --git a/docs/tools/cli/agent-cli.md b/docs/tools/cli/agent-cli.mdindex d53d27e90..a5ba9e3e6 100644--- a/docs/tools/cli/agent-cli.md+++ b/docs/tools/cli/agent-cli.md@@ -189,9 +189,9 @@ Do not confuse this setup-warning shape with the `warnings` array on the `validaFor the structured commands, exactly one such object is written to stderr per failure, so the stream parses as a single JSON document.-**`migration`** — a configuration error (`"error_domain": "config"`) carries an extra `migration` object when, and only when, a scan of this machine's configuration directories found something. Its presence is the whole signal: the configuration is *out of date* rather than wrong. It holds `remedy` (the command that fixes what can be fixed), `needs_attention` (whether something there is a person's decision rather than the tool's), and `plans` — one per file, in the same shape [`pipelex-agent migrate`](migrate.md) emits under its own `plans` key. The loop from there is `pipelex-agent migrate --dry-run --format json`, show the user what would change, then `--yes`. Never hand-edit a configuration file, and never answer this by re-initializing one — that discards every setting the migration would have kept.+**`migration`** — a configuration error (`"error_domain": "config"`) carries an extra `migration` object when, and only when, a scan of this machine's configuration directories found something. Its presence says the migration history has something to report about these files; **`would_write` says whether a command repairs them.** The object holds `remedy` (the command that fixes what can be fixed), `would_write` (whether running it would rewrite any of these files), `needs_attention` (whether something there is a person's decision rather than the tool's), and `plans` — one per file, in the same shape [`pipelex-agent migrate`](migrate.md) emits under its own `plans` key. On `would_write: true` the loop is `pipelex-agent migrate --dry-run --format json`, show the user what would change, then `--yes`. On `would_write: false` there is nothing to run: the plans carry a path no ledger entry explains, or an entry blocked before anything applied, and the command would visit the files, write nothing and leave the same error standing — so read the plans and correct what they name. Never answer either one by re-initializing a configuration file — that discards every setting the migration would have kept.-`TelemetryConfigValidationError` carries it too, on the same terms: present means the `telemetry.toml` is old, absent means it is wrong and the fields the message names are what to correct.+`TelemetryConfigValidationError` carries it too, on the same terms: absent means the `telemetry.toml` is wrong and the fields the message names are what to correct, present with `would_write: true` means it is old, and present with `would_write: false` means it is both reported on and unrepairable by the command.**A failure is not the only way to learn this, and for an agent it is not even the reliable one.** A configuration the migration history explains boots with a warning rather than an error — and `pipelex-agent` silences logging process-wide before anything can emit one, so no error arrives and the machine is still stale. `pipelex-agent doctor` is the channel that always answers: its `checks.pending_migrations` row carries a `finding` (`up_to_date`, `pending`, `needs_attention`, `unavailable`), the `migratable_files` a migration would rewrite, and the `attention_files` it will not repair on its own. Branch on `finding`; `unavailable` means the check could not run and is not a claim that the machine is current. The row answers for both configuration directories even under `--global`, because it describes `pipelex migrate`, which has no such flag.diff --git a/drift.toml b/drift.tomlindex 89e7be850..cf25fa5c4 100644--- a/drift.toml+++ b/drift.toml@@ -14,7 +14,13 @@version = 1[contracts.config-docs]-description = "User-facing configuration docs must track the config model and the shipped defaults."+description = """+User-facing configuration docs must track the config model and the shipped defaults, and a change \+to that model must be answered in the migration ledgers — including the domain narrowing no \+fingerprint can see, because it lives in a validator rather than in an annotation. The four live \+sites: KitConfig._validate_targets, DryRunConfig.validate_image_urls, \+ImgGenConfig.validate_quality_mapping, LLMConfig.validate_effort_to_budget_mapping.\+"""# The config model tree is rooted in system/configuration/ but several documented# submodels are defined in their own packages — they trigger too.triggers = [@@ -26,9 +32,25 @@ triggers = ["pipelex/tools/log/log_config.py","pipelex/pipelex.toml",]+# Three kinds of target, not one. The docs are the user-facing prose. The ledgers are where a+# shape change is answered, and the two source files are there because they hold the four+# validators above: a validator that narrows a value domain is semantic residue the fingerprint+# projection cannot record, so the coverage gate calls the change additive and the review list is+# the only place the obligation can land. Reviewing them means asking, of the change that opened+# this contract, whether it narrowed a domain, and if it did, whether an `unsafe` entry carrying+# `declared_narrowed_paths` is owed. See docs/migration-ledger.md § The fingerprint.+#+# Deliberately absent: pipelex/migration/goldens/. They are generator output (`make umig`), which+# a review list must never carry, and their staleness is already a derived check —+# `check-migration-schemas` fails on a head golden the models have moved past.review = ["docs/configuration/**/*.md",+ "pipelex/migration/ledgers/",+ "pipelex/system/configuration/configs.py",+ "pipelex/cogt/config_cogt.py",]+# `make tb` only. `check-ledger` and `check-migration-schemas` already gate `make check` and CI,+# so re-running them here would add the unstaged-file hard error without adding a guarantee.verify_commands = ["make tb"][contracts.cli-docs]diff --git a/mkdocs.yml b/mkdocs.ymlindex 7e9fabb37..096152560 100644--- a/mkdocs.yml+++ b/mkdocs.yml@@ -339,6 +339,7 @@ plugins:- contribute/hub-layering.md: "Hub Layering"- contribute/registration-surface.md: "Registration Surface"- contribute/drift-contracts.md: "Drift Contracts"+ - migration-ledger.md: "Migration Ledger"- changelog.md: "Changelog"markdown_extensions:@@ -379,13 +380,8 @@ extra_css:# gotchas) referenced from the root `CLAUDE.md`. They are built and searchable but# intentionally kept out of the user-facing nav so they don't clutter the reading# flow for human readers of the docs site.-# - `migration-ledger.md` is the configuration-migration contract, written ahead of the-# engine it specifies. It stays out of the nav until `pipelex migrate` and boot-# tolerance ship, so the reading flow never advertises a command that does not exist-# yet; move it into the Project section in the same change that ships them.not_in_nav: |CLAUDE.md- migration-ledger.mderrors/*.md!errors/index.md!errors/authoring-and-language.md@@ -587,6 +583,7 @@ nav:- Hub Layering: contribute/hub-layering.md- Registration Surface: contribute/registration-surface.md- Drift Contracts: contribute/drift-contracts.md+ - Migration Ledger: migration-ledger.md- Code of Conduct: CODE_OF_CONDUCT.md- License: license.md- Changelog: changelog.mddiff --git a/pipelex/base_exceptions.py b/pipelex/base_exceptions.pyindex b02c71ec1..4d1458d52 100644--- a/pipelex/base_exceptions.py+++ b/pipelex/base_exceptions.py@@ -354,6 +354,19 @@ class MigrationErrorBlock(BaseModel):remedy: str"""The command that applies whatever can be applied without a decision."""+ would_write: bool+ """Whether running ``remedy`` would actually rewrite any of these files.++ The block's *presence* says the migration history has something to report about this machine.+ It does not say the remedy repairs it, and this field is what separates the two. A block whose+ ``would_write`` is False carries a diagnosis and nothing to apply — a path no entry explains, a+ file that could not be read, an entry blocked before any of its operations landed — so naming+ ``remedy`` there would send a reader to a run that visits the files, writes nothing, and leaves+ the same refusal standing. The dry run is what carries the answer on that side.++ Independent of :attr:`needs_attention`, and the pair is never both False: a file with nothing to+ write and nothing for a person is clean, and clean files are not in ``plans``."""+needs_attention: bool"""Whether something here is a person's to resolve rather than the tool's — a blocked file, ablocked entry, or a path no ledger entry explains. When this is False, running ``remedy`` isdiff --git a/pipelex/cli/agent_cli/CLAUDE.md b/pipelex/cli/agent_cli/CLAUDE.mdindex e258e559e..853f63058 100644--- a/pipelex/cli/agent_cli/CLAUDE.md+++ b/pipelex/cli/agent_cli/CLAUDE.md@@ -97,13 +97,13 @@ commands/| `models` | Lists available model presets, aliases, and waterfalls. `--format markdown\|json` (success, default: markdown) + `--error-format markdown\|json` (errors, defaults to `--format`'s value) || `check-model` | Validates a model reference and suggests alternatives if invalid. `--type`/`-t` for model category, `--format markdown\|json` (success, default: markdown) + `--error-format markdown\|json` (errors, defaults to `--format`'s value) || `migrate` | Migrates this machine's configuration files (global `~/.pipelex/` and project `.pipelex/`, non-recursively) to the current schema by replaying each surface's ledger. Does **not** boot — it is the command for a configuration that cannot load. Writes only with `--yes`; `--dry-run` plans and is the default; the two together are refused with exit 2. `--format markdown\|json` (success, default: markdown) + `--error-format markdown\|json`. The verdict is the structured `needs_attention`, not the exit code. |-| `doctor` | Checks config, credentials, models health. `--global`/`-g` for global dir. `--format markdown\|json` (success, default: markdown) + `--error-format markdown\|json` (errors, defaults to `--format`'s value). The telemetry check carries a `finding` (`healthy`/`not_found`/`unparseable`/`out_of_date`/`invalid`) beside its `healthy` and `message`; branch on that, and note `out_of_date` is `pipelex migrate`'s and never `pipelex init telemetry`'s — a reset would discard the settings the migration keeps. `checks.pending_migrations` is the machine-wide half: a `finding` (`up_to_date`/`pending`/`needs_attention`/`unavailable`) plus `migratable_files` and `attention_files`. It is the only channel a machine has for a pending migration — a tolerated boot warns a person and this CLI silences logging — and it is **not** scoped by `--global`, because it answers for `pipelex migrate`, which walks both directories. |+| `doctor` | Checks config, credentials, models health. `--global`/`-g` for global dir. `--format markdown\|json` (success, default: markdown) + `--error-format markdown\|json` (errors, defaults to `--format`'s value). The telemetry check carries a `finding` (`healthy`/`not_found`/`unparseable`/`out_of_date`/`invalid`) beside its `healthy` and `message`; branch on that, and note `out_of_date` is `pipelex migrate`'s and never `pipelex init telemetry`'s — a reset would discard the settings the migration keeps — and that it means the migration would actually rewrite that file, so a file it would only report on is `invalid`. `checks.pending_migrations` is the machine-wide half: a `finding` (`up_to_date`/`pending`/`needs_attention`/`unavailable`) plus `migratable_files` and `attention_files`. It is the only channel a machine has for a pending migration — a tolerated boot warns a person and this CLI silences logging — and it is **not** scoped by `--global`, because it answers for `pipelex migrate`, which walks both directories. |## Key Patterns- **Output contract**: Commands with `--format` emit success via `agent_success_formatted(result, markdown_renderer, output_format)` — JSON or a markdown renderer per the explicit `output_format` argument. `agent_error(message, error_type, cause)` dispatches JSON or markdown by reading the `_agent_cli_error_format` ContextVar, which each `--format`-aware command sets via `set_agent_cli_error_format(error_format or output_format)` at function entry. Exceptions that print directly to stdout: `fmt`/`lint` (plxt passthrough), `concept`/`pipe` (raw TOML). Markdown renderers: `format_run_markdown` (`run/_output_helpers.py`), `format_validate_markdown` (lifted to the non-CLI `pipelex/pipeline/validation_render.py` so `pipelex-api` can import it without CLI/Typer deps), `format_fix_markdown` (non-CLI `pipelex/pipeline/fixes/fix_render.py`), `_format_init_markdown` (`init_cmd.py`).- **Error classification**: Each error type maps to a domain (`input`, `config`, `runtime`), a hint string, and a `retryable` flag. See `AGENT_ERROR_HINTS` dict in `agent_output.py`. The `error_domain` also drives the HTTP-status mapping for downstream APIs — see `error_domain_to_http_status()` in `pipelex/base_exceptions.py`.-- **The `migration` field on a configuration error**: A `PipelexConfigError` carries one when a scan of this machine's configuration directories found something — and only then, so its presence is the whole test. It says the configuration is *old* rather than *wrong*, and the loop it opens is `pipelex-agent migrate --dry-run --format json`, show the user, then `--yes`. Its `plans` are the same shape that command emits under its own `plans` key. `error_domain` stays `config`: a domain the hook specification does not know routes to BLOCK, which would stop an agent instead of telling it what to run. See `docs/migration-ledger.md` → "Reporting a stale configuration on a validation error".+- **The `migration` field on a configuration error**: A `PipelexConfigError` carries one when a scan of this machine's configuration directories found something — and only then, so its presence is the test for whether the migration history has anything to say. Whether a command *repairs* it is the separate `would_write` field: true means the configuration is *old*, and the loop is `pipelex-agent migrate --dry-run --format json`, show the user, then `--yes`; false means the block is a diagnosis its `plans` carry and the command would rewrite nothing, so branching on presence alone sends an agent to a run with nothing to do. Its `plans` are the same shape that command emits under its own `plans` key. `error_domain` stays `config`: a domain the hook specification does not know routes to BLOCK, which would stop an agent instead of telling it what to run. See `docs/migration-ledger.md` → "Reporting a stale configuration on a validation error".- **Init**: All commands that need Pipelex use `make_pipelex_for_agent_cli(library_dirs)`. It catches init errors and routes them through `agent_error()`.- **Async core**: Run and validate are async — commands use `asyncio.run()`.- **File convention**: Generated outputs go to `mthds-wip/` with incremental naming (`pipeline_01/`, `pipeline_02/`).diff --git a/pipelex/cli/agent_cli/commands/agent_output.py b/pipelex/cli/agent_cli/commands/agent_output.pyindex b73cdb473..19cb8df5c 100644--- a/pipelex/cli/agent_cli/commands/agent_output.py+++ b/pipelex/cli/agent_cli/commands/agent_output.py@@ -119,13 +119,17 @@ AGENT_ERROR_HINTS: dict[str, str] = {# Interpreter errors"MthdsParserError": "Check MTHDS file TOML syntax and ensure all referenced concepts and pipes are defined",# Configuration/initialization errors- # Two readings, and the `migration` field on this same payload is what separates them: present- # means the file is out of date, absent means it is wrong. Never `pipelex init telemetry` on- # the first — that writes a fresh file over settings a migration would have kept.+ # Three readings, and two fields on this same payload separate them: an absent `migration`+ # means the file is wrong, and a present one means the migration history has something to say+ # about it — `migration.would_write` then says whether a command repairs it or whether the+ # plans are a diagnosis to act on by hand. Never `pipelex init telemetry` on either of the+ # last two: that writes a fresh file over settings a migration would have kept."TelemetryConfigValidationError": (- "If this payload carries a 'migration' field, the configuration is out of date: run "- "'pipelex-agent migrate --dry-run --format json', then 'pipelex-agent migrate --yes'. "- "Otherwise correct the telemetry.toml settings named in the message."+ "If this payload carries a 'migration' field, read its 'would_write': true means the "+ "configuration is out of date and 'pipelex-agent migrate --yes' repairs it — run "+ "'pipelex-agent migrate --dry-run --format json' first to show the user what would change. "+ "False means the migration would write nothing and its 'plans' name what to correct by hand. "+ "Without a 'migration' field, correct the telemetry.toml settings named in the message."),"GatewayTermsNotAcceptedError": "Run 'pipelex init config' to accept gateway terms, or disable pipelex_gateway in backends.toml","GatewayApiKeyMissingError": "Set the PIPELEX_GATEWAY_API_KEY environment variable, or disable pipelex_gateway in backends.toml",diff --git a/pipelex/cli/commands/doctor_cmd.py b/pipelex/cli/commands/doctor_cmd.pyindex 6484b5da5..0802df014 100644--- a/pipelex/cli/commands/doctor_cmd.py+++ b/pipelex/cli/commands/doctor_cmd.py@@ -271,15 +271,15 @@ def _telemetry_is_out_of_date_or_wrong(*, validation_error: ValidationError, conexcept (MigrationError, OSError):report = Noneown_plan = next((plan for plan in report.plans if plan.file_path == config_path), None) if report is not None else None- if own_plan is not None and not own_plan.is_clean:+ if own_plan is not None and own_plan.did_change:return TelemetryConfigCheck(finding=TelemetryConfigFinding.OUT_OF_DATE,message=f"Configuration is out of date — run '{MIGRATE_COMMAND}' to bring it up to date",)- return TelemetryConfigCheck(- finding=TelemetryConfigFinding.INVALID,- message=f"Invalid configuration:\n{report_validation_error(validation_error=validation_error).message}",- )+ message = f"Invalid configuration:\n{report_validation_error(validation_error=validation_error).message}"+ if own_plan is not None and not own_plan.is_clean:+ message += f"\nThe migration found something here it will not do on its own — run '{MIGRATE_COMMAND} --dry-run' for the detail."+ return TelemetryConfigCheck(finding=TelemetryConfigFinding.INVALID, message=message)class PendingMigrationsFinding(StrEnum):@@ -707,20 +707,20 @@ def display_health_report(# Configuration Location sectionconsole.print("[bold]Configuration Location[/bold]")if config_location.is_project_local:- console.print(f" [green]✓[/green] Using project config: [cyan]{config_location.config_dir}[/cyan]")- console.print(f" [dim]Project root: {config_location.project_root}[/dim]")- console.print(f" [dim]Global config: {config_location.global_config_dir}[/dim]")+ console.print(f" [green]✓[/green] Using project config: [cyan]{escape(config_location.config_dir)}[/cyan]")+ console.print(f" [dim]Project root: {escape(str(config_location.project_root))}[/dim]")+ console.print(f" [dim]Global config: {escape(config_location.global_config_dir)}[/dim]")else:- console.print(f" [green]✓[/green] Using global config: [cyan]{config_location.config_dir}[/cyan]")+ console.print(f" [green]✓[/green] Using global config: [cyan]{escape(config_location.config_dir)}[/cyan]")console.print(" [dim]No project .pipelex/ directory found[/dim]")console.print()# Configuration Files sectionconsole.print("[bold]Configuration Files[/bold]")if config_healthy:- console.print(f" [green]✓[/green] {config_message}")+ console.print(f" [green]✓[/green] {escape(config_message)}")else:- console.print(f" [red]✗[/red] {config_message}")+ console.print(f" [red]✗[/red] {escape(config_message)}")console.print()# Configuration Migrations section. It sits next to Configuration Files because it is about@@ -740,27 +740,27 @@ def display_health_report(# Backend Credentials sectionconsole.print("[bold]Backend Credentials[/bold]")if backends_healthy:- console.print(f" [green]✓[/green] {backends_message}")+ console.print(f" [green]✓[/green] {escape(backends_message)}")elif not backend_credential_reports:# No backends were checked (e.g., file not found)- console.print(f" [red]✗[/red] {backends_message}")+ console.print(f" [red]✗[/red] {escape(backends_message)}")else:- console.print(f" [yellow]⚠[/yellow] {backends_message}")+ console.print(f" [yellow]⚠[/yellow] {escape(backends_message)}")console.print()# Show details for each backendbad_backend_credential_reports: dict[str, BackendCredentialsReport] = {}for backend_name, backend_credential_report in backend_credential_reports.items():if backend_credential_report.all_credentials_valid:- console.print(f" [dim]{backend_name}[/dim]")+ console.print(f" [dim]{escape(backend_name)}[/dim]")console.print(" [green]✓[/green] All credentials set")else:bad_backend_credential_reports[backend_name] = backend_credential_report- console.print(f" [bold]{backend_name}[/bold]")+ console.print(f" [bold]{escape(backend_name)}[/bold]")if backend_credential_report.missing_vars:- console.print(f" [red]✗[/red] Missing: {', '.join(backend_credential_report.missing_vars)}")+ console.print(f" [red]✗[/red] Missing: {escape(', '.join(backend_credential_report.missing_vars))}")if backend_credential_report.placeholder_vars:- console.print(f" [yellow]⚠[/yellow] Placeholders: {', '.join(backend_credential_report.placeholder_vars)}")+ console.print(f" [yellow]⚠[/yellow] Placeholders: {escape(', '.join(backend_credential_report.placeholder_vars))}")error_msg = BackendCredentialsErrorMsgFactory.make_comprehensive_error_msg(backend_credential_reports=bad_backend_credential_reports)console.print(error_msg)@@ -769,13 +769,13 @@ def display_health_report(# Models sectionconsole.print("[bold]Models[/bold]")if models_healthy:- console.print(f" [green]✓[/green] {models_message}")+ console.print(f" [green]✓[/green] {escape(models_message)}")elif models_skipped:# Skipped reads as advisory, not failure — the Config Files row is the real issue.- console.print(f" [yellow]⚠[/yellow] {models_message}")+ console.print(f" [yellow]⚠[/yellow] {escape(models_message)}")console.print(" [dim]Models check deferred until config errors are fixed.[/dim]")else:- console.print(f" [red]✗[/red] {models_message}")+ console.print(f" [red]✗[/red] {escape(models_message)}")# Show details for backend file issues if anyif backend_file_reports:@@ -783,7 +783,7 @@ def display_health_report(if invalid_backends:console.print()for backend_name, backend_file_report in invalid_backends.items():- console.print(f" [bold]{backend_name}[/bold]")+ console.print(f" [bold]{escape(backend_name)}[/bold]")if backend_file_report.has_kit_template:console.print(" [yellow]⚠[/yellow] Backend configuration format may be outdated")console.print(" [dim]Template available for replacement[/dim]")@@ -793,21 +793,21 @@ def display_health_report(if backend_file_report.error_message:# Show first line of errorerror_lines = backend_file_report.error_message.split("\n")- console.print(f" [dim]{error_lines[0][:100]}[/dim]")+ console.print(f" [dim]{escape(error_lines[0][:100])}[/dim]")console.print()# Model Deck sectionconsole.print("[bold]Model Deck[/bold]")if deck_healthy:- console.print(f" [green]✓[/green] {deck_message}")+ console.print(f" [green]✓[/green] {escape(deck_message)}")else:- console.print(f" [yellow]⚠[/yellow] {deck_message}")+ console.print(f" [yellow]⚠[/yellow] {escape(deck_message)}")# Per-file detail when there are pending actionsactionable_statuses = {name: status for name, status in deck_report.files.items() if status != DeckFileStatus.UP_TO_DATE}if actionable_statuses:for filename in sorted(actionable_statuses):status = actionable_statuses[filename]- console.print(f" [dim]{filename}[/dim] — {status_rich_label(status)}")+ console.print(f" [dim]{escape(filename)}[/dim] — {status_rich_label(status)}")console.print()# Recommended actions@@ -884,7 +884,7 @@ def display_health_report(console.print(f" • Run [cyan]{MIGRATE_COMMAND}[/cyan] to bring telemetry.toml up to date")if has_telemetry_validation_error:- console.print(f" • Fix validation errors in [cyan]{config_location.config_dir}/telemetry.toml[/cyan]")+ console.print(f" • Fix validation errors in [cyan]{escape(config_location.config_dir)}/telemetry.toml[/cyan]")if has_deck_drift:console.print(" • Run [cyan]pipelex update[/cyan] to refresh the model deck from the current kit")@@ -903,9 +903,8 @@ def display_health_report(if has_custom_backend_issues:invalid_custom = [name for name, report in backend_file_reports.items() if not report.is_valid and not report.has_kit_template]for backend_name in invalid_custom:- console.print(- f" • Manually fix backend configuration in [cyan]{config_location.config_dir}/inference/backends/{backend_name}.toml[/cyan]"- )+ backend_file = f"{escape(config_location.config_dir)}/inference/backends/{escape(backend_name)}.toml"+ console.print(f" • Manually fix backend configuration in [cyan]{backend_file}[/cyan]")if not backends_healthy and backend_credential_reports:# Collect all missing and placeholder vars@@ -920,12 +919,12 @@ def display_health_report(if all_missing_vars:console.print(" • Set the following environment variables:")for var_name in sorted(all_missing_vars):- console.print(f" - {var_name}")+ console.print(f" - {escape(var_name)}")if all_placeholder_vars:console.print(" • Replace placeholder values for:")for var_name in sorted(all_placeholder_vars):- console.print(f" - {var_name}")+ console.print(f" - {escape(var_name)}")console.print()@@ -1169,7 +1168,7 @@ def doctor_cmd(except Exception as exc: # noqa: BLE001# Handle unexpected errors gracefully without printing tracesconsole.print()- console.print(f"[red]✗ Unexpected error: {exc!s}[/red]")+ console.print(f"[red]✗ Unexpected error: {escape(str(exc))}[/red]")console.print()console.print("[dim]If you need help:[/dim]")console.print(" [cyan]https://docs.pipelex.com[/cyan] - Documentation")@@ -1298,7 +1297,7 @@ def do_doctor_cmd(console.print("[green]✓[/green] Configuration files installed")except Exception as exc: # noqa: BLE001# Doctor --fix handler: wraps the whole init_cmd sub-command; a fix failure is reported and the doctor run continues.- console.print(f"[red]Failed to install configuration files: {exc!s}[/red]")+ console.print(f"[red]Failed to install configuration files: {escape(str(exc))}[/red]")console.print()# Migrate the configuration files the ledger can carry forward. This runs the same write@@ -1317,7 +1316,7 @@ def do_doctor_cmd(console.print("[dim]Re-run[/dim] [cyan]pipelex doctor[/cyan] [dim]for an updated report.[/dim]")except Exception as exc: # noqa: BLE001# Doctor --fix handler: wraps the whole migration pass; a fix failure is reported and the doctor run continues.- console.print(f"[red]Failed to migrate configuration files: {exc!s}[/red]")+ console.print(f"[red]Failed to migrate configuration files: {escape(str(exc))}[/red]")console.print()# Fix a missing telemetry config@@ -1329,7 +1328,7 @@ def do_doctor_cmd(console.print("[green]✓[/green] Telemetry configured")except Exception as exc: # noqa: BLE001# Doctor --fix handler: wraps the whole init_cmd sub-command; a fix failure is reported and the doctor run continues.- console.print(f"[red]Failed to configure telemetry: {exc!s}[/red]")+ console.print(f"[red]Failed to configure telemetry: {escape(str(exc))}[/red]")console.print()# Fix outdated model deck@@ -1341,7 +1340,7 @@ def do_doctor_cmd(console.print("[green]✓[/green] Model deck updated")except Exception as exc: # noqa: BLE001# Doctor --fix handler: wraps the whole update_cmd sub-command; a fix failure is reported and the doctor run continues.- console.print(f"[red]Failed to update deck: {exc!s}[/red]")+ console.print(f"[red]Failed to update deck: {escape(str(exc))}[/red]")console.print()# Fix outdated backend files@@ -1350,8 +1349,8 @@ def do_doctor_cmd(console.print()for backend_name, backend_file_report in fixable_backends:- console.print(f" Backend: [cyan]{backend_name}[/cyan]")- console.print(f" File: [dim]{backend_file_report.file_path}[/dim]")+ console.print(f" Backend: [cyan]{escape(backend_name)}[/cyan]")+ console.print(f" File: [dim]{escape(backend_file_report.file_path)}[/dim]")console.print(" [yellow]⚠[/yellow] Configuration format may be outdated")console.print()@@ -1363,15 +1362,15 @@ def do_doctor_cmd(resolved_config_dir = Path(backend_file_report.file_path).parent.parent.parentsuccess = replace_backend_file(backend_name, dry_run=False, config_dir=resolved_config_dir)if success:- console.print(f"[green]✓[/green] Replaced {backend_name} backend configuration")+ console.print(f"[green]✓[/green] Replaced {escape(backend_name)} backend configuration")else:- console.print(f"[red]Failed to replace {backend_name}: Template not found or copy failed[/red]")+ console.print(f"[red]Failed to replace {escape(backend_name)}: Template not found or copy failed[/red]")except Exception as exc: # noqa: BLE001# Doctor --fix handler: wraps replace_backend_file; a fix failure is reported and the doctor run continues.- console.print(f"[red]Failed to replace {backend_name}: {exc!s}[/red]")+ console.print(f"[red]Failed to replace {escape(backend_name)}: {escape(str(exc))}[/red]")console.print()else:- console.print(f"[dim]Skipped {backend_name}[/dim]")+ console.print(f"[dim]Skipped {escape(backend_name)}[/dim]")console.print()# Handle issues that can't be auto-fixed@@ -1383,9 +1382,9 @@ def do_doctor_cmd(# Config validation errorsif has_config_validation_error:console.print("[bold]Configuration validation error:[/bold]")- console.print(f" {config_message}")+ console.print(f" {escape(config_message)}")console.print()- console.print(f"You can fix this manually by editing [cyan]{config_location.config_dir}/pipelex.toml[/cyan]")+ console.print(f"You can fix this manually by editing [cyan]{escape(config_location.config_dir)}/pipelex.toml[/cyan]")console.print("or run [cyan]pipelex init config[/cyan] to regenerate from template.")console.print()@@ -1396,7 +1395,7 @@ def do_doctor_cmd(console.print("[bold]Telemetry validation error:[/bold]")console.print(f" {escape(telemetry_check.message)}")console.print()- console.print(f"You can fix this manually by editing [cyan]{config_location.config_dir}/telemetry.toml[/cyan]")+ console.print(f"You can fix this manually by editing [cyan]{escape(config_location.config_dir)}/telemetry.toml[/cyan]")console.print("or run [cyan]pipelex init telemetry[/cyan] to start the file over, discarding what is in it.")console.print()@@ -1416,7 +1415,7 @@ def do_doctor_cmd(# Show .env file syntax firstconsole.print("[dim]# In your .env file:[/dim]")for var_name in sorted(all_missing_vars):- console.print(f"{var_name}=[yellow]your_value_here[/yellow]")+ console.print(f"{escape(var_name)}=[yellow]your_value_here[/yellow]")console.print()# Show shell syntax for different platforms@@ -1426,19 +1425,19 @@ def do_doctor_cmd(# Linux/MacOSconsole.print("[dim]# Linux/MacOS[/dim]")for var_name in sorted(all_missing_vars):- console.print(f"export {var_name}=[yellow]your_value_here[/yellow]")+ console.print(f"export {escape(var_name)}=[yellow]your_value_here[/yellow]")console.print()# Windows PowerShellconsole.print("[dim]# Windows PowerShell[/dim]")for var_name in sorted(all_missing_vars):- console.print(f'$env:{var_name}="[yellow]your_value_here[/yellow]"')+ console.print(f'$env:{escape(var_name)}="[yellow]your_value_here[/yellow]"')console.print()# Windows CMDconsole.print("[dim]# Windows CMD[/dim]")for var_name in sorted(all_missing_vars):- console.print(f"set {var_name}=[yellow]your_value_here[/yellow]")+ console.print(f"set {escape(var_name)}=[yellow]your_value_here[/yellow]")console.print()sys.exit(1)diff --git a/pipelex/cli/error_handlers.py b/pipelex/cli/error_handlers.pyindex c491c7f72..7a925ef05 100644--- a/pipelex/cli/error_handlers.py+++ b/pipelex/cli/error_handlers.py@@ -427,9 +427,15 @@ def handle_telemetry_config_validation_error(exc: TelemetryConfigValidationErrorconsole.print(escape(exc.message))console.print()- if exc.migration is not None:+ if exc.migration is not None and exc.migration.would_write:console.print(f"[bold green]💡 To fix:[/bold green] Run [cyan]{exc.migration.remedy}[/cyan] to bring your configuration up to date\n")console.print("[dim]The migration keeps every setting in the file — it does not start it over.[/dim]")+ elif exc.migration is not None:+ # A block whose `would_write` is False is a diagnosis, not a repair: the command would visit+ # this file, write nothing, and leave the same refusal standing. What the reader needs is the+ # dry run's detail and their own editor.+ console.print("[bold green]💡 To fix:[/bold green] Correct the settings named above in [cyan]telemetry.toml[/cyan]\n")+ console.print(f"[dim]Run [cyan]{exc.migration.remedy} --dry-run[/cyan] for what the migration found — it would rewrite nothing here.[/dim]")else:console.print("[bold green]💡 To fix:[/bold green] Correct the settings named above in [cyan]telemetry.toml[/cyan]\n")console.print("[dim]Or run [cyan]pipelex init telemetry[/cyan] to start the file over — this discards what is in it.[/dim]")diff --git a/pipelex/core/validation.py b/pipelex/core/validation.pyindex a7ebc5f4c..6718fc3f5 100644--- a/pipelex/core/validation.py+++ b/pipelex/core/validation.py@@ -133,7 +133,12 @@ def _pending_migration(*, surface_id: str, config_dirs: list[Path] | None) -> Miplans = [plan for plan in report.plans if not plan.is_clean]if not plans:return None- return MigrationErrorBlock(remedy=MIGRATE_COMMAND, needs_attention=report.needs_attention, plans=plans)+ return MigrationErrorBlock(+ remedy=MIGRATE_COMMAND,+ would_write=any(plan.did_change for plan in plans),+ needs_attention=report.needs_attention,+ plans=plans,+ )def _migration_prose(*, block: MigrationErrorBlock) -> str:@@ -144,16 +149,35 @@ def _migration_prose(*, block: MigrationErrorBlock) -> str:is attached to a failure rather than to a boot that carried on. Everything it names comes fromthe ledger or from a file path: **no value read from a user's file appears here**, which isthe third of the three channels that rule covers.++ **The paragraph opens and closes on `would_write`, never on the block's presence.** A block+ means the migration history has something to say about these files; only `would_write` means+ the command would change them. Telling a reader to run a migration over a file it would not+ touch is a sentence whose honest outcome is *nothing was written*, with their error still in+ front of them — so on that side the paragraph says so and points at the dry run, which is where+ the diagnosis is. And when the command would write but the paragraph has just listed what it+ cannot do, the closing sentence says both, rather than promising a repair the list above has+ already qualified."""files = ", ".join(f"'{plan.file_path}'" for plan in block.plans)carried = sorted({step.title for plan in block.plans for step in plan.steps})- sentences = [f"Your configuration may be out of date rather than wrong: {files}."]+ if block.would_write:+ sentences = [f"Your configuration may be out of date rather than wrong: {files}."]+ else:+ sentences = [f"The migration history has something to say about these files: {files}."]if carried:sentences.append(f"What `{block.remedy}` would carry forward: {'; '.join(carried)}.")unresolved = _what_needs_a_person(plans=block.plans)if unresolved:sentences.append(f"What it cannot do for you: {'; '.join(unresolved)}.")- sentences.append(f"Run `{block.remedy}` to bring these files up to date.")+ if block.would_write and unresolved:+ sentences.append(f"Run `{block.remedy}` to carry forward what it can; the rest is yours to fix.")+ elif block.would_write:+ sentences.append(f"Run `{block.remedy}` to bring these files up to date.")+ else:+ sentences.append(+ f"`{block.remedy}` would rewrite nothing here — run `{block.remedy} --dry-run` to read what it found, and fix these files by hand."+ )return " ".join(sentences)diff --git a/tests/unit/pipelex/cli/test_doctor_config_checks.py b/tests/unit/pipelex/cli/test_doctor_config_checks.pyindex c11071f94..e1f1f31b9 100644--- a/tests/unit/pipelex/cli/test_doctor_config_checks.py+++ b/tests/unit/pipelex/cli/test_doctor_config_checks.py@@ -312,3 +312,30 @@ class TestDoctorConfigChecks:assert check.finding is TelemetryConfigFinding.INVALIDassert "custom_posthog.mode" in check.messageassert MIGRATE_COMMAND not in check.message++ def test_check_telemetry_config_calls_a_file_with_nothing_to_apply_invalid_rather_than_out_of_date(self, tmp_path: Path) -> None:+ """`out_of_date` is a promise that a command repairs this file, so it has to be one.++ The probe used to read *not clean* as *out of date*, which made a file whose only finding is+ a key no build knows about `out_of_date` — and the row then offered `pipelex migrate`, a run+ that visits the file, writes nothing, and leaves the same refusal behind. That file is not+ old; it is wrong in a way the ledger happens to have something to say about, and `invalid`+ is where it belongs, because that is the finding that routes to a person.+ """+ (tmp_path / TELEMETRY_CONFIG_FILE_NAME).write_text('[custom_posthog]\nmode = "off"\nnot_a_telemetry_setting = true\n', encoding="utf-8")++ check = check_telemetry_config(config_dir=tmp_path)++ assert check.finding is TelemetryConfigFinding.INVALID+ assert check.finding.is_repaired_by_initializing is False+ assert f"{MIGRATE_COMMAND} --dry-run" in check.message, "the diagnosis the scan found must not be lost with the finding"+ assert f"run '{MIGRATE_COMMAND}'" not in check.message++ def test_check_telemetry_config_still_calls_a_file_the_ledger_carries_forward_out_of_date(self, tmp_path: Path) -> None:+ """The other side of the same branch, so a fix that simply stopped reporting staleness is red."""+ (tmp_path / TELEMETRY_CONFIG_FILE_NAME).write_text('telemetry_mode = "off"\nproject_api_key = "key"\n', encoding="utf-8")++ check = check_telemetry_config(config_dir=tmp_path)++ assert check.finding is TelemetryConfigFinding.OUT_OF_DATE+ assert MIGRATE_COMMAND in check.messagediff --git a/tests/unit/pipelex/cli/test_doctor_display_report.py b/tests/unit/pipelex/cli/test_doctor_display_report.pyindex a0ce2397b..6e48c976d 100644--- a/tests/unit/pipelex/cli/test_doctor_display_report.py+++ b/tests/unit/pipelex/cli/test_doctor_display_report.py@@ -66,6 +66,13 @@ def _healthy_report_kwargs() -> dict[str, Any]:}+#: A directory name that is legal on every filesystem and is also Rich's opening delimiter.+BRACKETED_DIR = "/work/[dev]/project/.pipelex"++#: A closing tag: markup Rich cannot balance, which raises rather than swallowing.+CLOSING_TAG = "unknown key '[/b]' in section"++class TestDoctorDisplayReport:@pytest.fixturedef console(self, mocker: MockerFixture) -> Console:@@ -346,3 +353,98 @@ class TestDoctorDisplayReport:output = console.export_text()assert "✗ Unexpected error: totally unexpected" in outputassert "https://go.pipelex.com/discord" in output++ # --- Every dynamic field survives Rich markup ---+ # A bracket in a path or a message is data, and the report has to print it as data. Rich reads+ # `[...]` in a printed string as markup: a path segment like `[dev]` is silently dropped from+ # the output, and a `[/x]` sequence raises `MarkupError` and takes the whole report down. Every+ # row here interpolates something that comes from the user's filesystem, their configuration,+ # or an exception's text, so each one is a place that can happen — and the failure is worst+ # exactly when the report matters most, since the fields carrying brackets are the ones+ # quoting what went wrong.++ def test_a_bracketed_config_directory_is_printed_whole(self, console: Console) -> None:+ kwargs = _healthy_report_kwargs()+ kwargs["config_location"] = ConfigLocationInfo(+ config_dir=BRACKETED_DIR,+ is_project_local=True,+ project_root="/work/[dev]/project",+ global_config_dir="/home/[user]/.pipelex",+ )++ display_health_report(**kwargs)++ output = console.export_text()+ assert BRACKETED_DIR in output+ assert "Project root: /work/[dev]/project" in output+ assert "Global config: /home/[user]/.pipelex" in output++ @pytest.mark.parametrize(+ "field_name",+ ["config_message", "backends_message", "models_message", "deck_message"],+ )+ def test_a_closing_tag_in_a_row_message_neither_raises_nor_vanishes(self, console: Console, field_name: str) -> None:+ """Each of the four rows that interpolate a message built elsewhere, including one that+ embeds the pydantic analysis of the user's own configuration.+ """+ kwargs = _healthy_report_kwargs()+ kwargs[field_name] = f"Configuration validation failed: {CLOSING_TAG}"+ kwargs[field_name.replace("_message", "_healthy")] = False++ display_health_report(**kwargs)++ assert CLOSING_TAG in console.export_text()++ def test_a_bracketed_backend_name_survives_the_credentials_detail(self, console: Console) -> None:+ """Backend names are table keys in the user's `backends.toml`, so they are user data too."""+ kwargs = _healthy_report_kwargs()+ kwargs["backends_healthy"] = False+ kwargs["backends_message"] = "1 backend(s) have credential issues"+ kwargs["backend_credential_reports"] = {+ "my[test]backend": BackendCredentialsReport(+ backend_name="my[test]backend",+ required_vars=["MY[dev]_API_KEY"],+ missing_vars=["MY[dev]_API_KEY"],+ placeholder_vars=[],+ all_credentials_valid=False,+ )+ }++ display_health_report(**kwargs)++ output = console.export_text()+ assert "my[test]backend" in output+ assert "MY[dev]_API_KEY" in output++ def test_a_bracketed_deck_filename_survives_the_per_file_detail(self, console: Console) -> None:+ kwargs = _healthy_report_kwargs()+ kwargs["deck_healthy"] = False+ kwargs["deck_message"] = "Deck has pending updates"+ kwargs["deck_report"] = DeckSyncReport(+ kit_version="1.2.0",+ installed_kit_version="1.1.0",+ manifest_present=True,+ files={"llm_deck[old].toml": DeckFileStatus.CLEAN_BEHIND},+ )++ display_health_report(**kwargs)++ assert "llm_deck[old].toml" in console.export_text()++ def test_a_bracketed_backend_error_survives_the_models_detail(self, console: Console) -> None:+ kwargs = _healthy_report_kwargs()+ kwargs["models_healthy"] = False+ kwargs["models_message"] = "Backend configuration errors"+ kwargs["backend_file_reports"] = {+ "openai": BackendFileReport(+ backend_name="openai",+ file_path="/work/[dev]/backends/openai.toml",+ is_valid=False,+ error_message=CLOSING_TAG,+ has_kit_template=False,+ )+ }++ display_health_report(**kwargs)++ assert CLOSING_TAG in console.export_text()diff --git a/tests/unit/pipelex/cli/test_doctor_fix_mode.py b/tests/unit/pipelex/cli/test_doctor_fix_mode.pyindex 0859ab9dc..61ac3a958 100644--- a/tests/unit/pipelex/cli/test_doctor_fix_mode.py+++ b/tests/unit/pipelex/cli/test_doctor_fix_mode.py@@ -276,6 +276,29 @@ class TestDoctorFixMode:assert "OPENAI_API_KEY=your_value_here" in outputassert "export OPENAI_API_KEY=your_value_here" in output+ def test_manual_fixes_print_a_bracketed_credential_name_on_every_platform(self, doctor_mocks: dict[str, Any]) -> None:+ """A variable name is data from the user's `backends.toml`; each of the four platform lines must print it whole.++ Rich reads `[TEST]` as markup and eats it, so a line that forgets to escape the name prints+ `MY_API_KEY` — a value the user cannot set — or raises and takes the whole guidance down.+ """+ credentials_report = BackendCredentialsReport(+ backend_name="my_backend",+ required_vars=["MY[dev]_API_KEY"],+ missing_vars=["MY[dev]_API_KEY"],+ placeholder_vars=[],+ all_credentials_valid=False,+ )+ doctor_mocks["backends"].return_value = (False, {"my_backend": credentials_report}, "1 backend(s) have missing or invalid credentials")++ self._run_doctor_expecting_exit_one()++ output = doctor_mocks["console"].export_text()+ assert "MY[dev]_API_KEY=your_value_here" in output+ assert "export MY[dev]_API_KEY=your_value_here" in output+ assert '$env:MY[dev]_API_KEY="your_value_here"' in output+ assert "set MY[dev]_API_KEY=your_value_here" in output+def test_fix_mode_with_all_healthy_exits_zero(self, doctor_mocks: dict[str, Any]) -> None:"""With everything healthy, fix mode exits 0 without prompting."""with pytest.raises(SystemExit) as exc_info:diff --git a/tests/unit/pipelex/cli/test_error_handlers_more.py b/tests/unit/pipelex/cli/test_error_handlers_more.pyindex b5a48682f..ac78d4500 100644--- a/tests/unit/pipelex/cli/test_error_handlers_more.py+++ b/tests/unit/pipelex/cli/test_error_handlers_more.py@@ -236,7 +236,7 @@ class TestErrorHandlersExtended:"""exc = TelemetryConfigValidationError("extra forbidden field: 'telemetry_mode'",- migration=MigrationErrorBlock(remedy=MIGRATE_COMMAND, needs_attention=False, plans=[]),+ migration=MigrationErrorBlock(remedy=MIGRATE_COMMAND, would_write=True, needs_attention=False, plans=[]),)with pytest.raises(typer.Exit) as exc_info:@@ -248,6 +248,27 @@ class TestErrorHandlersExtended:assert "does not start it over" in outputassert "init telemetry" not in output+ def test_handle_telemetry_config_validation_error_on_a_file_the_migration_would_not_write(self, console: Console) -> None:+ """A block is not a promise that a command repairs the file.++ The block's presence used to be the whole branch, so a file whose only finding is a path no+ entry explains was answered with *run `pipelex migrate` to bring your configuration up to+ date* — a run that visits the file, writes nothing, and leaves this same error behind.+ """+ exc = TelemetryConfigValidationError(+ "extra forbidden field: 'not_a_telemetry_setting'",+ migration=MigrationErrorBlock(remedy=MIGRATE_COMMAND, would_write=False, needs_attention=True, plans=[]),+ )++ with pytest.raises(typer.Exit) as exc_info:+ handle_telemetry_config_validation_error(exc)++ assert exc_info.value.exit_code == 1+ output = console.export_text()+ assert "Correct the settings named above" in output+ assert f"{MIGRATE_COMMAND} --dry-run" in output+ assert "init telemetry" not in output, "a file the migration cannot repair is still never answered with a reset"+def test_handle_gateway_terms_not_accepted_error(self, console: Console) -> None:"""The terms handler points at init config and the BYOK alternative."""with pytest.raises(typer.Exit) as exc_info:diff --git a/tests/unit/pipelex/core/test_validation_report.py b/tests/unit/pipelex/core/test_validation_report.pyindex c61affecb..d8cf1631c 100644--- a/tests/unit/pipelex/core/test_validation_report.py+++ b/tests/unit/pipelex/core/test_validation_report.py@@ -352,3 +352,73 @@ class TestNoValueFromAUsersFileIsEverRendered:)assert self.PLANTED_SECRET not in report.messageassert self.PLANTED_SECRET not in json.dumps(report.migration.model_dump(mode="json"))+++class TestARemedyIsNamedOnlyWhereItWouldWrite:+ """`would_write` — the field that separates *there is something to say* from *this repairs it*.++ A block's presence means the migration engine had something to report about these files. It+ does not mean the remedy would rewrite them: a file whose only finding is a path no entry+ explains, or an entry blocked before any of its operations landed, produces a block with+ nothing to apply. Naming the command there sends a reader to a run that writes nothing and+ leaves the error exactly where it was — which is the failure this field exists to prevent.+ """++ def test_a_file_the_ledger_carries_forward_would_be_written(self, machine: Path) -> None:+ machine.joinpath("telemetry.toml").write_text(_old_shape_telemetry_document(), encoding="utf-8")++ report = report_validation_error(validation_error=_make_validation_error(), surface_id=TELEMETRY_CONFIG_SURFACE_ID)++ assert report.migration is not None+ assert report.migration.would_write is True+ assert f"Run `{MIGRATE_COMMAND}` to bring these files up to date." in report.message++ def test_a_file_with_nothing_to_apply_is_sent_to_the_dry_run_instead(self, machine: Path) -> None:+ """The specimen the old wording got wrong: `pipelex-config` ships an entry-free ledger, so an+ unknown root key is the whole finding and there is not one operation behind it.+ """+ machine.joinpath("pipelex.toml").write_text("not_a_real_setting = true\n", encoding="utf-8")++ report = report_validation_error(validation_error=_make_validation_error(), surface_id=PIPELEX_CONFIG_SURFACE_ID)++ assert report.migration is not None+ assert report.migration.would_write is False+ assert f"Run `{MIGRATE_COMMAND}` to bring these files up to date." not in report.message+ assert f"{MIGRATE_COMMAND} --dry-run" in report.message+ assert "by hand" in report.message++ def test_a_block_that_would_write_nothing_and_needs_nobody_is_unreachable(self, machine: Path) -> None:+ """The invariant that lets a reader treat the two flags as an exhaustive pair.++ A plan is in the block only when it is not clean, and a plan that is not clean carries at+ least one of a step, an applied operation under a blocked entry, a blocked entry, a path no+ entry explains, or a file that could not be read — the first two make `would_write` true and+ the rest make `needs_attention` true. Both specimens are checked, since between them they+ cover both sides of the pair.+ """+ machine.joinpath("telemetry.toml").write_text(f"{_old_shape_telemetry_document()}\nnot_a_real_setting = true\n", encoding="utf-8")++ report = report_validation_error(validation_error=_make_validation_error(), surface_id=TELEMETRY_CONFIG_SURFACE_ID)++ assert report.migration is not None+ assert report.migration.would_write, "the flat body is carried forward"+ assert report.migration.needs_attention, "and the unknown key beside it is nobody's but a person's"++ def test_a_file_that_is_both_old_and_wrong_is_not_promised_a_full_repair(self, machine: Path) -> None:+ """The mixed case: the command would write, and something would still be there afterwards.++ `would_write` picks the opening and closing sentences, and this specimen is on its true side —+ but the closing sentence used to promise that the run brings the files up to date, over a+ file whose unknown key it will not touch. The paragraph has just listed what the command+ cannot do; its last sentence must not take that back.+ """+ machine.joinpath("telemetry.toml").write_text(f"{_old_shape_telemetry_document()}\nnot_a_real_setting = true\n", encoding="utf-8")++ report = report_validation_error(validation_error=_make_validation_error(), surface_id=TELEMETRY_CONFIG_SURFACE_ID)++ assert report.migration is not None+ assert report.migration.would_write is True+ assert "'not_a_real_setting', which this build knows nothing about" in report.message+ assert f"Run `{MIGRATE_COMMAND}` to bring these files up to date." not in report.message+ assert f"Run `{MIGRATE_COMMAND}` to carry forward what it can" in report.message+ assert "yours to fix" in report.messagediff --git a/tests/unit/pipelex/system/telemetry/test_telemetry_stale_remedy.py b/tests/unit/pipelex/system/telemetry/test_telemetry_stale_remedy.pyindex 86348b08d..e4039bd5a 100644--- a/tests/unit/pipelex/system/telemetry/test_telemetry_stale_remedy.py+++ b/tests/unit/pipelex/system/telemetry/test_telemetry_stale_remedy.py@@ -140,3 +140,30 @@ class TestNoValueFromAUsersFileIsEverRendered:assert PLANTED_KEY not in exc.messageassert exc.migration is not Noneassert PLANTED_KEY not in str(exc.migration.model_dump(mode="json"))+++class TestTheRemedyIsNamedOnlyWhereItWouldWrite:+ """A block says the migration history has something to report; it does not say a command fixes it.++ The two specimens below produce the same structured shape — a block, on a `telemetry.toml` that+ refused — and the same command would do opposite things to them. One is rewritten and repaired;+ the other is read, left untouched, and still refuses afterwards.+ """++ def test_a_file_the_ledger_carries_forward_is_told_to_run_the_command(self, global_dir: Path) -> None:+ exc = load_and_capture(config_dir=global_dir, body=f"{old_shape_document()}\n{UNKNOWN_KEY} = true\n")++ assert exc.migration is not None+ assert exc.migration.would_write is True+ # The specimen is both old and wrong, so the command is named for what it carries forward+ # and the unknown key is left where it belongs — with a person.+ assert f"Run `{MIGRATE_COMMAND}` to carry forward what it can; the rest is yours to fix." in exc.message++ def test_a_file_with_nothing_to_apply_is_told_to_read_the_dry_run(self, global_dir: Path) -> None:+ """An unknown root key on a file that is otherwise current: a finding without a single step."""+ exc = load_and_capture(config_dir=global_dir, body=f'[custom_posthog]\nmode = "off"\n{UNKNOWN_KEY} = true\n')++ assert exc.migration is not None+ assert exc.migration.would_write is False+ assert f"Run `{MIGRATE_COMMAND}` to bring these files up to date." not in exc.message+ assert f"{MIGRATE_COMMAND} --dry-run" in exc.messagediff --git a/wip/migrator-phase3-progress.md b/wip/migrator-phase3-progress.mdindex b52247f39..278a78b73 100644--- a/wip/migrator-phase3-progress.md+++ b/wip/migrator-phase3-progress.md@@ -17,7 +17,9 @@ Record all three numbers against S6.`make agent-check` and the full `make agent-test` are both green on the branch as pushed.-⚠ **S6 is well past half.** The pre-S7 bucket is closed (part 1, on `dev`), and on `feature/Migrator-3b` the two `migrate` commands (milestone 5), the downgrade diagnosis (milestone 6), boot tolerance (milestone 7), the validation-error report (milestone 8), the telemetry-remedy retirement (milestone 9) and the `doctor` pending-migrations row with `--fix` (milestone 10) are all built. What remains is the rest of the phase body — the drift-contract review list, the skills, the specs rows, and publishing the contract — as **part 3**, on a fresh branch after #1114 merges. See [What is actually left](#what-is-actually-left) at the bottom before planning a session.+✅ **S6 part 3 is complete and up for review — PR [#1115](https://github.com/Pipelex/pipelex/pull/1115), `feature/Migrator-3c` → `dev`, head `b1f3102ae` after the review pass.** Items 6–9 of [What is actually left](#what-is-actually-left) are Milestones 11–14; the two parked #1114 review items that were routed to part 3 are Milestones 15 (§2, *a remedy is named only where it would write*) and 16 (§4, the doctor's unescaped Rich fields). `agent-check`, `agent-test`, `cmig`, `docs-check` and `check-spec-links` all green. One companion change lands in a **different repo** — Milestone 13 is pushed on `feature/Migrator` in the workspace-root repo, with no PR of its own. **The bot review pass on #1115 is executed** (Codex, Greptile, Cubic — one round, ten threads, all answered and resolved; the fixes are the fourth commit, *"answer the PR #1115 review"*, and the one item deferred is in [`migrator-pr-1115-review-followups.md`](./migrator-pr-1115-review-followups.md), a repo-wide test-layout decision rather than a migrator item). Every required check is green on the head and the merge state is clean. **⏸ C is not reached**: it waits on #1115 being merged, since its cold-start checks read the files off `dev`.++**S6's three parts are all built.** The pre-S7 bucket is on `dev` (part 1, #1113); the two `migrate` commands (milestone 5), the downgrade diagnosis (milestone 6), boot tolerance (milestone 7), the validation-error report (milestone 8), the telemetry-remedy retirement (milestone 9) and the `doctor` pending-migrations row with `--fix` (milestone 10) are on `dev` (part 2, #1114); the drift-contract review list, the two skills, the spec section, the published contract and the two parked #1114 items (milestones 11–16) are part 3, #1115, reviewed and waiting for the merge. What follows the merge is not on this branch: ⏸ C's cold-start check in the runbook, then S7. See [What is actually left](#what-is-actually-left) at the bottom for the small items that ride with whoever next touches their module.## Build order chosen for this session@@ -622,12 +624,42 @@ The phase body the charter lists under **Do**, in the order the next session sho3. ~~**`report_validation_error` on the real plan**~~ — done, see Milestone 8. The third channel of the rendering-rule test landed with it, as a new e2e class (`TestABootFailureCarriesThePendingMigration`) rather than inside `TestNoValueFromAUsersFileIsEverRendered`, because the reachable specimen is different: boot tolerance means a file the ledger *can* explain never reaches the error surface at all, so the channel is exercised by a key no entry explains, whose value is the planted secret.4. ~~**The two telemetry remedies retired**~~ — done, see Milestone 9. There were four, and the worst of them was `doctor --fix`'s offer to reset a migratable file. The third surface, `pipelex_service_config.py`, was deliberately left alone — it has no wrong remedy to retire, and closing its gap costs the same models/loader split.5. ~~**`doctor`: the pending-migrations row and `--fix`**~~ — done, see Milestone 10. Both halves: a row that is `pipelex migrate`'s own dry run across every surface, and fix mode reaching the command's write pass (not the command, which exits). The row deliberately takes no directory — it answers for a command that has no `--global`.-6. **The `config-docs` drift contract's `review` list** plus the four validator sites R8 names (`KitConfig._validate_targets`, `DryRunConfig.validate_image_urls`, `ImgGenConfig.validate_quality_mapping`, `LLMConfig.validate_effort_to_budget_mapping`).-7. **The skills**: `.claude/skills/add-migration/`, and `/release` step 3b.-8. **`docs/specs/command-surface-map.md` rows** — that file is in the **workspace-root** repo, not this one.-9. **Publish the contract**: delete `docs/migration-ledger.md`'s Status banner, remove its `not_in_nav` entry and comment, add a Migration Ledger row to the nav's Project section.+6. ~~**The `config-docs` drift contract's `review` list**~~ — done, see Milestone 11.+7. ~~**The skills**~~ — done, see Milestone 12.+8. ~~**`docs/specs/command-surface-map.md` rows**~~ — done, see Milestone 13 (workspace-root repo, uncommitted there).+9. ~~**Publish the contract**~~ — done, see Milestone 14.++~~Then the part-3 PR to `dev` from `feature/Migrator-3c`~~ — opened as [#1115](https://github.com/Pipelex/pipelex/pull/1115). Checkpoint C follows its merge.++### Part 3 — Milestones 11 to 14 (uncommitted on `feature/Migrator-3c`)++**Milestone 11 — the `config-docs` drift contract's review list (item 6).** `drift.toml`'s `config-docs` contract now reviews three kinds of target, not one: `docs/configuration/**/*.md` as before, plus `pipelex/migration/ledgers/` and the two modules holding R8's four validator sites (`pipelex/system/configuration/configs.py`, `pipelex/cogt/config_cogt.py`). The `description` names the four qualnames, because `drift plan` prints the description and the review paths and prints no comments — a site named only in a TOML comment reaches nobody at review time. **Two rulings taken here.** *The goldens are deliberately NOT in the review list*, against the tracker's own parenthetical: `docs/contribute/drift-contracts.md` bars generated artifacts from a review list, `make umig` generates them, and their staleness is already the derived check `check-migration-schemas` — which is the tier the drift doc says such a relationship belongs to. `plan.md` says "the ledger files", and the ledgers are the hand-authored half. *No verify command was added* — `check-ledger` and `check-migration-schemas` already gate `make check` and CI, so re-running them under the ack would add the unstaged-file hard error without adding a guarantee (the same reasoning the `hub-layering-convention` contract records). The contract was reviewed and acked for real: `make cl` and `make cmig` both green, no trigger file moved, nothing owed. Two docs moved with it — `docs/migration-ledger.md` now says where the "author's responsibility" for validator-expressed narrowing is *declared*, and `docs/contribute/drift-contracts.md` gained a paragraph saying a review target does not have to be prose, with the bar (a person reads and judges it; never something a command regenerates).++**Milestone 12 — the two skills (item 7).** `.claude/skills/add-migration/SKILL.md` is written. Its spine is one rule — *derive the entry from the gate's refusal, never from memory* — then: read what `cl`/`cmig` say (with a table mapping the issue kinds that mean **an entry is owed** to what it owes, explicitly not the whole kind list), decide `safe` vs `unsafe`, write the two edits to the ledger, handle the reserved-path rule, `make umig` and read its diff, prove with `cl`/`cmig`, add the `**Migration:**` changelog bullet. It also states what it must never do (hand-edit a golden, widen a check, reuse a retired name, put a value in an operation) and carries the `pre_history` special case. `/release` gained **step 3b** between the quality checks and the branch cut: `make check-migration-schemas` blocks the release, a failure routes to `add-migration`, and on a pass it diffs `pipelex/migration/ledgers/` against `origin/main` to confirm a `**Migration:**` bullet and a correct `introduced_in` for every new breaking entry — plus the note that a breaking entry makes the release a minor bump. The Files-touched list and the Important-details list were updated to match.++**Milestone 13 — `docs/specs/command-surface-map.md` (item 8), in the workspace-root repo.** A new `## Configuration migration surface` section rather than rows in the master table, following the precedent the codegen family set — the master table is indexed by hop in the *validate* chain and migrate has no hook, no `mthds-agent` command and no HTTP route. The section carries a chain block for `[M] pipelex migrate`, `[Ma] pipelex-agent migrate` and `[Md] pipelex doctor --fix`, a two-row table with the same columns as the master one, the `needs_attention`-is-the-verdict sentence, the no-user-values rule, and an `<!-- unverified -->` marker explaining why this family is not in `conformance/` (it acts on the invoking machine's own configuration directories). One correction the spec now states rather than overclaiming: `mthds-agent migrate` is **not** a registered command, but under the pipelex runner it still reaches `pipelex-agent migrate` through hop 3's unknown-command passthrough, and under `--runner api` it is an `ArgumentError` — a fallback, not a surface. The front matter's `sources:` gained both command modules. `make check-spec-links` in `conformance/` is **green** (the CLAUDE.md note about 35 issues is stale — the pair is passing today). ⚠ **This change is uncommitted in the workspace-root repo on branch `feature/Migrator`**, a different repo from this branch.++**Milestone 14 — publishing the contract (item 9).** `docs/migration-ledger.md` lost its Status banner, `mkdocs.yml` lost the `migration-ledger.md` line from `not_in_nav` and the comment block explaining when to move it, and the page gained a `Migration Ledger` row in the nav's Project section beside `Drift Contracts`. A trap worth recording: `mkdocs.yml` contains **two** structures that look like a nav — the real `nav:` at the bottom, and the `llmstxt-md` plugin's `sections:` map several hundred lines above it, whose entries have the same `- path.md: "Title"` shape. The row was added to both (the llms.txt listing wants it too), and `make docs-check` is what caught that the first one was not the nav. Docs build clean under `--strict`.++### Milestone 15 — the §2 ruling, built++**The ruling.** *A remedy is named only where it would write.* The presence of a `migration` block means the migration engine has something to say about these files — **not** that the remedy would rewrite them. What separates the two is a field, not a sentence: `MigrationErrorBlock` carries **`would_write: bool`** (`any(plan.did_change for plan in plans)`), and every surface that used to name `pipelex migrate` on the block's mere presence now branches on it, pointing at the **dry run** where nothing would be written, because the dry run is what actually carries the answer. This is Milestone 10's ruling one step along — *a fix is offered only where a command would actually write* — and Milestone 9's — *a probe's verdict is a field its callers branch on, never a sentence they search*. The two flags are independent and never both false: a file with nothing to write and nothing for a person is clean, and clean files are not in `plans`.-Then the part-3 PR to `dev` from `feature/Migrator-3c`, and Checkpoint C.+**Where it landed — five surfaces, not the four the follow-up named.** (1) `pipelex/base_exceptions.py` — the field with its docstring. (2) `pipelex/core/validation.py` — `_pending_migration` computes it, and `_migration_prose` swaps both its opening and its closing sentence on it. When `would_write` is false the "what it would carry forward" sentence is absent by construction, since `carried` reads `plan.steps` and a plan with steps changes. (3) `pipelex/cli/commands/doctor_cmd.py` — `_telemetry_is_out_of_date_or_wrong` branches on `own_plan.did_change` rather than `not own_plan.is_clean`, so a file the migration would only report on falls to `INVALID` (which routes to Manual Fixes and is what `--fix` declines to offer a command for), and the `INVALID` message gains the `--dry-run` pointer **only when a scan actually found something** — a genuinely wrong file gets no pointer, which is what keeps `test_check_telemetry_config_invalid_new_format_names_the_field`'s `MIGRATE_COMMAND not in message` true. (4) `pipelex/cli/agent_cli/commands/agent_output.py` — the hint is now three-way and tells the agent to read `migration.would_write` off the payload it already holds rather than to run a command to learn it. (5) **`pipelex/cli/error_handlers.py`, which the follow-up did not name** — the human telemetry handler had exactly the same `if exc.migration is not None:` shape and is the surface a person actually reads; it now has three arms, and the middle one keeps "never offer `init telemetry`" while sending the reader to the dry run.++**The docs that would otherwise have disagreed with the CLI.** `docs/migration-ledger.md` — the structured-block bullet lists the field, a new blockquote states the rule, the three per-surface bullets under "Every surface reports it the same way" are rewritten three-way, and the `doctor`-row bullet now says `out_of_date` means the plan would rewrite that file. `docs/tools/cli/agent-cli.md` and `pipelex/cli/agent_cli/CLAUDE.md` — both said presence was "the whole signal" and sent an agent to `migrate --yes` from it. The `cli-docs` drift contract opened on the three `pipelex/cli/**` edits and was reviewed and acked; `docs/tools/cli/migrate.md` needed nothing, since it describes the command and the `pending_migrations` row and neither moved.++**Changelog.** Folded into the two existing `[Unreleased]` bullets rather than added as a new one — the block has never shipped without `would_write`, so a bullet describing a fix to it would be describing a fix to something no user has seen.++**Tests, written first and red before the code.** `TestARemedyIsNamedOnlyWhereItWouldWrite` in `tests/unit/pipelex/core/test_validation_report.py` (both sides plus the never-both-false invariant on a specimen that is both at once), `TestTheRemedyIsNamedOnlyWhereItWouldWrite` in `tests/unit/pipelex/system/telemetry/test_telemetry_stale_remedy.py` (the same pair through the real loader), `TestTheTelemetryRowNamesMigrateOnlyWhereItWouldWrite` in `tests/unit/pipelex/cli/test_doctor_config_checks.py` (including the regression guard that a genuinely stale file is *still* `out_of_date`), and the would-not-write arm of the human handler in `test_error_handlers_more.py`.++### Milestone 16 — §4, the doctor's unescaped Rich fields++The last parked #1114 item. `display_health_report` printed nearly every dynamic value straight through Rich's markup parser: a `[dev]` path segment was silently dropped and an unbalanced `[/b]` raised `MarkupError` and took the whole report down — and the fields most likely to carry brackets are the ones quoting what went wrong, so the report failed hardest exactly when it mattered. One pass now escapes the four row messages (`config_message` embeds `report_validation_error(...).message`, which quotes the user's own keys), every path off `ConfigLocationInfo`, backend names, environment-variable names, deck filenames, the first line of a backend file's error, and `str(exc)` at each site the `--fix` pass reports one. Two things deliberately stay raw: `status_rich_label(status)`, which returns markup on purpose, and the module constant `MIGRATE_COMMAND`.++**One residual, recorded rather than half-fixed.** `console.print(error_msg)` prints `BackendCredentialsErrorMsgFactory.make_comprehensive_error_msg(...)`, a plain-string builder that already hardcodes a Rich `\[` in one of its lines — escaping it at the print site would render that as a literal backslash. It is the same layer question §4 already ruled on for `stale_configuration_warning`: a builder whose consumers include non-Rich sinks cannot escape for one of them.++`TestEveryDynamicFieldSurvivesRichMarkup` covers it with the recorded-console pattern, and each assertion was mutation-tested — the escape reverted, the test watched go red, the escape restored.### Deferred from the #1114 review@@ -646,9 +678,7 @@ The items the review-bot pass on PR #1114 raised and this branch parked rather t- **The rescue-copy race** (`pr-1113-review-notes.md` §3): a third run's prune can take the `.bak.` a rescue is about to rename. The commands now make concurrent runs producible, so this is decidable — revisit as an age-sparing prune, not a lock.- Deliberately past S7's freeze, with named triggers, in `pr-1113-review-notes.md` and `migrator-write-scope-and-rename-fidelity.md`: per-member bounds in the golden, the `safe`-entry sibling, the tomlkit raw-storage staleness pass, rename fidelity (§2), the taken-backup-name report, and the residual. §1 of the write-scope note is **closed** by Milestone 5.-**The next session — part 3, on `feature/Migrator-3c` — starts at item 6, the `config-docs` drift contract's `review` list.** Everything that touches *code* in the phase body is now built — items 1 through 5, on `dev` once #1114 merges — and what is left is four items of a different kind: a contract's review list (item 6), two skills (item 7), a spec file in the **workspace-root** repo (item 8), and publishing the ledger contract in the nav (item 9). None of them depends on another, so they can be taken in any order; item 6 is the cheapest and item 9 is the one that closes the phase.--Item 6 concretely: extend `drift.toml`'s `config-docs` contract so its `review` list also covers the ledger files (`pipelex/migration/goldens/`, the ledgers themselves) and the four validator sites R8 names — `KitConfig._validate_targets`, `DryRunConfig.validate_image_urls`, `ImgGenConfig.validate_quality_mapping`, `LLMConfig.validate_effort_to_budget_mapping`. R8's point is that a validator is a schema change the fingerprint cannot see, so a change to one is a review obligation the same way a model field is.+✅ **Part 3 is done, over two sessions.** Session 1 built items 6 through 9 (Milestones 11–14), committed as *"the review obligation, the two skills, and publishing the contract"*. Session 2 built the two parked #1114 review items routed here — Milestone 15 (§2) and Milestone 16 (§4) — committed as *"a remedy is named only where it would write, and the doctor stops eating brackets"*. Both are pushed as [#1115](https://github.com/Pipelex/pipelex/pull/1115), and a third, shorter session answered its bot review — the last unescaped doctor line, the closing sentence of the migration paragraph, the `add-migration` closing rule, the `/release` ledger-diff baseline, and the two test modules folded back to one class each — committed as *"answer the PR #1115 review"* (head `b1f3102ae`). One item is deferred, in [`migrator-pr-1115-review-followups.md`](./migrator-pr-1115-review-followups.md): whether the one-TestClass-per-module rule holds against the narrative multi-class layout that predates this PR in two of the touched modules and dozens more — a repo-wide decision, not this branch's. Nothing is left on this branch; ⏸ C waits on the merge.Milestone 7's inherited finding — the dead `except ValidationError` around `setup_config` — **is fixed**, at both of that function's config-side callers, and the same defect turned out to exist in the doctor.diff --git a/wip/migrator-pr-1114-review-followups.md b/wip/migrator-pr-1114-review-followups.mdindex eac4c8ad6..cf4e299d5 100644--- a/wip/migrator-pr-1114-review-followups.md+++ b/wip/migrator-pr-1114-review-followups.md@@ -12,7 +12,7 @@ An embedder's `Pipelex.make(config_dir=…)` outside `~/.pipelex/` and the proje**Recommendation:** when the first `pipelex-config` entry ships, have `stale_configuration_warning` take the walked directories and, for a stale file outside them, say "this file is outside `pipelex migrate`'s reach — update it where it lives" instead of naming the command. Do **not** add `pipelex migrate --config-dir`: `check_pending_migrations` deliberately takes no directory so the doctor row can never name a command that then rewrites a file it did not mention. This sits beside `migrator-write-scope-and-rename-fidelity.md`, which parks the sibling question of writing outside the walk.-## 2. What the presence of a `migration` block means when the plan is unexplained-only+## 2. What the presence of a `migration` block means when the plan is unexplained-only — **RESOLVED on `feature/Migrator-3c`****Reporter:** Cubic (`agent_output.py`, the `TelemetryConfigValidationError` hint) — [thread](https://github.com/Pipelex/pipelex/pull/1114#discussion_r3792679317).@@ -20,7 +20,9 @@ An embedder's `Pipelex.make(config_dir=…)` outside `~/.pipelex/` and the proje**Why deferred:** the hint faithfully implements a documented contract — `docs/tools/cli/agent-cli.md` ("Its presence is the whole signal: the configuration is *out of date* rather than wrong") and `docs/migration-ledger.md` → "Reporting a stale configuration on a validation error" say the same — and `_migration_prose` ends the human message with the same unconditional "run `pipelex migrate`". Rewording the hint alone would leave the CLI and its spec disagreeing. This is one ruling over four surfaces: what "presence" means, or whether the block should carry (or the hint should point at) "is there anything the command would write" as distinct from "is there anything a person must look at". The `--dry-run` the hint sends the agent to does print the unexplained note ("either the name is a typo, or this file was written by a newer pipelex"), so the wasted round trip is the whole harm.-The doctor's telemetry row is a further surface of the same ruling ([thread](https://github.com/Pipelex/pipelex/pull/1114#discussion_r3792785607), which reported the sibling-file bug that was fixed): `_telemetry_is_out_of_date_or_wrong` now reads the plan of the file the row is about, but still branches on `not plan.is_clean`, so an unexplained-only file — a typo under `extra="forbid"` — reads `out_of_date`, names `pipelex migrate` (which writes nothing), and suppresses the manual-fixes section. Whatever "presence" is ruled to mean, that row follows.+The doctor's telemetry row is a further surface of the same ruling ([thread](https://github.com/Pipelex/pipelex/pull/1114#discussion_r3792785607), which reported the sibling-file bug that was fixed): `_telemetry_is_out_of_date_or_wrong` read the plan of the file the row is about, but branched on `not plan.is_clean`, so an unexplained-only file — a typo under `extra="forbid"` — read `out_of_date`, named `pipelex migrate` (which writes nothing), and suppressed the manual-fixes section.++**The ruling, taken and built in part 3:** *a remedy is named only where it would write.* `MigrationErrorBlock` carries a `would_write: bool` (`any(plan.did_change for plan in plans)`), presence keeps meaning only *the migration history has something to say about these files*, and every surface branches on the field: the agent hint, the human handler in `error_handlers.py` (a fifth surface, which this section did not name and which had the identical shape), `_migration_prose`'s opening and closing sentences, and the doctor row, whose `out_of_date` now requires `own_plan.did_change` so an unexplained-only file falls to `invalid` and reaches Manual Fixes with the dry run's pointer. The three docs that stated the old contract moved with it. See `wip/migrator-phase3-progress.md` → Milestone 15.## 3. The service-configuration loader still warns directly, and two commands load it before logging exists@@ -30,15 +32,17 @@ The main configuration's warning is now parked on the loader and emitted after `**Recommendation:** when either ledger gains an entry, a `StaleConfigurationWarning(UserWarning)` raised through `warnings.warn` on the `RemoteConfigStaleWarning` pattern (`pipelex_service/exceptions.py`, captured by the agent CLI factory) covers all three loaders and every entry point uniformly, at the cost of a second presentation channel. Not worth building against an empty ledger.-## 4. Pre-existing unescaped Rich fields in the doctor report+## 4. Pre-existing unescaped Rich fields in the doctor report — **RESOLVED on `feature/Migrator-3c`****Surfaced by:** Cubic's two escape findings on `doctor_cmd.py` — [thread](https://github.com/Pipelex/pipelex/pull/1114#discussion_r3792679312), [thread](https://github.com/Pipelex/pipelex/pull/1114#discussion_r3792679315).-The telemetry row and the pending-migrations row now escape what they print (this PR is what put user-file content into the telemetry message). `config_message`, `backends_message`, `models_message` and `deck_message` in `display_health_report` (and the Manual-Fixes block) still interpolate unescaped, and `config_message` embeds `report_validation_error(...).message` too. A bracketed path segment is silently dropped by Rich and a `[/x]` sequence raises `MarkupError`.+The telemetry row and the pending-migrations row escaped what they printed (PR #1114 is what put user-file content into the telemetry message); everything else in `display_health_report` interpolated raw. Rich reads `[...]` in a printed string as markup, so a path segment like `[dev]` was silently dropped and a `[/x]` sequence raised `MarkupError` and took the whole report down — worst exactly when the report matters most, since the fields carrying brackets are the ones quoting what went wrong.++**Done in part 3.** One pass over the whole function and the fix-mode and Manual-Fixes blocks it owns: the four row messages (`config_message`, which embeds `report_validation_error(...).message`, plus `backends_message`, `models_message`, `deck_message`), every path off `ConfigLocationInfo`, backend names, environment-variable names, deck filenames, the first line of a backend file's error, and the `str(exc)` of every caught exception the fix mode reports. `status_rich_label(status)` is deliberately **not** escaped — it returns markup on purpose — and neither are the module constant `MIGRATE_COMMAND` nor an `int`. `TestEveryDynamicFieldSurvivesRichMarkup` in `test_doctor_display_report.py` covers it with the recorded-console pattern, using a bracketed directory and an unbalanced `[/b]`; each assertion was mutation-tested by reverting its escape and watching it go red.-**Recommendation:** one pass over `display_health_report` escaping every dynamic field, with the recorded-console test pattern from `test_doctor_display_report.py`. Small, mechanical, and outside this PR's scope.+**One residual, and it is at the builder layer rather than here.** `console.print(error_msg)` prints `BackendCredentialsErrorMsgFactory.make_comprehensive_error_msg(...)`, which already hardcodes a Rich `\[` in one line — so escaping it at the print site would render that as a literal backslash. It carries dynamic backend names, and its correct fix is the same shape as the `stale_configuration_warning` one this section already ruled the wrong layer: a plain-string builder whose consumers include non-Rich sinks cannot escape for one of them. Left alone deliberately.-Cubic raised it again in the second round for `config_message` specifically (this PR routes `report_validation_error(...).message` into it) and, in the same run, asked for the paths in `stale_configuration_warning` (`config_surface.py`) to be escaped. The second one is the wrong layer: that function is a plain-string builder whose consumers are `log.warning` — which feeds a `RichHandler(markup=True)` under `is_markup_enabled` *and* a plain `StreamHandler` in `POOR` mode — and two Rich render sites that already `escape()`; a `\[`-escaped string is corrupt in the poor sink, and no builder in the tree escapes (`core/validation.py` builds the identical list unescaped). The residual is a property of the log channel — every logged path or exception text across the codebase is interpreted as markup — and its one correct home, if it is ever wanted, is the rich branch of the log dispatch, not the builders.+Cubic raised the escaping again in the second round for `config_message` specifically (this PR routes `report_validation_error(...).message` into it) and, in the same run, asked for the paths in `stale_configuration_warning` (`config_surface.py`) to be escaped. The second one stays refused, on the layer argument: that function is a plain-string builder whose consumers are `log.warning` — which feeds a `RichHandler(markup=True)` under `is_markup_enabled` *and* a plain `StreamHandler` in `POOR` mode — and two Rich render sites that already `escape()`; a `\[`-escaped string is corrupt in the poor sink, and no builder in the tree escapes (`core/validation.py` builds the identical list unescaped). The residual is a property of the log channel — every logged path or exception text across the codebase is interpreted as markup — and its one correct home, if it is ever wanted, is the rich branch of the log dispatch, not the builders.## 5. A file declaring a version below the floor still boots when its body validatesdiff --git a/wip/migrator-pr-1115-review-followups.md b/wip/migrator-pr-1115-review-followups.mdnew file mode 100644index 000000000..d6925458f--- /dev/null+++ b/wip/migrator-pr-1115-review-followups.md@@ -0,0 +1,13 @@+# Migrator Phase 3, part 3 — items deferred from the PR #1115 review++What the review-bot pass on [PR #1115](https://github.com/Pipelex/pipelex/pull/1115) surfaced and this branch did **not** fix, with why. The confirmed items were fixed on the branch: the doctor's PowerShell credential line was the one platform example still printing a variable name through Rich's markup parser (its regression test uses a lowercase bracket segment, because Rich only reads a tag that starts with a lowercase letter, `#`, `/` or `@` — an uppercase `[TEST]` is inert and proves nothing); the `add-migration` skill's closing rule forbade "any value in an operation", which would have told an agent to mark an entry `unsafe` whose `remap_value` mapping is exactly the safe repair the skill's own table asks for; the `/release` skill's ledger diff was baselined on `origin/main`, which is empty when the skill is invoked from `main`, and now uses the previous release's tag; the two test modules this PR turned multi-class were folded back to one class each; and the migration paragraph on a validation error, in the case where the command would write *and* something it cannot repair sits in the same files, closes on "carry forward what it can; the rest is yours to fix" rather than promising the files come out up to date. Two of Cubic's items were false positives and are answered on the thread: `.claude/settings.json`'s allow list only skips prompts (an unlisted `make umig` prompts, it is not blocked, like every other skill's targets), and the closing "fix these files by hand" on a file the command would not touch does not contradict the below-floor guidance, which the same paragraph's "What it cannot do for you" sentence carries verbatim — and no surface has a floor above zero today.++## 1. The one-TestClass-per-module rule against the narrative multi-class layout++**Reporter:** Codex (`tests/unit/pipelex/cli/test_doctor_config_checks.py`, and by extension `test_doctor_display_report.py`, `core/test_validation_report.py`, `system/telemetry/test_telemetry_stale_remedy.py`) — [thread](https://github.com/Pipelex/pipelex/pull/1115#discussion_r3792986025).++`AGENTS.md` says one TestClass per module, and this PR broke it in four modules. Two of them (`test_doctor_config_checks.py`, `test_doctor_display_report.py`) had one class before the PR, and the branch folded the new tests back into it. The other two — `tests/unit/pipelex/core/test_validation_report.py` and `tests/unit/pipelex/system/telemetry/test_telemetry_stale_remedy.py` — were already multi-class before this PR, laid out as one class per concern with a narrative name (`TestNoValueFromAUsersFileIsEverRendered`, `TestTheRemedyIsNamedOnlyWhereItWouldWrite`), and the PR's added class followed each file's own layout. Dozens of modules across `tests/` are laid out the same way.++**Why deferred:** reworking modules whose layout predates the PR is not a review fix, and the two directions are genuinely different decisions. Either the rule holds — and those modules are split into one file per class (a mechanical sweep, but a large diff touching many modules the migrator work never opened) — or the narrative one-class-per-concern layout is accepted for a module that tests one seam from several angles, and `AGENTS.md` (which is generated — edit the source, not the file) is relaxed to say so.++**Recommendation:** decide once, repo-wide, rather than per PR. If the rule holds, sweep the two migrator modules first since they are the ones this branch touched, then the rest in a `chore/` PR of its own. Until then, a new test in an already multi-class module should follow that module's layout — mixing both styles in one file is the worst outcome.