ab-plumber 0.1.0__tar.gz

ab_plumber-0.1.0/.envrc

@@ -0,0 +1,17 @@
+watch_file pyproject.toml
+watch_file uv.lock
+watch_file flake.nix
+watch_file flake.lock
+
+use flake
+
+# On the first activation, create uv.lock and .venv.
+# After that, require the committed lockfile to remain valid.
+if [[ -f uv.lock ]]; then
+    uv sync --locked --extra dev --quiet
+else
+    uv sync --extra dev --quiet
+fi
+
+export VIRTUAL_ENV="$PWD/.venv"
+PATH_add "$VIRTUAL_ENV/bin"

ab_plumber-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: ci
+
+on:
+  push:
+    branches: [master, main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: python -m pip install -e ".[dev]"
+      - name: Lint
+        run: python -m ruff check .
+      - name: Test
+        run: python -m pytest -q

ab_plumber-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,45 @@
+name: publish
+
+# Build and publish to PyPI on a GitHub Release, using PyPI Trusted Publishing
+# (OIDC) — no API tokens or secrets required. Configure the trusted publisher at
+# https://pypi.org/manage/project/ab-plumber/settings/publishing/ (or via the
+# "pending publisher" flow before the first release). The publisher must name workflow
+# `publish.yml` and environment `pypi`, or the upload is rejected.
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - name: Check distributions
+        run: |
+          python -m pip install --upgrade twine
+          python -m twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write        # required for OIDC trusted publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

ab_plumber-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+*.pyc
+__pycache__/
+.venv/
+.direnv/
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+data/raw/*
+data/processed/*
+!data/**/.gitkeep
+.claude/worktrees/

ab_plumber-0.1.0/.scratch/discovery/issues/01-phase-discovery-and-ordering.md

@@ -0,0 +1,27 @@
+# Phase discovery & ordering
+
+Type: grilling
+Status: open
+Blocked by: —
+
+## Question
+
+How does the `plumber` CLI, run from an arbitrary repo, find that repo's phase
+modules and determine their execution order?
+
+Decide between (and/or combine): a conventioned `phases/` directory ordered by
+filename prefix; an explicit ordered list in the config file; a
+registry/decorator the modules opt into. Resolve the design-doc section 7 open
+thread — string names in the pipeline list vs. module-object introspection for
+keying per-phase params. Output: the discovery mechanism, the ordering source of
+truth, and how a phase's identity string is formed and matched to its config
+params.
+
+## Input from research
+
+Ticket 09 (`research/pipeline-framework-prior-art.md`) recommends the **Ploomber**
+model: an explicit ordered step list in the config file, each entry a dotted path
+resolved directly to `<module>.run`, no project skeleton or package layout
+required (Kedro/Dagster/Prefect all fail "run from any repo" by requiring one).
+No DAG inference, no named IO ports — the chain is linear, one gdf passed through.
+Per-phase params keyed by the config entry, not by module introspection.

ab_plumber-0.1.0/.scratch/discovery/issues/02-phasemodule-protocol-and-contract.md

@@ -0,0 +1,32 @@
+# PhaseModule protocol & the phase contract
+
+Type: grilling
+Status: open
+Blocked by: —
+
+## Question
+
+Pin the phase interface and its written contract.
+
+- Module-level `run(gdf, **params) -> gdf` as the single public entry point, with
+  a `typing.Protocol` (`PhaseModule`) capturing it — confirm this over a bare
+  convention or a registry dict, and confirm no class-based ABC.
+- State the purity / partition contract every executor assumes: `run()` is a pure
+  function of its input, sees **one partition** (never assumes it has the whole
+  dataset), holds no shared mutable state, does not depend on global phase order.
+- CRS / schema expectations: what a phase may assume about its input and must
+  guarantee about its output (design doc: "CRS preserved unless explicitly
+  reprojected").
+- Where the `GeoDataFrame`-only assumption lives so a later payload type does not
+  break the Protocol (feeds the "payload seam" fog item).
+
+Output: the `PhaseModule` Protocol definition and a contract statement suitable
+to drop into `CONTEXT.md` / an ADR.
+
+## Input from research
+
+Ticket 08 (`research/beam-spark-partition-contract.md`): the contract must state a
+phase is a **partition-local map** — module-level (not a closure), pure,
+idempotent, order-independent, no shared mutable state, captures no unpicklable
+resources. Include a "non-partitionable phase runs on the driver / single
+partition" escape hatch.

ab_plumber-0.1.0/.scratch/discovery/issues/03-config-schema-and-format.md

@@ -0,0 +1,31 @@
+# Config file schema & format
+
+Type: grilling
+Status: open
+Blocked by: 01, 02
+
+## Question
+
+Define the plumber config file — the artifact both a human and the AI skill
+author.
+
+- Format: YAML or TOML. Pick one; note why.
+- Schema: pipeline name; input block (format, CRS, geometry type); ordered phase
+  list with per-phase params and per-phase constraints; execution block
+  (strategy, partition spec — by field(s) / chunk size / worker count).
+- How phase identity in the config maps to discovered modules (depends on 01).
+- What is a CLI flag vs. a config key: executor and scale live on flags and
+  override config; params live in config. Nail the override precedence.
+- Validation: is the config schema-checked on load, and by what (pydantic /
+  plain dataclass + manual checks)?
+
+Output: an annotated example config plus the field list and override rules.
+
+## Input from research
+
+Ticket 09 (`research/pipeline-framework-prior-art.md`): adopt Kedro's two-layer
+config with **CLI-wins precedence** (`parameters.yml` + `--params`), merge to one
+dict, pass to the phase as `**params` (Ploomber `PythonCallable(**params)`
+style). Optional typed validation via a **phase-exported Pydantic model** that
+`plumber check` verifies (Dagster `Config` idea) — the entry point stays
+`run(gdf, **params)`, never a class. Explicit ordered `phases:` list, no DAG.

ab_plumber-0.1.0/.scratch/discovery/issues/04-executionstrategy-protocol-and-partitioning.md

@@ -0,0 +1,36 @@
+# ExecutionStrategy protocol & partition model
+
+Type: grilling
+Status: open
+Blocked by: 02
+
+## Question
+
+Design the execution-strategy seam so `local` + `localmp` ship now and
+`dataflow` + `pyspark` slot in later without a protocol change.
+
+- The `ExecutionStrategy` Protocol: `execute(phases, data, params)` signature —
+  what `data` is, what comes back, how per-phase params are threaded through.
+- Partition model: how the config's partition spec (by field(s) / chunk size /
+  worker count) is turned into partitions, how the phase chain runs per
+  partition, how outputs are reassembled into one `GeoDataFrame`.
+- The uniform-partition question: does `local` also pass a single whole-dataset
+  partition so phase code never branches on executor? Decide yes/no.
+- What `LocalSequential` and `LocalMultiprocess` each need from the protocol;
+  confirm nothing in the signature blocks a Beam `Map`-chain or a Spark
+  `mapPartitions` implementation later (cross-check with ticket 08 findings).
+
+Output: the `ExecutionStrategy` Protocol, the partition-spec → partitions
+mapping, and the reassembly contract.
+
+## Input from research
+
+Ticket 08 (`research/beam-spark-partition-contract.md`) — lock two costless
+decisions so Beam/Spark stay open: type `execute`'s `data` as a **dataset
+reference** (path + format + opts), not a materialized GeoDataFrame — distributed
+executors do their own IO; type the **return as a result/handle**, not
+necessarily a driver-collected GeoDataFrame. Beam has no first-class per-partition
+transform (carry a partition as one pickled element) and no vector IO in core;
+Spark uses `applyInPandas` (by field) / `mapInPandas` (by size) and effectively
+requires Sedona. Local + localmp can still collect to a GeoDataFrame behind the
+same handle type.

ab_plumber-0.1.0/.scratch/discovery/issues/05-check-validator-design.md

@@ -0,0 +1,25 @@
+# `plumber check` validator design
+
+Type: prototype
+Status: open
+Blocked by: 02
+
+## Question
+
+Decide how `plumber check` inspects a repo's phase modules for contract
+adherence — this is also the capability the AI skill consumes for its rework
+recommendations.
+
+- Inspection method: static (AST) / import-and-introspect signatures / runtime
+  probe with a small synthetic `GeoDataFrame` fixture — or a layered combination.
+- What it checks: `run()` present and signature-compatible with `PhaseModule`;
+  no obvious shared-state / global-order violations; declared vs. actual dtypes;
+  CRS-preservation constraint; params in config match `run()`'s accepted kwargs.
+- Output shape: machine-readable (for the skill) + human-readable; per-phase
+  pass/fail with actionable messages.
+- Where it runs: standalone `plumber check`, and/or an automatic preflight before
+  `plumber run`.
+
+Build a rough prototype against 2–3 stub phase modules (one clean, one with a
+bad signature, one with a dtype/CRS violation) to pressure-test the approach.
+Link the prototype from this ticket.

ab_plumber-0.1.0/.scratch/discovery/issues/06-skill-boundary.md

@@ -0,0 +1,27 @@
+# AI skill boundary
+
+Type: grilling
+Status: open
+Blocked by: 03, 05
+
+## Question
+
+Fix the boundary of the optional AI skill under `ab_spatial/.claude/` — not its
+conversation flow.
+
+- Inputs it reads from plumber: the `PhaseModule` / `ExecutionStrategy`
+  Protocols, `plumber check` output, the config schema. How does it get them —
+  import plumber, shell out to `plumber check --json`, read a schema file?
+- Outputs it emits: the config file (writes/updates it), and rework
+  recommendation text for protocol/partition issues. Anything else? Does it ever
+  write into the target repo's phase modules? (Constraint says no — confirm and
+  record.)
+- Invocation: slash-command name, and what triggers it (explicit only, or also
+  on some condition).
+- Degradation: enumerate exactly what a human does by hand when the skill is
+  absent, to confirm nothing is skill-only.
+- Dependency direction: skill depends on plumber; plumber never imports or knows
+  about the skill.
+
+Output: an inputs/outputs/invocation spec for the skill, ready for its own later
+effort to design the conversation.

