96 lines
4.6 KiB
Markdown
96 lines
4.6 KiB
Markdown
# 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.
|