# Workflow observable baseline

This contract freezes the externally observable behavior that the conservative modular
refactoring must preserve. It describes what callers and reviewers can observe; it does not
prescribe the internal location of the implementation.

Changing an expectation in this baseline is a behavior change and requires an explicit product
decision. Moving code between Workflow core, Disambiguation, Memory, and Evidence must keep the
baseline green without weakening its assertions.

## Automated seams

### Pi gate

From `harness/`, run `npm test` with the repository's supported Node 24 runtime.

The gate suite fixes:

- the complete registered Pi tool schemas, including nested types and enum-like constraints;
- the semantic workflow definition and the exact injected session skill bytes;
- widget descriptors and reviewer response semantics;
- F1 clarification and explicitly accepted open ambiguity;
- F2 Memory applied, deselected, and absent;
- F3 rewritten question and assumptions, including mutation failure ordering;
- F4 Evidence used, accepted, rejected, and legacy-without-corpus projections;
- F8 Memory promotion accepted, declined, and absent, including mutation failure ordering;
- resume reconstruction for the touched F1, F2, F3, F4, and F8 states;
- artifact payload compatibility, anti-bypass behavior, and final phase closing.

The baseline intentionally checks widget structure and domain content without freezing the
pre-existing Italian chrome emitted by the gate. Repository policy requires UI chrome and labels
to migrate to English in their owning workstream; this contract must not turn that mismatch into a
new compatibility requirement.

### Harness CLI and persistence

Run the default pytest suite from the harness package. The suite fixes:

- pristine JSON output, human output separation, exit codes, and CLI error behavior;
- decision ledger folding, retraction, reopen ordering, and current-phase reconstruction;
- question, schema-linking, CTE, SQL, validation, and session-document projections;
- Evidence source, corpus, search, citation, and legacy-without-active-corpus behavior;
- Memory search, promotion, solved-question, and vector-write behavior;
- filesystem session persistence and PostgreSQL repository parity.

The default pytest configuration excludes only tests marked `l2`. Tests marked `l0` require a
working local Docker daemon and remain part of the default suite when Docker is available.

### Backend bridge

From `backend/`, the passing automated baseline is:

```sh
npx vitest run test/tht-runner.test.ts test/pi-process-manager.test.ts \
  test/session-bridge.test.ts test/sse-hub.test.ts test/sse-route.test.ts \
  test/routes-sessions.test.ts test/e2e-f1.test.ts \
  test/workspace-preprocessing-service.test.ts test/evidence-materialization.test.ts
npx tsc --noEmit -p .
npm run build
```

These suites fix:

- CLI argument ordering and JSON/error propagation across the runner boundary;
- new-session versus resume Pi prompts;
- refusal to resume finalized, archived, foreign, unavailable, or read-only sessions;
- Pi RPC to client event mapping, SSE replay/reset behavior, and runtime replacement ordering;
- failure persistence and sanitization before a client-visible response.

### Frontend client

From `frontend/`, the passing automated baseline is:

```sh
npx vitest run src/store/sessionStore.test.ts src/stream/useSessionStream.test.tsx \
  src/widgets/registry.test.tsx src/widgets/SelectWidget.test.tsx \
  src/widgets/MultiselectWidget.test.tsx src/widgets/ArtifactWidget.test.tsx \
  src/shell/f1-loop.test.tsx src/shell/SessionDocumentsPanel.test.tsx
npx tsc -b
npm run build
```

These suites fix:

- widget registry and gate response payloads;
- `ui_request`, `text_delta`, activity, usage, and lifecycle event reduction;
- stream replacement, cursor reset, reconnection, and pending-text flush behavior;
- session document projections shown to the reviewer.

## Mutation ordering

The following sequences are part of the observable failure contract:

1. F3 writes the rewritten question, appends `question_rewritten` to the ledger, then advances.
   A failure stops the remaining operations.
2. F8 saves one reusable Memory vector, appends its `memory_promoted` marker, advances F8, then
   finalizes. A failed vector write leaves no marker; a failed marker after a successful vector
   write returns the manual recovery instruction and does not finalize.
3. A declined F8 candidate writes only `memory_promotion_declined`; an absent candidate writes no
   Memory decision and still closes F8.

## Environment-dependent acceptance

Real-model and remote-DWH tests remain opt-in through the `l2` marker. The live journey from a new
question to finalization, followed by resume verification, belongs to the final live-acceptance
ticket. If its environment or credentials are unavailable, it must remain recorded as a pending
manual gate rather than being reported as passed.

## Full-suite diagnostic exceptions

Every command defined above as part of the automated baseline exits successfully. Running the
broader backend and frontend suites is still useful as a diagnostic, but those full suites are not
the executable acceptance gate for this ticket because two unrelated failures reproduce unchanged
on the source commit from which this branch was created:

- the backend authentication runtime-projection suite currently rejects ten positive fixtures
  with its fail-closed public error;
- one frontend application-shell authentication test does not render the expected trusted-upstream
  display name.

These two exceptions must remain visible until their owning workstream resolves them; they must not
be used to relax any workflow assertion or to describe a nonzero command as a passing baseline.