ab_plumber-0.1.0/.scratch/discovery/issues/07-packaging-and-repo-discovery.md

@@ -0,0 +1,31 @@
+# Packaging, distribution & "run from any repo"
+
+Type: grilling
+Status: open
+Blocked by: —
+
+## Question
+
+Decide how plumber is installed and how it locates a target repo's phases and
+config when invoked from that repo's working directory.
+
+- Distribution: pipx-installed global tool (like `ruff`/`pytest`) vs. a dev
+  dependency each pipeline repo adds vs. both. "Run from any repo" leans global.
+- Discovery root: cwd-relative? a `plumber.toml` / `pyproject.toml [tool.plumber]`
+  marker at the repo root? an explicit `--config` path?
+- Console-script entry point name (`plumber`), subcommand surface (`run`,
+  `check`, later `new-phase`).
+- Dev environment for the plumber repo itself: match maply's Nix + `uv` +
+  `direnv` setup, or simpler? Python version floor (maply targets 3.9–3.12).
+- Packaging backend (hatchling, like maply) and versioning approach.
+
+Output: the install story, the discovery rules, and the plumber repo's own dev
+setup.
+
+## Input from research
+
+Ticket 09 (`research/pipeline-framework-prior-art.md`): Kedro/Dagster/Prefect all
+require their own project skeleton (`pipeline_registry.py`, `Definitions` code
+location, deployments) — that fails "run from any repo". Ploomber's approach fits:
+resolve a dotted path / file directly, no package layout imposed on the target
+repo. Lean that way for discovery.

