docs(blueprints): align F5-F7 and demo paths with the ADR-0005 escrow, approval and refund flows

[XxHugheadxX]

Closes #76

Summary

docs/blueprints/flows.md still described the direct SAC transfer, the six-check verification, authorize_feedback and the #10 states. F5–F7 and both demo paths now follow ADR-0005 (D1, D4, D5, D6, D8) and the relay contract in docs/architecture/api.md (#77). F1–F4 are unchanged.

• F5 Hire and pay is the escrow path:

  • the server prepares create_job, then fund;
  • the wallet signs each envelope unchanged, and the server verifies and relays it;
  • the tracker confirms fund and checks the job before the agent runs: state Funded, client and evaluator = consumer, provider = agent wallet, USDC, budget, expired_at.

  New edge rows:

  • JobMismatch / JobEvidenceUnavailable: the funds stay in the escrow until expired_at;
  • Cancel on an open hire: a reject from open, labeled Cancelled;
  • an unfunded hire past expired_at: shown as Expired, with no transaction.

• F6 Track, result and approve:

  • the hire stays Funded while the run shows Queued, Running or Failed;
  • it becomes Submitted after the server-signed submit;
  • the client approves with complete or rejects before the approval deadline;
  • with no decision, the tracker calls release and the hire is Completed (D4). The countdown UI comes by HackMeridian, and the window length is deferred (D3).

• Refund paths, each with its own edge row:

  • a failed run → the client's Reject and refund (primary);
  • the client never acts → claim_refund after expired_at, and the hire is Expired (fallback).

  A reject is final (D8), and only rejects of submitted work count against the client.

• F7 Rate:

  • it is offered only on a Completed hire with no rating, and there is no authorize_feedback: the paid-hire rule is a completed escrow job (D5);
  • the hire keeps a feedback reference and stays Completed;
  • HireAlreadyRated is the only "already rated" path.

• Demo paths: sign create_job and fund, show the escrow holding the USDC, then Funded → Submitted → Approve → Completed.

• Header: sources now cite ADR-0005 and the API contract.

Acceptance criteria

• No flow describes a direct SAC transfer to the agent wallet or the six-check verification
• F5–F7 match ADR-0005 D1, D4, D5 and D6, using the method mapping from the F5–F7 traceability tables in api.md
• Both refund paths have an error/edge row (F6 step 3: claim_refund after expired_at; F6 step 5: reject and refund)
• A reject from open is labeled "Cancelled" (F5 step 7, F6 step 6); no cancelled, failed, inProgress or rated hire state remains
• Every Mermaid diagram renders: all 7 checked, see below
• Screen IDs stay consistent with the consolidated list: no new screens; approve and reject live on S06-hire-detail

Verification evidence

The remaining matches for the stale terms are not hire states:

$ grep -nE "\bPaid\b|InProgress|inProgress|Delivered|\bRated\b|authorize_feedback|muxed|USDC transfer|six-check|\bcancelled\b|\bfailed\b" docs/blueprints/flows.md
34:  ... "Connection cancelled" ...                       (F1 wallet connection)
44:  ... "Connection cancelled" ...                       (F1)
118: ... "Tx failed" ...                                  (F4 registration tx)
130: ... step marked failed ...                           (F4 deploy step)
132: ... Tx failed ...                                    (F4)
182: runtime progress (`queued`, `running`, `failed`)     (RuntimeStatus, not a hire state)
188: "Run failed or timed out"                            (RuntimeStatus)
212: ... no `authorize_feedback` step.                    (explicitly removed)

I rendered every Mermaid block through mermaid.ink: all 7 diagrams return an SVG with no syntax error. F5, F6 and F7 are blocks 4, 5 and 6.

0 200 svg   1 200 svg   2 200 svg   3 200 svg   4 200 svg   5 200 svg   6 200 svg

Notes for reviewers

• Mapped, not invented. The flows use the method names and outcome codes from api.md (createHire, prepareFund, submitEscrowCall, prepareComplete, prepareReject, JobMismatch, HireAlreadyRated). Where docs: update MVP flows to ADR-0005 escrow and hire states #76's deliverable 1 says "signs authorization entries", the contract decided that the wallet signs the prepared envelope unchanged (Decision A), and these flows follow the contract.
• Out of scope. Wireframes (docs: wireframes and screen specs for all MVP screens #23), endpoint definitions (docs: API contract between Flutter app and Serverpod #8), timeout values (D3) and retry with another agent (D9) are untouched.

[cloudflare-workers-and-pages]

Deploying puls3 with    Cloudflare Pages

Latest commit:	03140ef
Status:	✅  Deploy successful!
Preview URL:	https://3c316353.puls3-4lw.pages.dev
Branch Preview URL:	https://docs-76-flows-adr0005.puls3-4lw.pages.dev

View logs

[TOMOKI977]

Approved. F5–F7 and both demo paths now match ADR-0005 and the relay contract in api.md:

• F5: create_job → fund, each signed unchanged and relayed by the server, then the tracker's job check before the run.
• F6: the hire stays funded while the run shows its own progress, then submitted → approve/reject, or release after the deadline.
• Edge paths: Cancel from open, the derived Expired state, and the refund paths.
• F7: feedback without authorize_feedback.

Some of it describes behavior that is still post-demo work: the tracker calling release and claim_refund (#97) and the server-signed submit (#18). That's fine for a flows document.