134 lines
6.4 KiB
Markdown
134 lines
6.4 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
|
|
|
|
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;
|
|
- a newly folded phase is announced once in RPC mode even when it requires no human gate;
|
|
- 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:
|
|
|
|
```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/workspaces/evidence/materialization.test.ts \
|
|
test/workspaces/evidence/preprocessing.test.ts \
|
|
test/workspaces/evidence/boundary.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;
|
|
- reserved Pi phase notifications mapped to sanitized `phase_started` client events;
|
|
- 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;
|
|
- phase progress and the active workflow dot advancing on `phase_started` without a `ui_request`;
|
|
- 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.
|