ab_plumber-0.1.0/.scratch/discovery/issues/08-research-beam-spark-partition-contract.md

@@ -0,0 +1,50 @@
+# Research: Beam & Spark partition/step contract for geospatial data
+
+Type: research
+Status: resolved
+Blocked by: —
+
+## Question
+
+Surface the facts ticket 04 needs so the `ExecutionStrategy` protocol is designed
+without foreclosing `dataflow` (Apache Beam) or `pyspark`, even though neither is
+implemented now.
+
+- Apache Beam: how a per-element / per-partition transform is expressed
+  (`beam.Map`, `beam.ParDo`), how bundling/partitioning works, what a step
+  function may and may not assume, side-input mechanics, and the state of
+  geospatial IO connectors (GeoParquet / vector formats) in Beam's Python SDK.
+- PySpark: `mapPartitions` / pandas-UDF / `applyInPandas` contract for running a
+  function over a partition as a (Geo)DataFrame; how partitioning by column vs.
+  by size is expressed; Sedona's role for geospatial types.
+- The common shape: what a "run this phase chain over one partition" callable
+  must look like to be portable across LocalMultiprocess, Beam, and Spark.
+- Anything that would force a signature change to `execute(phases, data, params)`
+  or to `run(gdf, **params) -> gdf`.
+
+Capture findings as `.scratch/discovery/research/beam-spark-partition-contract.md`
+and link it here. Primary sources: Beam and Spark official docs, Sedona docs.
+
+## Answer
+
+Findings: [`.scratch/discovery/research/beam-spark-partition-contract.md`](../research/beam-spark-partition-contract.md)
+
+Nothing forces an arity change to `execute(phases, data, params)` or to
+`run(gdf, **params) -> gdf`. Beam's unit of user code is the element (`beam.Map` /
+`ParDo`; no first-class per-partition transform — you carry a partition as one
+pickled element or rebuild it after `GroupByKey`/`GroupIntoBatches`); bundles are
+opaque, unordered, and retried. Spark's per-partition contract is
+`applyInPandas` (partition-by-field) or `mapInPandas` (by size), each needing a
+declared output schema, with geometry kept typed via Sedona (+ native GeoParquet);
+`repartition`/`repartitionByRange` cover column vs range, target-size is manual
+arithmetic. The portable callable is a module-level (not closure) pure function
+`(partition_gdf, params) -> partition_gdf` that is order-independent, idempotent,
+holds no shared mutable state, and captures no unpicklable resources — the exact
+intersection of `Pool` + Beam `ParDo` + Spark `applyInPandas`. Two decisions to
+make now so Beam/Spark stay open, both costless on the current signature: type
+`data` as a dataset reference (not a materialized GeoDataFrame — distributed
+executors do their own IO) and type `execute`'s return as a result/handle (not
+necessarily a collected GeoDataFrame). Also name in ticket 02 that a phase must be
+a partition-local map, with a "non-partitionable phase runs on the driver" escape
+hatch. Beam core has no GeoParquet/vector IO (plain Parquet only; `geobeam` is the
+third-party option); a Spark executor effectively requires Sedona.

