stepcraft 0.1.0__tar.gz

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

@@ -0,0 +1,83 @@
+name: CI
+
+on:
+  push:
+    branches: [main, working_barnch]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install dependencies
+        run: |
+          uv sync --all-extras --group dev
+
+      - name: Run tests
+        run: |
+          uv run pytest tests/ -v
+
+  test-free-threading:
+    # Free-threaded (no-GIL) CPython 3.14t. Skips gracefully if the runner
+    # cannot provision the build.
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up free-threaded Python 3.14
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.14t"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install dependencies
+        run: |
+          uv sync --group dev
+
+      - name: Run free-threading + parallel tests
+        run: |
+          uv run pytest tests/ -v -k "free_threading or parallel_auto or parallel or thread_parallel"
+
+  test-rsloop:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.13
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install with rsloop extra
+        run: |
+          uv sync --extra rsloop --group dev
+
+      - name: Run rsloop tests
+        run: |
+          uv run pytest tests/ -v -m rsloop

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

@@ -0,0 +1,48 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build wheel and sdist
+        run: uv build --out-dir dist
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/*
+
+  publish:
+    name: Publish to PyPI
+    needs: [build]
+    runs-on: ubuntu-latest
+    environment: pypi
+
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Publish to PyPI
+        run: uv publish dist/*
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.UV_PUBLISH_TOKEN }}

stepcraft-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Compiled extensions
+*.so
+
+# OS
+.DS_Store
+Thumbs.db
+._*

stepcraft-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

stepcraft-0.1.0/AUDIT.md

@@ -0,0 +1,292 @@
+# stepcraft Audit — Bugs & Incomplete Features
+
+Audit date: 2026-06-24. Based on code review, runtime reproduction, and test coverage analysis.
+Updated 2026-06-25 with findings from the multi-agent code-review pass on the
+`working_barnch` feature diff (hooks, shared context, half-open breaker, beartype).
+
+---
+
+## Open findings — code-review pass (2026-06-25)
+
+Verified findings against the feature diff. Ordered by severity. Each item lists
+**what** is wrong and **how** to fix it.
+
+### CR-1. Shared context never reaches pool workers (HIGH)
+
+**What:** `Pipeline._activate_context` sets a `contextvars.ContextVar` on the
+calling thread only. `pool.map` / `loop.run_in_executor` do **not** copy
+contextvars into worker threads/processes, so any step that runs off the calling
+thread sees `get_context() == {}`:
+- `@piped(parallel='thread'|'process')` steps,
+- `@piped(timeout=...)` steps (run via the thread pool),
+- sync functions executed inside an async pipeline (`run_in_executor`),
+- auto-mapped/batched work dispatched to executors.
+
+README presents `get_context()` as the supported way for steps to read context,
+so this is a silent correctness gap.
+
+**Location:** `context.py:12`, `pipeline.py` (`_activate_context`, run loops),
+`step.py` (`_execute_parallel`, `_execute_parallel_async`, `_execute_sync`
+timeout branch, `_execute_auto_map*`, `_execute_batched*`).
+
+**How to fix:** capture the active context at dispatch and run workers inside it.
+- Threads: wrap submitted callables with `contextvars.copy_context().run(fn, ...)`,
+  or snapshot `get_context()` on the calling thread and re-set it inside the
+  worker wrapper.
+- Processes: contextvars cannot cross the pickle boundary — pass the context dict
+  explicitly to the worker and re-set it there, or document that process pools do
+  not see `get_context()`.
+- Add tests: `parallel='thread'`, `timeout=`, and async-with-sync-func steps all
+  reading `get_context()` inside a `Pipeline(context=...)`.
+
+### CR-2. Half-open probe slot consumed before cancel check → breaker stuck (HIGH)
+
+**What:** In `_preflight_check`, `_check_circuit_breaker()` runs first and
+increments `_half_open_calls`; the cancel-event check runs *after*. If the call
+is cancelled, the probe slot is consumed but neither `_record_failure` nor
+`_reset_circuit_breaker` runs, leaving the breaker `HALF_OPEN` with the slot used
+**forever** — every later call raises `CircuitBreakerError` even once healthy.
+
+**Location:** `step.py` `_preflight_check` / `_check_circuit_breaker` (~L155, L387–391).
+
+**How to fix:** check the cancel event **before** consuming a probe slot (reorder
+`_preflight_check` so the cancel check precedes `_check_circuit_breaker`), or
+release the slot on cancellation (decrement `_half_open_calls` / restore state in
+a `finally`/except path when `CancelledError` is raised before the call runs).
+Add a regression test: half-open + cancel set → breaker still recovers later.
+
+### CR-3. Breaker reset happens before the schema check (MEDIUM)
+
+**What:** `_finalize_success` calls `_reset_circuit_breaker()` and *then* validates
+`schema`. A half-open probe whose function returns a wrong-typed value first
+closes the breaker, then raises `TypeError`, which records a failure against a
+now-`CLOSED` breaker (count from 0) instead of re-opening immediately.
+
+**Location:** `step.py:169–179` (`_finalize_success`).
+
+**How to fix:** validate the schema **before** calling `_reset_circuit_breaker()`
+so a schema failure is treated like any other probe failure. Add a test:
+`circuit_breaker` + `schema` where the recovered call returns the wrong type →
+breaker re-opens rather than closing.
+
+### CR-4. Graph never activates shared context (MEDIUM)
+
+**What:** Context activation was added to `Pipeline` only. `Graph.run` /
+`Graph.async_run` have no `_activate_context`, so a `@piped` node that reads
+`get_context()` gets `{}` in a DAG even when run sequentially — inconsistent with
+`Pipeline` and with the docs.
+
+**Location:** `graph.py:120` (`run`) and `graph.py` `async_run`.
+
+**How to fix:** give `Graph` an optional `context=` and wrap both run paths in the
+same activation, ideally by extracting a shared `_activate_context` helper (e.g.
+into `context.py`) reused by `Pipeline` and `Graph`. Note this composes with CR-1
+(workers still need propagation). Add a Graph context test.
+
+### CR-5. `on_step` missing on half the public run surface (MEDIUM)
+
+**What:** `on_step` was threaded through `run` / `async_run` / `run_detailed` /
+`async_run_detailed` only. `run_async`, `map`, `async_map`, `map_async` ignore it;
+`pipeline.run_async(seed, on_step=hook)` raises `TypeError`. README says "Pass
+`on_step` to any run method."
+
+**Location:** `pipeline.py` (`run_async`, `map`, `async_map`, `map_async`).
+
+**How to fix:** forward `on_step` from `map`/`async_map` into per-item `run`/
+`async_run`, and from `run_async`/`map_async` into the underlying coroutine; OR
+narrow the README to list exactly the four methods that accept it. Prefer
+forwarding for consistency. Add coverage for at least `map(on_step=...)`.
+
+### CR-6. Spec with both `graph:` and `steps:` builds a silent linear pipeline (LOW)
+
+**What:** `build_pipeline_from_spec` only rejects a graph spec when `steps` is
+absent. A spec containing **both** keys silently builds a linear `Pipeline` and
+ignores the `graph:` block (wrong execution order / fan-in inputs, no error).
+
+**Location:** `spec.py:144` (`build_pipeline_from_spec`).
+
+**How to fix:** raise `ValueError` when both `graph` and `steps` are present
+(ambiguous spec). Mirror the check in `build_graph_from_spec`. Add a test for the
+both-keys case.
+
+### CR-7. `_half_open_calls` increment is not atomic across threads (LOW)
+
+**What:** `_check_circuit_breaker` does a non-atomic read-check-increment on
+`_half_open_calls`. When one `PipeStep` is invoked concurrently (parallel graph
+levels, `parallel='thread'` fan-out), multiple threads can each read `0` and all
+proceed, exceeding `half_open_max_calls`. Pre-existing class of issue — breaker
+state was never lock-guarded — but the new probe quota relies on it.
+
+**Location:** `step.py:384–391` (`_check_circuit_breaker`, `_record_failure`).
+
+**How to fix:** guard breaker state transitions with a `threading.Lock` on the
+step (note: a `frozen`/`object.__setattr__` dataclass needs a non-init lock
+field). Lower priority unless shared concurrent steps are a supported pattern;
+otherwise document that breaker state is not thread-safe.
+
+### Intentional behavior changes (not bugs — confirm and keep)
+
+- **Single-probe half-open semantics** (`step.py` `_check_circuit_breaker`): the
+  breaker now allows only `half_open_max_calls` (default 1) probes and re-opens on
+  the first probe failure. This is the requested Phase 2.4 feature, **not** a
+  regression — but CR-2/CR-3/CR-7 above are real defects within it.
+- **beartype runtime type-checking** (`__init__.py`): every function/method is
+  decorated via the import hook; calls that violate annotations now raise
+  `BeartypeCallHintParamViolation`. Intended. Caveat to document: it is always-on
+  with no opt-out env var, and the numeric tower is enabled (int accepted for
+  float). Consider an opt-out hook (e.g. `PIPECRAFT_NO_BEARTYPE`) if consumers
+  need to disable runtime checks in production.
+
+---
+
+## Confirmed bugs
+
+### 1. Async + `batch_size` returns unawaited coroutines
+
+When an **async** function is used with `batch_size > 1`, `_invoke_function_async` calls the sync `_execute_batched`, which invokes `self.func(batch)` without awaiting.
+
+```python
+@piped(batch_size=2)
+async def process_batch(batch):
+    return [x * 2 for x in batch]
+
+await process_batch.async_run([1, 2, 3, 4])
+# -> [<coroutine ...>, <coroutine ...>]  # RuntimeWarning: never awaited
+```
+
+**Location:** `src/stepcraft/step.py` — `_invoke_function_async` → `_execute_batched`
+
+**Impact:** `async_run` silently returns coroutine objects instead of results.
+
+---
+
+### 2. Async + `parallel='thread'` has the same problem
+
+The parallel async path uses `run_in_executor(pool, call, item)`, which always invokes the **sync** wrapper. Async `@piped` functions therefore produce unawaited coroutines.
+
+```python
+@piped(parallel='thread')
+async def f(x):
+    return x * 2
+
+await f.async_run([1, 2, 3])
+# -> [<coroutine ...>, <coroutine ...>, <coroutine ...>]
+```
+
+**Location:** `src/stepcraft/step.py` — `_execute_parallel_async`
+
+**Impact:** `parallel` + async steps are broken on the async execution path. Sync `run()` is fine (thread pool runs sync callables).
+
+---
+
+### 3. `_async_run_branch_value` may not await `run()` coroutines
+
+If a branch has `.run` but not `.async_run`, and `run()` returns a coroutine, it is returned without awaiting.
+
+```python
+# src/stepcraft/utils.py
+async def _async_run_branch_value(branch, value):
+    ...
+    if hasattr(branch, 'run'):
+        return branch.run(value)   # coroutine not awaited
+    result = branch(value)
+    if asyncio.iscoroutine(result):
+        return await result
+```
+
+**Impact:** Uncommon, but custom steps with only sync `run()` that return coroutines will misbehave in `ConditionalStep` / `SwitchStep` async paths.
+
+---
+
+## Known deferred behavior (documented, still open)
+
+### 4. Whole collections are not auto-mapped
+
+Passing a list into a normal step sends the **entire list** as one argument. Parallel/batch only kick in when explicitly configured.
+
+```python
+@piped
+def step(x): ...
+
+pipeline.run([1, 2, 3])  # step receives [1,2,3], not three scalars
+```
+
+**Status:** Intentionally deferred — see `CODE_REVIEW_CHECKLIST.md` line 10. Surprising if users expect implicit map behavior.
+
+---
+
+## Incomplete features
+
+| Feature | Status |
+|--------|--------|
+| `Pipeline.from_spec("yaml")` | ✅ Implemented (`spec.py`, `stepcraft[spec]`) |
+| `Graph.from_spec("yaml")` | ✅ Implemented — `graph:` block with `nodes`/`edges` |
+| `FanOutStep.async_run` + `parallel=` | ✅ Honors `parallel` on the async path |
+| `MapReduceStep.async_run` | ✅ Async mappers mapped concurrently per batch |
+| `jit` / `vectorize` on `@piped` | ✅ Warns when numba/numpy missing |
+| rsloop integration | ✅ Covered by the `test-rsloop` CI job |
+| Step hooks (`on_step`) | ✅ `Pipeline` + `Graph` run paths, see `hooks.py` |
+| Pipeline shared context | ✅ `Pipeline(steps, context=...)` + `get_context()` |
+| Configurable pools | ✅ `configure_pools(thread_workers=, process_workers=)` |
+| Runtime type-checking | ✅ beartype decorates every function via import hook |
+
+---
+
+## Design limitations / footguns
+
+**Circuit breaker half-open is single-probe (implemented; has open defects).** After the recovery timeout the breaker moves to `HALF_OPEN` and allows up to `CircuitBreakerConfig.half_open_max_calls` (default 1) trial calls; success closes it, failure re-opens it immediately. See `step.py` `_check_circuit_breaker` / `_record_failure`. ⚠️ Three defects in this logic are open — see **CR-2** (probe slot consumed before cancel check → permanent lock), **CR-3** (reset before schema check), and **CR-7** (non-atomic probe increment) above.
+
+**Sync timeouts leave worker threads running.** On timeout, `fut.result(timeout=...)` raises but the thread-pool worker keeps executing `_invoke_function`. `@piped(cancel_on_timeout=True)` makes a best-effort `fut.cancel()`, which only helps if the worker has not started — a running thread cannot be interrupted. Documented footgun under load.
+
+**Process pools are global and long-lived.** `_POOLS` only shuts down via `cleanup_pools()` (Pipeline context manager or explicit call). Long-running apps can accumulate idle pools.
+
+**`@node` mutates class metadata** via `inst.__class__.__name__ = ...` — unusual pattern; each decorated function gets its own inner class so it works, but fragile.
+
+**`retry` / `circuit_breaker` are immutable (resolved).** Both return a **new** `PipeStep` via `PipeStep.copy()` with fresh breaker counters, so decorating the same step twice or reusing across pipelines no longer shares state.
+
+**`parallel` + `batch_size` together** — parallel wins; batching is skipped. Documented and tested, but easy to misconfigure.
+
+---
+
+## Test coverage gaps
+
+No tests for:
+
+- async `batch_size`
+- async `parallel='thread'` / `'process'` with async functions
+- `FanOutStep.async_run` with `parallel=`
+- `MapReduceStep.async_run` with async mapper/reducer
+- half-open circuit breaker probe semantics
+- rsloop in CI (only optional local tests)
+
+---
+
+## What looks solid
+
+Previously flagged checklist items appear fixed and covered by tests:
+
+- Circuit breaker records one failure per logical call (not per retry)
+- Async timeout honors `timeout=0.0`
+- Parallel forwards kwargs (sync and async)
+- Batched does not sum booleans
+- FanOut process parallel uses picklable helper
+- Topo sort cached; deque used instead of `list.pop(0)`
+- Shared thread pool for sync timeouts
+- Branch helpers deduplicated
+
+**89 tests pass** locally with rsloop installed (3 skipped).
+
+---
+
+## Suggested priority
+
+The async/spec/parallel items from the original audit are now resolved (see
+**Incomplete features**). Remaining work is the code-review pass:
+
+1. **CR-1** — propagate shared context into pool workers (or document the limit). Highest user-facing impact.
+2. **CR-2** — half-open probe consumed before cancel check → breaker permanently stuck. Correctness.
+3. **CR-3** — move schema validation before breaker reset.
+4. **CR-4** — activate shared context in `Graph` (extract a shared helper).
+5. **CR-5** — forward `on_step` through `map`/`async_map`/`run_async`/`map_async` (or narrow the docs).
+6. **CR-6** — reject specs that contain both `graph:` and `steps:`.
+7. **CR-7** — lock breaker state (or document non-thread-safety). Lowest priority.

stepcraft-0.1.0/CLAUDE_CODE_HANDOFF.md

@@ -0,0 +1,209 @@
+# stepcraft — Claude Code Handoff Plan
+
+**Author:** Senior review / planning pass  
+**Date:** 2026-06-24  
+**Sub-agent:** claude-code (available after quota reset ~12:50 AM Asia/Calcutta)  
+**Branch:** `working_barnch`
+
+This file is the **source of truth** for what is done, what was started tonight, and what claude-code should build next. Read this before any feature work.
+
+---
+
+## Already shipped (do not redo)
+
+| Area | Status | Key commits / files |
+|------|--------|---------------------|
+| Async `batch_size` awaits coroutines | Done | `step._execute_batched_async` |
+| Async `parallel` awaits coroutines | Done | `step._execute_parallel_async` |
+| `_async_run_branch_value` awaits `run()` coroutines | Done | `utils.py` |
+| List auto-map on default `@piped` | Done | `step._should_auto_map`, lists only (not tuples) |
+| `Pipeline.from_spec` YAML/JSON | Done | `spec.py`, `pip install stepcraft[spec]` |
+| FanOut / MapReduce async parity | Done | `fan.py` |
+| jit/vectorize warnings | Done | `decorators.py` |
+| rsloop CI job | Done | `.github/workflows/ci.yml` `test-rsloop` |
+| Free-threaded 3.14 parallel | Done | `runtime.py`, `parallel='auto'` |
+
+**Tests:** 114+ passed locally. Run `uv run pytest tests/ -v` before every PR.
+
+---
+
+## Started tonight (manager pass — verify / extend)
+
+Claude-code should **read the diff** and finish tests/docs if incomplete:
+
+### A. `@piped(auto_map=False)` opt-out
+- **Why:** Steps that intentionally receive a whole list must not be split.
+- **Files:** `decorators.py`, `step.py`, `tests/test_pipeline.py`
+- **Acceptance:**
+  - `@piped(auto_map=False)` passes `[1,2,3]` as one argument
+  - Default remains auto-map on multi-item lists
+  - `__call__` / partial binding preserves `auto_map`
+
+### B. Immutable `retry` / `circuit_breaker`
+- **Why:** Decorating the same `PipeStep` twice or reusing across pipelines must not share breaker counters.
+- **Files:** `step.py` (`PipeStep.copy()`), `decorators.py`
+- **Acceptance:**
+  - `@retry` / `@circuit_breaker` return a **new** `PipeStep` via `copy()`
+  - Fresh `_circuit_state`, `_failure_count`, `_last_failure_time`
+  - Existing tests still pass; add test that two decorated copies do not share breaker state
+
+### C. `Pipeline.async_run_detailed()`
+- **Why:** Parity with `run_detailed()` for async pipelines.
+- **Files:** `pipeline.py`, `tests/test_pipeline.py`
+- **Acceptance:**
+  - Returns `ExecutionResult` with history, `dt`, `n`
+  - Works with async `@piped` steps and sync steps (executor fallback in `async_run`)
+
+---
+
+## Phase 1 — Claude-code (high priority, ~1 session)
+
+### 1. Step hooks / observability
+**Goal:** Callback after each step without wrapping functions.
+
+```python
+# API sketch (finalize in hooks.py)
+StepHook = Callable[[str, Any, Any, float], None]  # name, input, output, step_dt
+
+pipeline.run(seed, on_step=hook)
+pipeline.run_detailed(seed, on_step=hook)  # hook in addition to history
+await pipeline.async_run(seed, on_step=hook)
+await pipeline.async_run_detailed(seed, on_step=hook)
+```
+
+**Files to add/touch:**
+- `src/stepcraft/hooks.py` — `StepHook` type alias, `_call_hook` helper
+- `pipeline.py` — optional `on_step` on run paths
+- `graph.py` — optional `on_step` on `run` / `async_run` (per node)
+- `tests/test_pipeline.py` — hook called N times, receives correct I/O
+
+**Rules:**
+- Hook errors must **not** swallow pipeline errors (wrap in try/except log or re-raise based on strict flag — default: log warning, continue)
+- `on_step` is optional; no breaking changes to existing signatures (use keyword-only)
+
+### 2. Update `AUDIT.md` + `README.md`
+- Mark fixed bugs incomplete features as resolved
+- Document: `auto_map`, `parallel='auto'`, `from_spec`, free-threading, `pip install stepcraft[spec]`
+- Add short “Parallelism” section: GIL vs 3.14t vs `process`
+
+### 3. `@piped(map=False)` alias
+- If manager used `auto_map`, add `map: Optional[bool] = None` where `map=False` ≡ `auto_map=False` for README-friendly naming (single implementation).
+
+---
+
+## Phase 2 — Claude-code (production hardening)
+
+### 4. Circuit breaker single-probe half-open
+**Location:** `step.py` `_check_circuit_breaker`, `_record_failure`, `_reset_circuit_breaker`
+
+**Behavior:**
+- `HALF_OPEN`: allow **one** trial call; success → `CLOSED`, failure → `OPEN`
+- Add `CircuitBreakerConfig.half_open_max_calls: int = 1` (optional, default 1)
+- Tests: `test_circuit_breaker_half_open_single_probe`
+
+### 5. Configurable thread/process pools
+**Location:** `pools.py`
+
+```python
+def configure_pools(*, thread_workers: int | None = None, process_workers: int | None = None) -> None
+```
+
+- Apply on next `_get_pool` creation; document that reconfigure requires `cleanup_pools()` first
+- Test: pool respects max_workers when set
+
+### 6. Sync timeout cancellation note + optional flag
+- Document that timed-out sync work keeps running in thread pool (AUDIT footgun)
+- Optional: `cancel_on_timeout=True` on `@piped` — best-effort, document limitations
+- **Low priority** if complex; documenting is enough for Phase 2
+
+---
+
+## Phase 3 — Claude-code (larger features)
+
+### 7. Pipeline shared context
+```python
+Pipeline(steps, context={"request_id": "abc"})
+# Steps access via contextvar or optional kw PIPE_CONTEXT
+```
+
+- Use `contextvars.ContextVar[dict]` set at pipeline run entry
+- `Node.setup()` can read context
+- Do **not** break existing step signatures
+
+### 8. `from_spec` graph support
+Extend `spec.py`:
+```yaml
+graph:
+  nodes:
+    a: { import: "mymodule:fetch" }
+    b: { import: "mymodule:parse" }
+  edges:
+    - [a, b]
+  seed_node: a
+```
+
+- `Graph.from_spec(path)` or `Pipeline.from_spec` detects `graph:` key
+- Tests with fixture YAML
+
+### 9. CI: `python3.14t` job
+- Ubuntu job installing free-threaded CPython when available on setup-python
+- Run `tests/test_pipeline.py -k "free_threading or parallel_auto"`
+- Skip gracefully if 3.14t not on runner
+
+---
+
+## Phase 4 — Defer unless user asks
+
+- Streaming / lazy iterator pipelines
+- Checkpoint / resume for graphs
+- Pydantic schema validation (optional dep)
+- OpenTelemetry exporter (build on hooks)
+
+---
+
+## Conventions for claude-code
+
+1. **Minimal diff** — match existing style in `step.py`, `decorators.py`
+2. **Tests required** for every behavior change
+3. **No new required dependencies** — optional extras only (`spec`, `rsloop`, etc.)
+4. **Do not commit** unless user asks (manager may commit manager pass)
+5. **Run before handoff:** `uv run pytest tests/ -q`
+6. **Import surface:** export new public APIs from `__init__.py` + `pipeline` shim if tests import from `pipeline`
+
+---
+
+## Suggested claude-code prompt (copy-paste)
+
+```
+Read CLAUDE_CODE_HANDOFF.md fully. You are implementing stepcraft on branch working_barnch.
+
+1. Verify items in "Started tonight" (A–C) — add missing tests, fix gaps.
+2. Implement Phase 1 items 1–3 (hooks, docs, map= alias).
+3. Run full test suite; fix failures.
+4. Summarize what changed and what remains for Phase 2.
+
+Do not commit unless I ask. Follow existing code conventions.
+```
+
+---
+
+## Manager pass checklist
+
+- [x] Write this handoff file
+- [x] `auto_map=False` implementation
+- [x] `PipeStep.copy()` + immutable decorators
+- [x] `async_run_detailed()`
+- [x] Tests for above
+- [x] Commit manager pass (if user approves) — `3c7e1f4`, pushed
+
+---
+
+## Scheduled trigger (12:51 AM IST)
+
+- **Set:** 2026-06-24 ~21:38 IST
+- **Fires:** 2026-06-25 00:51:00 Asia/Kolkata
+- **Script:** `scripts/trigger_claude_code_at_1251.sh`
+- **Wake sentinel:** `AGENT_LOOP_WAKE_CLAUDE_CODE`
+- **Remote:** `origin/working_barnch` @ `3c7e1f4`
+
+To cancel: kill the background sleeper PID shown in terminal metadata.