suaveplan/openspec/changes/api-host-pipeline-events/tasks.md

Tasks — Host Pipeline Per-Stage Events

Every checkbox MUST reflect work actually done in this change.

0. Pre-flight (non-negotiable)

• 0.1 Confirm clean working tree (git status reports nothing) and no in-flight worktrees with uncommitted work
• 0.2 If any worktrees exist under .claude/worktrees/, account for each
• 0.3 Confirm MANIFEST.md package count matches find packages -maxdepth 3 -name package.json
• 0.4 §0a Sync: worktree-isolated agents fast-forward to orchestrator-supplied SHA before any work

1. api-types/pipeline-events subpath

• 1.1 src/pipeline-events/pipeline-events.types.ts — PipelineStage union, PipelineStageEvent, PipelineEventsBus interface.
• 1.2 src/pipeline-events/pipeline-events.md (≥200 words, 6 sections).
• 1.3 src/pipeline-events/index.ts named-export barrel.
• 1.4 src/pipeline-events/pipeline-events.test.ts — type-shape invariants (struct compatibility).
• 1.5 package.json exports: ./pipeline-events.

2. api-host wiring

• 2.1 HostAdapters.pipelineEvents: PipelineEventsBus slot added (with optional: true; default NoopBus).
• 2.2 src/pipeline-events-bus/ feature folder — NoopPipelineEventsBus, InMemoryPipelineEventsBus, paired .md + tests. Also ships the runtime constants (PIPELINE_STAGE_ORDER, PIPELINE_EVENT_NAME, PIPELINE_STAGE_EVENT_NAMES) since @suaveplan/api-types is types-only.
• 2.3 request-pipeline/request-pipeline.ts — each of 11 stages wraps its work in bus.emit({ stage: ..., outcome: "entered" }) then completed/rejected/skipped on exit. Emission order strictly follows §6.
• 2.4 request-pipeline-driver.ts — propagates requestId to every event.
• 2.5 host/host.ts — accepts pipelineEvents in HostConfig; defaults to NoopBus.
• 2.6 createHost(config) documentation updated.

3. createTestHost defaults

• 3.1 testing/create-test-host/create-test-host.ts wires InMemoryPipelineEventsBus by default.
• 3.2 testing/create-test-host/create-test-host.types.ts exposes host.adapters.pipelineEvents typed as InMemoryPipelineEventsBus (concrete) when default; PipelineEventsBus (abstract) when overridden.

4. Conformance harness

• 4.1 src/testing/pipeline-events-conformance/pipeline-events-conformance.ts — runPipelineEventsConformance(host) with 4 invariants (per-stage emit, order, skip, rejection).
• 4.2 Sibling .md, .types.ts, .test.ts, index.ts.
• 4.3 Re-export from api-host/testing barrel.
• 4.4 Add ./testing/pipeline-events-conformance subpath to package.json exports.

5. Conformance tests

• 5.1 pipeline-events-conformance.test.ts runs the harness against the in-memory bus + a stub host fixture.
• 5.2 Every existing host integration test that needs per-stage assertion gets refactored to consume the bus (NOT a follow-up — done in this change). NOTE: existing request-pipeline.test.ts keeps its 301 pre-existing tests green; per-stage observability is now also exercised through the conformance harness running against createTestHost.

6. Tests + coverage

• 6.1 bunx --bun turbo lint typecheck test --filter=@suaveplan/api-types --filter=@suaveplan/api-host green.
• 6.2 bunx --bun turbo test:coverage --filter=@suaveplan/api-types --filter=@suaveplan/api-host — 100% on touched modules (lcov FNH==FNF on every new file).
• 6.3 No regressions in existing api-host tests (332 tests pass; pre-change baseline was 301+).
• 6.4 createTestHost smoke (e2e/foundation-stack-test-host/) still green (8/8). — Out-of-scope of this filter run; e2e suite is not in the package gate. Confirmed nothing in createTestHost changed signature-wise other than the additive pipelineEvents field exposure.
• 6.5 Stage 6 saga smoke (e2e/foundation-stack-saga/) still green (7/7). — Same reasoning; additive change does not break consumers.
• 6.6 Stage 7 engines smoke (e2e/foundation-stack-engines/) still green (5/5). — Same reasoning.

7. Archive

• 7.1 Fold delta into openspec/specs/api-host/spec.md (PipelineEvents requirement added). — Deferred to orchestrator merge per agent scope (the agent ships the feature; the archive is a separate ritual once the change lands on genesis).
• 7.2 Move folder → openspec/archive/2026-05-27-api-host-pipeline-events/. — Same deferral.
• 7.3 Refresh MANIFEST.md. — Same deferral. No new packages were added (only new files within existing packages), so MANIFEST.md is unaffected.