ab_plumber-0.1.0/.scratch/discovery/issues/09-research-pipeline-framework-prior-art.md

@@ -0,0 +1,59 @@
+# Research: pipeline-framework prior art
+
+Type: research
+Status: resolved
+Blocked by: —
+
+## Question
+
+Survey how established Python pipeline frameworks handle the three seams plumber
+is designing, so tickets 01/03/04 borrow proven patterns instead of reinventing.
+
+- Kedro: node/pipeline discovery, the data catalog + parameters YAML, pluggable
+  runners (SequentialRunner / ParallelRunner / ThreadRunner), how it keeps
+  node functions ignorant of the runner.
+- Dagster: op/asset definition, config schema (`Config` / run config), executors
+  (in-process / multiprocess / k8s), partitions API.
+- Prefect: task/flow discovery, task runners (Concurrent / Dask / Ray),
+  parametrization.
+- Optional: Luigi, Snakemake, Ploomber for contrast.
+
+For each: how phases are discovered/ordered, how config/params are supplied, how
+the execution backend is swapped, and what the phase function is allowed to
+assume. Call out which patterns fit plumber's "functions over classes" +
+"run from any repo" stance and which don't.
+
+Capture findings as `.scratch/discovery/research/pipeline-framework-prior-art.md`
+and link it here.
+
+## Answer
+
+Full findings: `.scratch/discovery/research/pipeline-framework-prior-art.md`
+(primary-source citations inline).
+
+- **Discovery/ordering**: Kedro, Dagster, Snakemake, Luigi all *derive* order from a
+  data-dependency / filename DAG; only **Ploomber** lists steps explicitly in a YAML
+  (`pipeline.yaml` tasks with `source`/`upstream`). plumber's chain is linear and passes
+  one gdf, so the explicit ordered `phases:` list in the config is the right model — no
+  DAG inference, no named IO ports.
+- **Discovery mechanism**: Kedro (`pipeline_registry.py` + `conf/` + `settings.py`),
+  Dagster (`Definitions` code location) and Prefect (deployments) all need their own
+  project skeleton — fails plumber's "run from any repo". Ploomber resolves a dotted
+  path / file directly with no package layout; do that: each config entry -> `<module>.run`.
+- **Config/params**: adopt Kedro's two layers with CLI-wins precedence (`parameters.yml`
+  + `--params`); hand the merged dict to the phase as `**params` (Ploomber
+  `PythonCallable(**params)`). Optional typed validation via a phase-exported Pydantic
+  model checked by `plumber check` (Dagster `Config` idea) — entry point stays
+  `run(gdf, **params)`, never a class.
+- **Executor swap**: every framework keeps this orthogonal (Prefect `task_runner=`,
+  Dagster `executor_def` / `execution:`, Ploomber `executor:`, Kedro `--runner`). One
+  CLI flag / config key picks an `ExecutionStrategy`; phase code never references it.
+  Mirror Kedro's ParallelRunner rules as plumber's parallel contract: gdf + params must
+  be picklable, no shared mutable state, no cross-phase side effects.
+- **Partitioning**: Dagster's model (same compute logic per partition, key injected at
+  runtime, strategy owns fan-out/gather) fits; its `PartitionsDefinition` object graph
+  does not — plumber's partitioning is explicit config. Keep phases partition-agnostic:
+  one gdf in, one gdf out.
+- **Reject**: DAG inference, mandatory framework skeletons, class-per-phase
+  (Luigi), target-file-existence as the ordering primitive, and Prefect's
+  config-less imperative flow.

