picatz / picatz/flowstate

decision: the humans a gate waits on have no browser surface, so every approval flows through a CLI, an MCP client, or a webhook bridge someone builds; the one page worth having is the gate

Open
#1,748 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

design enhancement kind/design-record
Dominant language
Go
Stars
9
Forks
0
Avg merge
3h 3m
Merged PRs (30d)
509

Description

Observed behavior

At eb8172f, a wait_for_signal gate is answered by flow signal (CLI), the flowstate_signal MCP tool, a webhook route (examples/webhook-approval-bridge), or a Slack message posted by the Slack plugin that a person then has to act on from somewhere else. The prompt the gate renders (waitprompt.go, #1659) says what is being asked; the flow inbox proposal (#1688) lists what is waiting. Every one of these assumes the approver has the CLI or an agent. Searching the tracker for a browser or dashboard surface finds nothing; the Temporal UI shows history, not a prompt with an approve button.

In every enterprise deployment the approver is a manager, an on-call engineer on a phone, or a compliance reviewer, and the thing they expect is a link: open it, see who asked, what for, with what inputs, and press one of the buttons the gate declares. signals: policy already decides who may answer (ResolveSignalPolicySubjects), identity already comes from OIDC (flow login --device is S6 in #567), and the audit trail already records the decision. The missing piece is one authenticated page per pending gate.

This is deliberately not a proposal for a workflow UI, a builder, or a dashboard. It is the minimum human surface the product's own gates imply, and it is the surface that turns "policy-governed" into something a non-engineer experiences.

Desired outcome

A design record deciding:

  • Scope: one route on flow server (/gates/<run>/<step>), rendered server-side from the same prompt the CLI prints, showing the workflow, the step, the prompt, the declared signal inputs as a form, and the buttons the gate's schema declares; a second route listing the gates the authenticated principal may answer (the browser form of #1688). Nothing else.
  • Authentication: the browser session comes from the deployment's OIDC issuer through the existing trust policy; the page carries no token of its own; CSRF and the fail-closed signals: decision are the same path Signal takes over Connect, so there is no second authorization mechanism.
  • Implementation shape: server-rendered HTML from Go templates with no JavaScript required for approve or deny, so the page works from a phone, an email client's browser, and a locked-down corporate desktop; a SvelteKit front end is the later decision if a richer surface is ever wanted, and this page is the contract it would consume.
  • Where the link comes from: the Slack plugin, the webhook bridge, and flow inbox all print the same URL, generated by one function.

Acceptance criteria

  • flow server with --gates-ui serves the two routes; without it, the routes do not exist (fail closed, the posture every optional surface here takes).
  • A conformance case: alice (allowed by signals:) opens the page and approves; carol (denied) sees a refusal, and both decisions are in the audit trail with the same records flow signal produces.
  • The appearance goldens gain the rendered page for the approval-gate example.

Constraints and dependencies

  • Adjacent: #1688 (flow inbox), #1659 (prompt rendering), #567 (S6 human OIDC login), #1733 (per-action authorization), docs/MCP_AUTHORIZATION.md, the Slack plugin.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with flow server, Signal over Connect, waitprompt.go, and the adjacent #1688 inbox proposal; also read docs/MCP_AUTHORIZATION.md and the references to OIDC login and per-action authorization. Produce a design record covering the two gated routes, authentication and fail-closed authorization, shared link generation, server-rendered forms, and the conformance and appearance-golden acceptance criteria.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
authentication, authorization, backend, testing, web-dev
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.