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/.pi/skills/tht-sessione/SKILL.md is a committed projection. Its authoritative Disambiguation and Memory fragments live under modules/; from harness/, run python -m tht.pi_skill_projection --write to regenerate it or --check to detect drift. Composition uses a static ordered tuple and never directory discovery.

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:

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:

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:

F3 writes the rewritten question, appends question_rewritten to the ledger, then advances. A failure stops the remaining operations.
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.
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.

6.0 KiB Raw Blame History