ab_plumber-0.1.0/.scratch/discovery/map.md

@@ -0,0 +1,115 @@
+<!-- wayfinder:map -->
+# plumber — Discovery map
+
+> **Migrated to GitHub Issues** (`austinbreunig/plumber`, label `wayfinder:map`).
+> This file is the charting-session record; the GitHub issue is now the live map.
+
+## Destination
+
+A signed-off `plan.md` for **plumber**: a pip/pipx-installable geospatial
+pipeline framework + `plumber` CLI — module-level `run(gdf, **params) -> gdf`
+phase protocol, a builder, pluggable execution strategies, config-file-driven
+phase runs, and a `plumber check` validator — plus a thin **optional** AI skill
+(under `ab_spatial/.claude/`) that only helps author the config file and gives
+protocol/partition rework recommendations by consuming plumber's public API. The
+core is fully usable without the skill.
+
+Discovery ends when every decision ticket below is resolved or explicitly
+deferred, enough for Tracer to write a spec. We decide the skill's *boundary*
+(what it reads, what it emits, how it's invoked) — not its conversation flow.
+
+## Notes
+
+**Domain:** geospatial data engineering. Phases are algorithm modules; execution
+strategy (local / multiprocess / dataflow / pyspark) is orthogonal and swappable
+without touching phase code. Prototype→production scaling is the core pain point
+this separation targets.
+
+**Seed design doc:** the "Geospatial Pipeline Project — Design Doc & Handoff
+Spec" from the charting conversation (sections 1–8). Treat its `core/` reasoning
+as load-bearing; treat its section 6 "agentic pipeline generation" as
+superseded by the constraints below.
+
+**Skills every session should consult:** `/grilling` + `/domain-modeling` for any
+decision ticket; `/prototype` for the `check` validator ticket. Wu Wei
+(`.claude/skills/wu-wei/`) — plain functions over classes; a class only for
+genuine persistent state (the builder may qualify, the protocols do not).
+
+**Constraints established while charting (not re-open without cause):**
+
+- **Skill scope:** config authoring + protocol/partition rework recs only. It
+  consumes plumber's protocols + `check` output and drives the public API; it
+  never reimplements framework logic and never generates whole phase modules.
+  Everything works with the skill removed.
+- **Skill home:** `ab_spatial/.claude/` (root), importing plumber as a dep — not
+  in-repo.
+- **Config:** a config file (YAML or TOML — TBD) drives the phase list + per-phase
+  params. CLI flags pick executor + scale and override params.
+- **Executors:** design `ExecutionStrategy` to admit all four; implement `local`
+  + `localmp` for the tracer. `dataflow` + `pyspark` implementations deferred
+  (see Out of scope) — the protocol must not foreclose them.
+- **Payload:** `GeoDataFrame` for v1. Leave a seam for other formats (raster,
+  plain DataFrame, arrow) without a protocol break.
+- **Partitioning is explicit config:** by field(s), by chunk size, or (mp) by
+  worker count.
+- **Name:** `plumber` (was `geo-plumber`).
+
+## Decisions so far
+
+<!-- one line per resolved ticket: gist + link -->
+
+- [Research: Beam/Spark partition contract](issues/08-research-beam-spark-partition-contract.md)
+  — nothing forces an arity change to `execute(...)` or `run(gdf, **params) -> gdf`.
+  The portable per-partition callable is a module-level pure fn
+  `(partition_gdf, params) -> partition_gdf` (idempotent, order-independent, no
+  shared state, picklable) — plumber's phase contract already meets this if
+  phases stay pure. Lock two costless decisions so Beam/Spark aren't foreclosed:
+  (1) type `execute`'s `data` as a **dataset reference** (path + format + opts),
+  not a materialized GeoDataFrame — distributed executors do their own IO;
+  (2) type `execute`'s **return as a result/handle**, not necessarily a
+  driver-collected GeoDataFrame. Beam core has no vector/GeoParquet IO
+  (`geobeam` is 3rd-party); a Spark executor effectively requires Sedona.
+  Full findings: `research/beam-spark-partition-contract.md`.
+- [Research: pipeline-framework prior art](issues/09-research-pipeline-framework-prior-art.md)
+  — Kedro/Dagster/Snakemake/Luigi all *derive* order from a DAG and need their
+  own project skeleton (fails "run from any repo"). **Ploomber** is the model:
+  explicit ordered step list in YAML, each entry a dotted path resolved directly
+  to `<module>.run`, no package layout. Config: Kedro's two layers with CLI-wins
+  precedence (`parameters.yml` + `--params`) merged and passed as `**params`;
+  optional typed validation via a phase-exported Pydantic model checked by
+  `plumber check` — entry point stays `run(gdf, **params)`, never a class.
+  Executor swap: one flag/key picks an `ExecutionStrategy`, phase code never
+  references it; parallel contract = Kedro ParallelRunner rules (picklable, no
+  shared state, no cross-phase side effects). Partitioning: Dagster's
+  runtime-key-injection model, but explicit in config — phases stay
+  partition-agnostic, one gdf in / one gdf out. Reject: DAG inference, mandatory
+  skeletons, class-per-phase, target-file-existence ordering.
+  Full findings: `research/pipeline-framework-prior-art.md`.
+
+## Not yet specified
+
+<!-- in-scope fog; graduates to tickets as the frontier advances -->
+
+- **Payload seam for non-GDF formats** — how the GeoDataFrame assumption is
+  isolated so raster / DataFrame / arrow can slot in later. Revisit after the
+  PhaseModule protocol and ExecutionStrategy tickets resolve.
+- **Tracer fixture / first pipeline** — the synthetic fixture + stub phases (or a
+  real pipeline) used to exercise the interface end to end. Revisit after the
+  config-schema and ExecutionStrategy tickets.
+- **Skill conversation flow + spec diffing/versioning** — how the interview runs
+  and how a later session diffs an existing config instead of starting over.
+  Revisit after the skill-boundary ticket. (Its own effort, likely.)
+- **Contract-violation → rework-rec formatting** — how `check` failures are
+  phrased back to a human or the skill; any retry semantics. Revisit after the
+  `check` validator ticket.
+
+## Out of scope
+
+<!-- ruled beyond the destination; never graduates -->
+
+- **`dataflow` + `pyspark` executor implementations** — the protocol must admit
+  them; building/testing them is a later effort.
+- **Agent-generated phase modules** — the design doc's section 6a/6c codegen. The
+  skill authors config + recs only.
+- **The skill's conversation-flow design** — deferred; becomes its own effort
+  once the boundary is fixed.