ThothII/docs/contracts/workflow-observable-baseline.md

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

Run npm test from the harness package.

The gate suite fixes:

• the registered Pi tool names and their required and optional parameters;
• the exact workflow definition and 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 acceptance and rejection;
• F8 Memory promotion accepted, declined, and absent, including mutation failure ordering;
• artifact payload compatibility, anti-bypass behavior, and final phase closing.

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

Run the backend test suite followed by TypeScript typechecking. The suite fixes:

• 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

Run the frontend test suite followed by TypeScript typechecking. The suite fixes:

• 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.

Pre-existing full-suite exceptions

The workflow baseline and every focused seam above pass on the source commit from which this branch was created. Two unrelated full-suite failures also reproduce unchanged on that base checkout and are therefore recorded rather than hidden or repaired in this refactoring ticket:

• 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.

The focused backend workflow suite, backend typecheck and build, focused frontend workflow suite, frontend typecheck and build, complete harness pytest suite, Ruff, and complete Pi gate suite all pass. These two exceptions must remain visible until their owning workstream resolves them; they must not be used to relax any workflow assertion.