No approval, ask or park assumes a human: replace human.approve and the human-keyed vocabulary #521

Closed
opened 2026-10-27 13:36:39 +00:00 by sam · 0 comments
Owner

An approval, ask or parked task can be resolved by an operator, a rule, a classifier or automatically, but the code keys these on a human. Replace the approver-assuming vocabulary; leave plain English ('human-readable', a PR review's human-vs-machine authorship score) alone.

Identifiers (wire, storage and state, need migrations):

  • step type human.approve (control_steps.go, shipped feasibility.yaml, workflow-graph/workflow-triggers/StepEditor on the canvas, step-icons 'human: People' category)
  • park class needs_human / ParkNeedsHuman (taskstate, storecontract, tasks.sql and its default in 0001, TaskTable label)
  • event kinds human_approved, human_rejected, human_rereviewed (events.go, live-events.ts, timeline)

Contracts and docs that describe the decider as a human: messaging ApprovalRequester and the clarify/picker/questionnaire interactive requests, gatewayrpc ask handling, Telegram interactive replies, chat.proto ask comments, taskactions attribution (keep the person-vs-agent distinction, drop 'human' as the name), webmcp's 'never claim a human approved'.

Agent prompts that write for 'the human': shipped implement, remediate, triage ('a design document for a human to approve'), feasibility (assess reasons), prreview verify ('a human reviewer').

The PRD plan document setting moves to the replacement step.

Acceptance criteria

No step type, park class, event kind, contract doc or agent prompt names a human as the decider; plain-English uses remain; existing rows and events migrate.

Notes

Full inventory from git grep -i human over every tracked file (244 lines, 15 more in generated code that regenerates). Grouped by what has to change.

Identifiers (wire, storage, state; need a migration and regenerated code)

  • step type human.approve: domain/workflow/control_steps.go:19,57,59; shipped/feasibility.yaml:87; workflow_call.go:119; workflowsteps.go:57; taskstate.go:111 (ApprovalPlan); WORKFLOWS.md:74,111,220,226,299; ui workflows/workflow-graph.ts:161 ("Human approval"),199; workflow-triggers.ts:89; StepEditor.vue:58; step-icons.ts:10,21 (category "human"/"People"); tests control_steps_test.go:48,73,257, workflow_call_test.go:61, ui/test/workflow-edit.test.ts:83,116; e2e/checks/workflow-phone.cjs:85
  • park class needs_human / ParkNeedsHuman: taskstate.go:261,264,300,307; storecontract.go:51; task/task.go:126; state.proto:462-463; migrations/0001:42 (column default); queries/tasks.sql:157,213,234,258,269,282; postgres/steps.go:333, store.go:285; daemon daemon.go (9 sites), workflow_identity.go (8), workflow_org.go (2), park_test.go, workflow_identity_test.go, workflow_org_test.go; ui TaskTable.vue:36
  • alert kind task.needs_human / needsHuman: domain/alert/alert.go:1,65; postgres/task_alerts.go:31-79; migrations/0046 comment; ui alerts/alerts.ts:1
  • event kinds human_approved / human_rejected / human_rereviewed: events/events.go:47,48,56,57,175; taskactions/service.go:116-174 (Actor.Human, kind by actor); ui stores/live-events.ts:30-32; chat.proto:228; webui/api_tasks.go:355; CHANGELOG.md:967 (history, leave)
  • "Needs you" grouping: taskstate.go:203,209 (NeedsYou), webui/api_tasks.go:45-55, ui NeedsYouCard.vue:16, task-meta.ts:103, task-filter.ts:20

Approval and ask contracts that name the decider a human (docs and model-facing text)

  • tool approval: domain/messaging/approval.go:9-36; tools/approval.go:9,12; tools/classification.go:21; tools/disclosure.go:154 (error text); agentexec/modelloop/toolset.go:69,127; gateway/session_tools.go:255; channels/telegram/approval.go:23,32,44,136,137,328; telegram.go:82,86,92,609
  • clarify/picker/questionnaire: domain/messaging/interactive.go (18 lines incl. ErrEmptyReply text at 150); gateway/interactive_tools.go:12,19,23,41,59,60,61,108,162,177 (model-facing tool descriptions); gatewayrpc/client.go:143,201; channels/telegram/interactive.go:16-130; container/pool.go:158,500; gateway/gateway.go:850
  • delivery gates: domain/workflow/agent.go:42,44,227; agentrun/protocol.go:15; app/archied/main.go:4
  • ui: lib/webmcp.ts:46; components/ui/button/index.ts:21

Agent prompts and product copy

  • shipped/implement.yaml (now fixed), remediate.yaml:17, triage.yaml:16 ("for a human to approve"),31, feasibility.yaml:23
  • prreview_stages_verify.go:89 ("a human reviewer")
  • gateway/templates/product-guide.md:1 ("require human review")
  • docs/guides/first-playbook.md:58, docs/github-token.md:21, docs/prds/external-agent-harness.md:161,226

Leave as is (plain English or identity kind, not a decider)

  • "human-readable" (14 lines), go-humanize, ui lib/format.ts:6, gateway.go:990 relativeAge, dashboard_tools.go:17 label
  • prreview_stages.go:214,221 and prreview/scoring.go:323 (human vs machine authorship, readers)
  • telegram/live.go:22, messaging/chat_stream.go:26,27, gateway/message_dedup.go:118, gateway.go:567,582, webui/api_config.go:32, releaseupdate/format.go:8, timeline-event.ts:2,121, MappingForm.vue:28, deployments/systemd-user-service.md:190 (a person reading output, not deciding)
  • identity kinds: daemon/workflow_identity_test.go:221, staterpc/identity_start_test.go:24,65, webui/api_workflows_test.go:69,70, prompts/organisation-automation/01-execution-identities.md:32,62, identity/org "person" (a user identity vs an agent)
  • migrations/0055 (history), CHANGELOG.md:287,412

Close reason

Step type, park class, event kinds, alert kind and the needs-attention grouping renamed off the human key; 0061 migrates stored values, workflow definitions and pinned task YAML with digests recomputed. Prose, contracts, prompts and docs no longer name a person as the decider.


Imported from beads archie-core-0li8z · GitHub #1840 · type task · priority P2 · created 2026-10-25 · closed 2026-10-25

An approval, ask or parked task can be resolved by an operator, a rule, a classifier or automatically, but the code keys these on a human. Replace the approver-assuming vocabulary; leave plain English ('human-readable', a PR review's human-vs-machine authorship score) alone. Identifiers (wire, storage and state, need migrations): - step type human.approve (control_steps.go, shipped feasibility.yaml, workflow-graph/workflow-triggers/StepEditor on the canvas, step-icons 'human: People' category) - park class needs_human / ParkNeedsHuman (taskstate, storecontract, tasks.sql and its default in 0001, TaskTable label) - event kinds human_approved, human_rejected, human_rereviewed (events.go, live-events.ts, timeline) Contracts and docs that describe the decider as a human: messaging ApprovalRequester and the clarify/picker/questionnaire interactive requests, gatewayrpc ask handling, Telegram interactive replies, chat.proto ask comments, taskactions attribution (keep the person-vs-agent distinction, drop 'human' as the name), webmcp's 'never claim a human approved'. Agent prompts that write for 'the human': shipped implement, remediate, triage ('a design document for a human to approve'), feasibility (assess reasons), prreview verify ('a human reviewer'). The PRD plan document setting moves to the replacement step. ### Acceptance criteria No step type, park class, event kind, contract doc or agent prompt names a human as the decider; plain-English uses remain; existing rows and events migrate. ### Notes Full inventory from `git grep -i human` over every tracked file (244 lines, 15 more in generated code that regenerates). Grouped by what has to change. Identifiers (wire, storage, state; need a migration and regenerated code) - step type human.approve: domain/workflow/control_steps.go:19,57,59; shipped/feasibility.yaml:87; workflow_call.go:119; workflowsteps.go:57; taskstate.go:111 (ApprovalPlan); WORKFLOWS.md:74,111,220,226,299; ui workflows/workflow-graph.ts:161 ("Human approval"),199; workflow-triggers.ts:89; StepEditor.vue:58; step-icons.ts:10,21 (category "human"/"People"); tests control_steps_test.go:48,73,257, workflow_call_test.go:61, ui/test/workflow-edit.test.ts:83,116; e2e/checks/workflow-phone.cjs:85 - park class needs_human / ParkNeedsHuman: taskstate.go:261,264,300,307; storecontract.go:51; task/task.go:126; state.proto:462-463; migrations/0001:42 (column default); queries/tasks.sql:157,213,234,258,269,282; postgres/steps.go:333, store.go:285; daemon daemon.go (9 sites), workflow_identity.go (8), workflow_org.go (2), park_test.go, workflow_identity_test.go, workflow_org_test.go; ui TaskTable.vue:36 - alert kind task.needs_human / needsHuman: domain/alert/alert.go:1,65; postgres/task_alerts.go:31-79; migrations/0046 comment; ui alerts/alerts.ts:1 - event kinds human_approved / human_rejected / human_rereviewed: events/events.go:47,48,56,57,175; taskactions/service.go:116-174 (Actor.Human, kind by actor); ui stores/live-events.ts:30-32; chat.proto:228; webui/api_tasks.go:355; CHANGELOG.md:967 (history, leave) - "Needs you" grouping: taskstate.go:203,209 (NeedsYou), webui/api_tasks.go:45-55, ui NeedsYouCard.vue:16, task-meta.ts:103, task-filter.ts:20 Approval and ask contracts that name the decider a human (docs and model-facing text) - tool approval: domain/messaging/approval.go:9-36; tools/approval.go:9,12; tools/classification.go:21; tools/disclosure.go:154 (error text); agentexec/modelloop/toolset.go:69,127; gateway/session_tools.go:255; channels/telegram/approval.go:23,32,44,136,137,328; telegram.go:82,86,92,609 - clarify/picker/questionnaire: domain/messaging/interactive.go (18 lines incl. ErrEmptyReply text at 150); gateway/interactive_tools.go:12,19,23,41,59,60,61,108,162,177 (model-facing tool descriptions); gatewayrpc/client.go:143,201; channels/telegram/interactive.go:16-130; container/pool.go:158,500; gateway/gateway.go:850 - delivery gates: domain/workflow/agent.go:42,44,227; agentrun/protocol.go:15; app/archied/main.go:4 - ui: lib/webmcp.ts:46; components/ui/button/index.ts:21 Agent prompts and product copy - shipped/implement.yaml (now fixed), remediate.yaml:17, triage.yaml:16 ("for a human to approve"),31, feasibility.yaml:23 - prreview_stages_verify.go:89 ("a human reviewer") - gateway/templates/product-guide.md:1 ("require human review") - docs/guides/first-playbook.md:58, docs/github-token.md:21, docs/prds/external-agent-harness.md:161,226 Leave as is (plain English or identity kind, not a decider) - "human-readable" (14 lines), go-humanize, ui lib/format.ts:6, gateway.go:990 relativeAge, dashboard_tools.go:17 label - prreview_stages.go:214,221 and prreview/scoring.go:323 (human vs machine authorship, readers) - telegram/live.go:22, messaging/chat_stream.go:26,27, gateway/message_dedup.go:118, gateway.go:567,582, webui/api_config.go:32, releaseupdate/format.go:8, timeline-event.ts:2,121, MappingForm.vue:28, deployments/systemd-user-service.md:190 (a person reading output, not deciding) - identity kinds: daemon/workflow_identity_test.go:221, staterpc/identity_start_test.go:24,65, webui/api_workflows_test.go:69,70, prompts/organisation-automation/01-execution-identities.md:32,62, identity/org "person" (a user identity vs an agent) - migrations/0055 (history), CHANGELOG.md:287,412 ### Close reason Step type, park class, event kinds, alert kind and the needs-attention grouping renamed off the human key; 0061 migrates stored values, workflow definitions and pinned task YAML with digests recomputed. Prose, contracts, prompts and docs no longer name a person as the decider. --- _Imported from beads `archie-core-0li8z` · GitHub #1840 · type task · priority P2 · created 2026-10-25 · closed 2026-10-25_
sam added the mediumtask labels 2026-10-27 13:36:39 +00:00
sam self-assigned this 2026-10-27 13:36:39 +00:00
sam closed this issue 2026-10-27 13:36:39 +00:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: sam/archie#521