@pipefy/pipefy-process-coder 0.1.0

package/AGENTS.md

@@ -0,0 +1,456 @@
+# AGENTS.md — working on pipefy-process-coder
+
+Read this before changing anything. It is the accumulated cost of getting this
+tool wrong in specific ways, written down so the next agent does not pay it again.
+
+---
+
+## 1. What this is, and what it is for
+
+`pipe` is a CLI that pulls a Pipefy pipe — **and its iPaaS flows** — to disk as
+readable JSON, lets you edit the files, diffs them, compiles the diff into API
+calls, applies them, and verifies the result.
+
+```
+pipe pull <pipeId> --out ./my-pipe   # the pipe AND its iPaaS flows
+# edit the JSON
+pipe validate                     # shape + referential integrity, offline
+pipe diff                         # what changed — pipe structure and flows
+pipe plan --dry-run               # is every change applicable? refuses if not
+pipe apply                        # snapshot, apply step by step, verify, adopt
+```
+
+**The app is the deliverable.** Whatever pipes appear in `workspaces/` are
+*fixtures* — they exist to exercise the tool against a real endpoint, and they are
+gitignored for a reason. Do not optimise for a good-looking pipe. A fixture change
+that exercises an untested path is worth making; one that only makes the fixture
+nicer is not.
+
+The tool's job is to make a client's process **auditable and changeable as code**,
+on a laptop, against an API that lies in specific documented ways. It is built for
+an FDE working on someone else's Pipefy account, which is why every write is
+planned, refusable and verified.
+
+Specific ids appear in two places on purpose: `VALIDATION.md` and the run logs
+under `workspaces/*/flows/BUILD-LOG.md` are **records of real runs** kept locally
+and outside git, and an id
+there is evidence. Everywhere else — source comments, help text, these docs, the
+skills — ids are placeholders, because a general tool should not read as though it
+were written for one customer.
+
+---
+
+## 2. The one rule that matters most
+
+**Build through the app. Validate with the MCP afterwards.**
+
+When `pipe` cannot do something you need, the answer is to *add it to `pipe`* —
+not to reach for the Pipefy MCP, not to write a script in `research/` that does
+the write for you. Routing around a gap hides exactly the gap that was worth
+finding: the work looks finished and the tool is no better than before.
+
+- A blocker met with a workaround teaches nothing.
+- A blocker met by extending the app is the whole job.
+- A limitation of the **platform** is worth reporting. A limitation of the **app**
+  is worth fixing.
+
+The Pipefy MCP is for *independent verification after the build* — a different
+transport and a different code path, which makes it a genuine second opinion. Use
+`ap_validate_flow`, `ap_flow_structure`, `get_pipe`, `execute_graphql` to check
+what the app did. Never to do it.
+
+Anything that writes to a client's pipe belongs in `src/`, behind a command, with
+a plan step and a verify. `research/` holds reads and probes.
+
+Three probes there *do* write, because that is how the operation model and the
+connection shapes were learned. Each refuses to run without `PIPE_PROBE_WRITES=1`,
+and the reason is in §4. Do not add a fourth to get past a gap in the app.
+
+---
+
+## 3. The doctrines that make this trustworthy
+
+These are not style. Each one exists because its absence caused a live incident.
+
+### Coverage: absence is not absence
+
+Every entity group carries `complete | partial | unknown`. An `unknown` group
+means the read path could not see it — **not** that the pipe has none. Such a
+group is never diffed and never applied.
+
+This is the difference between "this pipe has no webhooks" and "I cannot read
+webhooks", and conflating them licenses deleting a client's live integrations.
+Applies to iPaaS flows identically: a pipe whose iPaaS is off gets `unknown`, and
+its flows are not compared at all.
+
+### Refuse rather than guess, per column
+
+`src/apply/registry.ts` records, for every entity and operation, whether a write
+path exists — and `settableColumns` records which *columns* it can actually
+write. `pipe plan` refuses what has no path, naming the reason.
+
+The failure this prevents: **a mutation that succeeds and changes nothing.**
+Arguments are filtered against the live schema, so an argument the mutation has no
+input for is silently dropped and the call returns success. `updatePipe` did this
+with `description`, `anyone_can_create_card` and `create_card_label`. A workspace
+that set one could never converge, and nothing said why.
+
+### Round trip or it does not ship
+
+`pack(unpack(P)) == P` for the payload codec, `link(unlink(F)) == F` for the flow
+codec. The payload fold is *movement only*, which makes it true by construction;
+the flow fold is a real transformation, so `test/flow-codec.test.ts` earns it
+across a linear chain, a router with an empty branch, a loop with a body, a router
+nested in a loop, and the live flows.
+
+If you add a fold, prove it the same way or keep the raw JSON.
+
+### Verify against intent, not identity
+
+After an apply, the tool reads the pipe back and diffs `live → expected` with
+`intentOnly`. An authored entity is a *partial specification*: the author writes
+what they care about and the server fills the rest. Asking "are these rows
+identical" fails a perfectly correct apply.
+
+Never assert a column the server mints and no create path accepts — `uuid`,
+`slug`, `color_uuid`, `suid`. That mistake reported 60 successful creates as
+failures.
+
+### Nothing leaves carrying a placeholder
+
+A new entity has no id, so a reference to it is `%{_new:<uuid>}`, substituted at
+send time from `IdMap`. `ID_BEARING_KEYS` governs which keys get a bare-value
+substitution, and the executor **refuses to send any request still containing
+`_new:`**, naming the key path.
+
+That list has been the cause of three separate bugs — `fieldConditionIds`, then
+`phase[jump_target_ids][]`. When you add a key that holds an id, add it there.
+
+### The create response already has the id — a read-back is not the only way to learn it
+
+`IdMap` is built live during `execute.ts`, straight from each create mutation's
+own response, to resolve `%{_new:<uuid>}` for later steps in the same run. That
+map is also enough to adopt a created entity's id into the workspace file it
+came from (`apply/adopt.ts`) — no live read-back needed, and by construction
+never wrong, because it is the id the mutation that created the entity actually
+returned.
+
+This is why `pipe apply` no longer snapshots a second time on its own
+initiative: that second, live-read snapshot (`SnapshotClient.pull()` always
+creates one — snapshot.ts's own comment says so) was the thing making the
+pre-apply rollback snapshot stop being restorable the moment the apply that
+took it finished. Id adoption never needed the read; only a *fuller*
+comparison (server-minted `slug`, `color_uuid`, and the like) does, and that
+stays opt-in (`--post-snapshot`, or the prompt).
+
+Every `produces` entry on a create step now matters for this reason too, not
+only for cross-step reference resolution — a create with no `produces` (labels,
+webhooks and pipe_relations lacked one until this was noticed live: `pipe
+apply` reported the id adopted, and the file still read `"id": null, "_new":
+true"`) silently cannot be adopted this way.
+
+### One apply, one revert question — not three mechanisms wearing one word
+
+The first version of this had three unrelated things all called some kind of
+"rollback": a pipe-structure offer wired to `pipe apply`'s pipe-side failure,
+a flow-only offer wired to the flow half, and nothing at all for agents. That
+is not how a user experiences an apply — it is one action, and if any part of
+it fails partway, the honest question is "revert everything this apply
+changed", asked once, with the details of what that actually means for each
+part that touched anything. `offerUnifiedRevert` (apply.ts) is that one
+question; `finishApply` is what makes sure every exit from `applyOneRepo`
+that could still touch flows or agents runs through it.
+
+It is also asked when the failure is *not* in the half that already
+succeeded: a pipe change that lands cleanly and is then followed by a flow or
+agent failure still gets offered as part of the same revert, because from the
+user's side "this apply" covers all of it, not just whichever half happened
+to error.
+
+Each part is reverted the way its own platform actually allows, because
+there is no single API that reverses all three:
+
+- **Pipe structure** — `restoreRepoToSnapshot`, Pipefy's own mechanism,
+  restoring the pre-apply snapshot. Only offered while that snapshot is still
+  the latest (`caps.restoreLatestOnly`) — nothing before this point takes a
+  second snapshot on its own initiative, so it normally still is.
+- **iPaaS flows** and **AI agents** have no snapshot at all — a rollback for
+  either is filling a real gap this tool owns, not routing around a platform
+  one. Each is reverted by diffing the *current* live state (re-read fresh,
+  since some steps may have landed) against the read taken right before this
+  apply touched it, direction flipped: current is baseline, the old
+  pre-apply state is the target. `buildFlowRevertPlan` / `planFlowRevert`
+  (commands/flows.ts) and `buildAgentRevertChangeSet` / `planAgentRevert`
+  (commands/agents.ts) — the agent diff is otherwise offline against the
+  local baseline (module doc comment there), so its revert point is a live
+  read this apply now takes specifically to have one, the same gap flows
+  closed first.
+
+Rendered in full for every part that has anything to revert, before the one
+question is asked, and executed — on confirmation — in the reverse of the
+order they were applied: agents, then flows, then pipe structure.
+
+None of this reaches further than the platform allows, and says so rather
+than implying otherwise: no revert, Pipefy's or this tool's, un-sends an
+email an automation already dispatched or un-fires a webhook that already
+notified a third party. That is the platform's own irreversibility, not
+something a bigger rollback would fix.
+
+Verified live, for flows: a real ADD_ACTION rejection, the correct reverse
+plan (delete what landed, restore the old link), and the flow back to its
+exact original chain once applied — twice, once through the standalone
+mechanism and once through the unified one that replaced it.
+
+### Read the bytes back
+
+The check nothing else can make. After a flow write, every stored datapill is
+compared against what was sent. A migrating write path rewrites
+`{{step_1['output'].x}}` into `{{step_1['output']['output'].x}}` — structurally
+valid, accepted by Pipefy's own validator, and resolving to nothing at runtime.
+
+Generalise the habit: when a write path might transform what you send, compare the
+stored value, not the status code.
+
+---
+
+## 4. How this endpoint lies
+
+`VALIDATION.md` is the full catalogue — 30 corrected API facts, 34 bugs found by
+live running. Do not re-derive them. The shapes that bite most often:
+
+| | |
+| --- | --- |
+| A mutation can **succeed and change nothing** | arguments with no input are dropped silently |
+| `updatePipe.title_field_id` | wants the field's **uuid** or slug, never the numeric id the payload holds |
+| `archiveField` | `{ uuid }`, not the id |
+| `restoreRepoSnapshot` | **does not exist.** The endpoint has **`restoreRepoToSnapshot`**, which this build never looked for — so every apply printed "no one-command rollback" beside a snapshot that was restorable |
+| `restoreRepoToSnapshot.versionId` | the **latest** snapshot only. An older one is refused with `Version_id must reference the latest uploaded snapshot of the Pipe`, so a pre-apply snapshot stops being restorable the moment the verify read-back snapshots the repo. Recovery is forward-first |
+| a restore | **asynchronous**, reported through `operations` as `RESTORE`, not by the mutation returning |
+| `pipe(id:)` on a database | **answers**, and returns its record statuses as phases. `Table.url` matching `/apollo_databases/` is the only discriminator |
+| a database's snapshot payload | **is a pipe's** — the same twenty relation arrays, columns under `fields` with a real start-form `phase_id`. `createRepoSnapshot` accepts a table id |
+| `updateTableField` / `deleteTableField` / `setTableFieldOrder` | the field's **slug**, with `table_id` alongside. The internal id and uuid are both refused — the inverse of `updatePhaseField` |
+| `updateTable.summary_attributes[]` | the field's **internal id**, refusing the slug every neighbouring argument wants |
+| `CreateTableFieldInput.type` | its description lists 23 values and **under-reports**: `dynamic_content` is accepted. `formula` is readable and refused. `FieldTypeId` is the authorable set |
+| `createLabel` for a database | **`table_id`, not `pipe_id`** — the latter answers `Pipe not found with id: <the database id>`, which reads like a missing capability. Full CRUD once addressed right |
+| `createWebhook` for a database | **accepted, and it attaches** — but the product offers no webhooks on a database and the actions are card-shaped, so one sits there inert. Refused deliberately, not by omission |
+| a table field label | **unique per table** — a duplicate is refused with `Field label has already been taken`, so `label` is a sound natural key |
+| a phase field label | `createPhaseField` **does not** enforce this — two fields both labelled "Classification" were created live, one in the same phase as the first, and the slug was disambiguated instead. `updatePhaseField.label` is non-null, though, so it resends the current label on *every* call regardless of what changed, and that is where a pre-existing duplicate surfaces as the same `Field label has already been taken` — caught offline now in `validate/schema.ts` |
+| `deletePhaseField` | the field's **slug**, not the numeric id. A field has three identifiers and three mutations disagree: `updatePhaseField.id` takes the internal id, `archiveField` the uuid, this one the slug. Sent the id it says `Field not found with id: <id>` about a field that is plainly there |
+| `phaseSettings` | reports **failure for changes it has already made** — three runs, three times. Its errors are inconclusive; re-read. |
+| `AutomationActionParamsInput` | mixes snake and camel: `card_id`, `field_map`, but `taskParams`, `httpMethod` |
+| pipe relation flags | `canCreateNewItems` in the mutation, `can_create_connected_cards` in the payload |
+| `hidden_top_buttons` | a closed set of six, documented only in its own rejection |
+| automation event/action params | a wrong one is rejected as **`is invalid`** and nothing else, on both endpoints. The catalogue (`automationEvents`, `automationActions`) is public — read it and refuse by name |
+| an automation `condition` | **silently dropped** unless every expression carries `structure_id` — `expressions_structure` is a list of structure ids, not indices. Mutation succeeds, `expressions: []` stored |
+| `createFieldCondition` without `condition` | **`"Something went wrong"`**. An unconditional hide is real and useful, but the key must be present as `{expressions: []}`. `condition` is not NON_NULL on the input type |
+| `setFieldConditionOrder` | answers a **no-op with `"Something went wrong"`**. A new condition is appended by the server, so appending one in the workspace needs no reorder — compare against baseline + this phase's creates, not the baseline alone |
+| `createFieldCondition.phaseId` | **authorized and then ignored.** A bogus id is refused with "Permission denied", a real one is accepted, and the condition lands on the start form regardless — even when both fields it names live on the phase asked for. The UI can target any phase; this mutation cannot |
+| an expression with no `structure_id` | `Invalid input: Structure can't be blank`. `expressions_structure` names structure ids; derive one from position when the author gives none |
+| a nested collection in verification | server-minted ids, an added `phase_id`, and `0` vs `"0"` in `expressions_structure` are **not drift**. Reduce the live side to what the intent states, at every depth, or a created condition can never verify |
+| a field condition testing the field it hides | stored happily, and the **phase form stops opening**. The API validates none of this — not the self-reference, not the operation, not even `not_a_real_operation` |
+| `automationVariables.active` | omitted for the life of the tool, so disabling an automation was a no-op that reported success |
+| `updateAutomation` | works, across every field map dimension. The recipes' delete-and-recreate was inherited, not measured |
+| iPaaS `IMPORT_FLOW` | migrates the tree it is given; never use it |
+| iPaaS connections | the host marks any credential `ACTIVE` **without validating it** |
+| `POST /app-connections/{id}` | accepts `scope` and `projectIds` and returns 200 ignoring both |
+| iPaaS `ADD_ACTION`, parent is a `LOOP_ON_ITEMS` | `stepLocationRelativeToParent` is **required**, not optional, the moment the parent is a loop. Omitted (the shape every non-loop add uses, and the only shape ever probed before this) it answers `Loop step parent undefined not found` on the add that exits the loop — entering it (`INSIDE_LOOP`) already carried the field and already worked. `'AFTER'` sent explicitly fixes it |
+| a flow datapill reading a `connector` field's value | **the connected card(s)' id(s) only** — never their own field values, at any depth you index into the payload. Reading a connected card's fields needs an explicit `getCardById` (or similar) step per id; the parent's connector-field datapill can never supply them |
+
+### Closed sets: the list is published and enforced by nothing
+
+The schema publishes every fixed list an authored value must come from —
+`AutomationsEvents` (10), `AutomationsActions` (15), `FieldTypeId` (24), `Colors`
+(12) — and then types the input fields that consume them as `ID` and `String`:
+
+```
+CreateAutomationInput.event_id     ID
+CreateAutomationInput.action_id    ID
+CreatePhaseFieldInput.type_id      String
+```
+
+So GraphQL validates none of them. A wrong value passes query validation, reaches
+a runtime check, and returns one of `is invalid` or `All fields must be filled
+properly.` — naming no parameter, no field, and no accepted value, partway
+through an apply.
+
+The traps are near-misses, which is why reading the list beats knowing the domain.
+All three of these were live:
+
+| written | why it failed |
+| --- | --- |
+| `card_moved` + `event_params.in_phase_id` | real parameter, wrong event — it belongs to `card_inbox_received_email`. `card_moved` takes only `to_phase_id`. |
+| `move_single_card` + `action_params.card_id` | real parameter, wrong action — accepted on `update_card_field`, refused here. Verified by probe. |
+| a `time_range` field | in this tool's own hardcoded list; **not** a type the API offers |
+
+**Never hardcode one of these lists.** That was the previous approach and it
+rotted silently: `FIELD_TYPES` in `validate/schema.ts` carried `time_range`, which
+does not exist, and omitted `dynamic_content`, which does — warning about a valid
+type and passing an invalid one, with nothing to reveal either. It survives only
+as a fallback for workspaces with no reference, and only as a warning.
+
+Instead: `pipefy/reference.ts` reads the sets on every pull into
+`.ppc/reference.json`, `validate/reference.ts` refuses offline and names the
+value, and `REFERENCE.md` puts the same lists in the workspace so whoever edits
+the JSON reads what is accepted instead of guessing. A new closed set is three
+lines — add the enum to `TRACKED_ENUMS`, add a site to `ENUM_SITES`. **Absent
+reference means the check is skipped, never that a value is valid.**
+
+Pipefy's own docs for the automation mutations are worth reading once
+([create](https://developers.pipefy.com/reference/automation-creation),
+[update](https://developers.pipefy.com/reference/automation-update),
+[delete](https://developers.pipefy.com/reference/automation-deletion),
+[retrieve](https://developers.pipefy.com/reference/automation-retrieve)), but they
+are secondary to the generated file: they describe the mutations, not which
+parameters this pipe's events and actions accept, and they cannot go stale in a
+way `pipe pull` would notice.
+
+### Check the endpoint before assuming the internal API
+
+All three automation mutations are **public** and were being sent to the internal
+endpoint — inherited from the Change Migrator recipes and never re-checked, which
+made automations the one entity written through an unversioned endpoint with no
+introspection, for no reason. Before adding anything to `registry.ts` with
+`transport: 'internal'`, introspect the public schema for it. If it genuinely is
+not there, say which public mutation is missing and how that was verified.
+
+### Probing is not free on this platform
+
+Two separate incidents from the same wrong assumption — that schema validation
+rejects a malformed request before anything acts:
+
+- Enumerating the flow-operation enum with `request: {}` **published and enabled a
+  draft flow**. Five operations act on an empty request: `CHANGE_STATUS`,
+  `LOCK_AND_PUBLISH`, `LOCK_FLOW`, `CHANGE_FOLDER`, `UPDATE_METADATA`.
+- Enumerating connection types with `"probe"` as the credential returned
+  **201 ACTIVE** every time, leaving a connection that would fail at runtime.
+
+**Probe reads freely. Assume every write-shaped probe is real**, do it on a
+throwaway object, and check the state afterwards. Record what you learn in
+`VALIDATION.md`.
+
+---
+
+## 5. Where things live
+
+```
+src/
+  cli.ts            command dispatch
+  config.ts         endpoints, credential resolution, limits
+  pipefy/           graphql client · internal API · snapshots · reconstruction ·
+                    discovery · capability detection · ipaas (Advanced Automations) ·
+                    reference (the closed sets, read per pull)
+  codec/            unpack · pack · round-trip · flow (linked list <-> nodes)
+  workspace/        layout · read · write · lock · flows · stamp · generated docs
+  validate/         shape · referential integrity · closed sets, offline
+  diff/             pipe change set · flow change set · text render · HTML view
+  apply/            registry · mutation builders · compiler · id map · executor ·
+                    flowops (iPaaS operations)
+  report/           run records · a pipe's integration surface
+  commands/         one file per command
+test/               116 tests, node:test, no framework
+research/           probes and reads. The three that write are gated behind
+                    PIPE_PROBE_WRITES=1 and say why.
+.agents/skills/     four skills for agents editing workspaces
+```
+
+**Docs, in the order they answer questions:**
+
+| | |
+| --- | --- |
+| `README.md` | what the tool does, install, the loop, token costs, integrations |
+| `VALIDATION.md` | every API fact and every bug found by running it live |
+| `PLAN-IPAAS.md` | the iPaaS plan, its evidence, and what is still unbuilt |
+| `PLAN-BEHAVIOUR.md` | **plan, unimplemented.** Why a valid, stored automation can be inert, and the layers that would catch it |
+| `PLAN.md`, `PLAN-ROUTE-B.md`, `ROUTE-B-V2.md` | the original design and its revisions |
+| `.agents/skills/*/SKILL.md` | how to *use* the tool on a workspace |
+| a workspace's `REFERENCE.md` | generated, not written: what the API accepts in every closed-set position |
+
+---
+
+## 6. Conventions
+
+**Zero runtime dependencies, no build step.** Every import in `src/` is a `node:`
+builtin. Node ≥ 22.18 strips the types itself. Verified by deleting
+`node_modules` and running the CLI. Do not add a dependency; an FDE behind a proxy
+that blocks the npm registry has to be able to clone and run.
+
+`erasableSyntaxOnly` is on: **no constructor parameter properties, no enums, no
+namespaces.** Declare fields explicitly.
+
+**Comments explain why, not what.** The codebase is dense with them and they are
+load-bearing: most record an API fact or a failure that motivated the code. When
+you fix something subtle, leave the reason. When you read a comment that says an
+argument is dropped or an error is inconclusive, believe it — it was measured.
+
+**Tests are `node:test`, no framework.** `node --test test/*.test.ts`. Add a case
+for the shape of a bug, not just the fix. `test/flow-codec.test.ts` and
+`report.test.ts` are the models: they break things deliberately and assert the
+finding.
+
+**Commit messages describe the change and why, in prose.** They are long here on
+purpose — a commit is where the reason for a subtle fix survives. Describe the
+change, never the tooling that produced it.
+
+**Line endings are mixed** (CRLF and LF). Multi-line string matching against
+source files fails on the wrong one; match single lines or normalise first.
+
+**`workspaces/` is gitignored** because a pulled pipe carries webhook URLs, which
+are bearer-equivalent. Force-add only files you have checked, and say why.
+
+---
+
+## 7. Things not to do
+
+- **Do not delete-and-recreate to work around a missing write path.** It destroys
+  every existing value. `pipe plan` refuses these on purpose; say so and stop.
+- **Do not enable an iPaaS flow as a side effect.** It arms the flow against live
+  traffic. `--allow-flow-enable` exists so it is always deliberate, and it is
+  additionally refused while the project holds a placeholder connection.
+- **Do not write an iPaaS connection's credential.** Connections hold secrets:
+  read them, reference them, refuse to write them. A *placeholder* connection is
+  the exception and is tagged as such.
+- **Do not send `IMPORT_FLOW`.** `IpaasClient.operate` refuses it. See §3.
+- **Do not trust `ACTIVE`, a 200, or a validator.** All three have signed off on
+  broken states here.
+- **Do not treat a missing prerequisite as a reason not to build.** A pipe with no
+  iPaaS connections gets a placeholder and the flow gets built; the structure is
+  what is being authored and it does not depend on the credential working.
+
+---
+
+## 8. What is still unbuilt
+
+Honest gaps, so you do not promise them:
+
+- **Check the endpoint before assuming the internal API.** Automations were sent
+  to the internal endpoint for the whole life of this project because the
+  Change Migrator recipes had to, and nobody re-checked. All three mutations are
+  public and documented. If something is on the internal API, there should be a
+  comment saying which public mutation is missing and how that was verified.
+- ~~**Databases are discovered but not pulled.**~~ Done. A database is a repo:
+  its columns are fields on a start form and the phases after it are record
+  statuses, so the existing codec round-trips one with nothing added. What is
+  *not* done is records, excluded by decision rather than omission. Labels are
+  supported; webhooks are refused on purpose, with the measurement in the reason.
+- **`setFieldConditionOrder`** works but is the least exercised write path.
+- ~~**Flow node *creation* inside an existing flow** is refused by the compiler.~~
+  Done. `diff/flow.ts` attaches the authored tree to a `node.create` change so
+  `apply/flowops.ts` can find the new node's parent the same way
+  `buildFlowOperations` already does for a brand-new flow — whoever's
+  `_nextAction` / `_firstLoopAction` / a branch's `_children` names it — and
+  sends `ADD_ACTION`. A node nothing in the chain points to is still refused,
+  by name, rather than guessed at. Multiple new nodes in one apply are fine as
+  long as each is reachable once its own parent (new or old) exists, which the
+  file's execution-order-as-topological-order guarantee already provides.
+- **`pipe validate` does not yet check flows.** The rules are specified in
+  `PLAN-IPAAS.md` §6 Phase 2 and prototyped in `research/ipaas/validate-flow.ts`
+  with 17 negative tests. Moving them into `src/validate/` is the next obvious
+  step, and it is where the cross-surface checks belong — a datapill naming a
+  field by slug that the pipe does not have, a write whose value cannot land in
+  that `type_id`, deleting a field a live flow depends on.
+- **A desktop shell** is not coming. `PLAN.md` phase 3 described an Electron app;
+  it was removed rather than deferred, because `pipe diff --open` renders the
+  same HTML in the browser and a GUI is a second product to keep working. If a
+  UI is ever wanted, it belongs in its own repo consuming this one.
+
+When you close one of these, update this section and `PLAN-IPAAS.md` together.