fix(confidence-engine): clarify relationship direction

docs/current-handoff.md

@@ -26,6 +26,13 @@
 - Owning deterministic tests pass. Ten broader orchestrator failures were observed and classified as unrelated to this increment, but were not proven pre-existing because non-mutating baseline execution was blocked by the existing Vitest apparatus.
 - No live validation has been rerun against this observability boundary. Next restart point: exactly one production-default `/api/cases/start` call using the fixed manufacturing scenario, comparing reconstruction relationship E directly with its projected graph edge.
 
+## v0.5 relationship direction contract
+
+- Directly observable v0.5 live validation proved first-class relationship declaration and deterministic projection work end-to-end, while exposing one `may_cause` directional inconsistency between endpoints and description.
+- v0.5 now defines relationships literally as `fromId → relationship → toId`: directional semantics are explicit for `depends_on`, `causes`, `may_cause`, `supports`, and `weakens`; `compares_with` may use either endpoint order.
+- The read-back rule requires relationship type, endpoint direction, and description to agree. Provenance and interpretation-separation rules remain unchanged.
+- Deterministic tests prove the instruction exists, not that the model obeys it. No live call has tested this refinement; next restart point is live directional-integrity validation before broader repeatability testing.
+
 ## Current product architecture
 
 Three distinct routes, not a single page:

prompts/reconstruct-v0.5.md

@@ -36,6 +36,8 @@ Reconstruction must preserve not only supplied semantic units but also relations
 
 Each relationship `fromId` and `toId` MUST reference IDs of semantic units already present elsewhere in `reconstruction`. Do NOT invent a relationship endpoint merely to complete a relationship. Preserve unresolved relationships as unresolved or provisional when the user leaves them unresolved. Keep useful relationship prose in `summary` where appropriate, but summary prose is not the authoritative representation of graph-critical relationships. Do not introduce an action recommendation or steering.
 
+Read every relationship literally as `fromId → relationship → toId`. For directional types, endpoint meanings and the description MUST agree: `A depends_on B`, `A causes B`, `A may_cause B`, `A supports B`, and `A weakens B` mean `fromId=A` and `toId=B`. Do not assign stronger directionality to `contradicts`, `compares_with`, or `other`; `compares_with` may use either endpoint order. Before emitting a relationship, read it back as “FROM [relationship] TO”. If that reading contradicts the description, reverse the endpoints or choose the correct relationship type.
+
 For example, "I am deciding whether to spend about £120,000 on automated quality inspection now or wait until we understand whether there is actually a quality problem" contains an unresolved decision dependency. A valid reconstruction can represent an unknown such as whether the complaint increase reflects a quality problem automated inspection could address (`u1`) and an unknown such as whether spending £120,000 on automated inspection now is appropriate (`u2`), then declare:
 
 ```json

tests/v03-reasoning.test.js

@@ -230,6 +230,21 @@ describe("v0.5 prompt", () => {
     expect(result.prompt).toContain("MUST reference IDs of semantic units");
   });
 
+  it("defines literal directional semantics for typed relationships", async () => {
+    const { prompt } = await buildPrompt("Direction contract scenario", "v0.5");
+
+    expect(prompt).toContain("fromId → relationship → toId");
+    expect(prompt).toContain("A depends_on B");
+    expect(prompt).toContain("A causes B");
+    expect(prompt).toContain("A may_cause B");
+    expect(prompt).toContain("A supports B");
+    expect(prompt).toContain("A weakens B");
+    expect(prompt).toContain("FROM [relationship] TO");
+    expect(prompt).toMatch(
+      /`?compares_with`? may use either endpoint order/,
+    );
+  });
+
   it("retains the provenance stop boundary and interpretation separation", async () => {
     const { prompt } = await buildPrompt("Contract retention scenario", "v0.5");