60 lines
4.5 KiB
Markdown
60 lines
4.5 KiB
Markdown
# Tasks — Host Pipeline Per-Stage Events
|
|
|
|
> Every checkbox MUST reflect work actually done in this change.
|
|
|
|
## 0. Pre-flight (non-negotiable)
|
|
|
|
- [x] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work
|
|
- [x] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each
|
|
- [x] 0.3 Confirm `MANIFEST.md` package count matches `find packages -maxdepth 3 -name package.json`
|
|
- [x] 0.4 §0a Sync: worktree-isolated agents fast-forward to orchestrator-supplied SHA before any work
|
|
|
|
## 1. api-types/pipeline-events subpath
|
|
|
|
- [x] 1.1 `src/pipeline-events/pipeline-events.types.ts` — `PipelineStage` union, `PipelineStageEvent`, `PipelineEventsBus` interface.
|
|
- [x] 1.2 `src/pipeline-events/pipeline-events.md` (≥200 words, 6 sections).
|
|
- [x] 1.3 `src/pipeline-events/index.ts` named-export barrel.
|
|
- [x] 1.4 `src/pipeline-events/pipeline-events.test.ts` — type-shape invariants (struct compatibility).
|
|
- [x] 1.5 `package.json` exports: `./pipeline-events`.
|
|
|
|
## 2. api-host wiring
|
|
|
|
- [x] 2.1 `HostAdapters.pipelineEvents: PipelineEventsBus` slot added (with `optional: true`; default NoopBus).
|
|
- [x] 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.
|
|
- [x] 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.
|
|
- [x] 2.4 `request-pipeline-driver.ts` — propagates `requestId` to every event.
|
|
- [x] 2.5 `host/host.ts` — accepts `pipelineEvents` in HostConfig; defaults to NoopBus.
|
|
- [x] 2.6 `createHost(config)` documentation updated.
|
|
|
|
## 3. createTestHost defaults
|
|
|
|
- [x] 3.1 `testing/create-test-host/create-test-host.ts` wires `InMemoryPipelineEventsBus` by default.
|
|
- [x] 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
|
|
|
|
- [x] 4.1 `src/testing/pipeline-events-conformance/pipeline-events-conformance.ts` — `runPipelineEventsConformance(host)` with 4 invariants (per-stage emit, order, skip, rejection).
|
|
- [x] 4.2 Sibling `.md`, `.types.ts`, `.test.ts`, `index.ts`.
|
|
- [x] 4.3 Re-export from `api-host/testing` barrel.
|
|
- [x] 4.4 Add `./testing/pipeline-events-conformance` subpath to package.json exports.
|
|
|
|
## 5. Conformance tests
|
|
|
|
- [x] 5.1 `pipeline-events-conformance.test.ts` runs the harness against the in-memory bus + a stub host fixture.
|
|
- [x] 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
|
|
|
|
- [x] 6.1 `bunx --bun turbo lint typecheck test --filter=@suaveplan/api-types --filter=@suaveplan/api-host` green.
|
|
- [x] 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).
|
|
- [x] 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.
|