Make the registered step vocabulary discoverable: name gate.diff-rules where an operator hits it #1057

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

internal/domain/workflow/diff_rules.go documents gate.diff-rules as "the supported
migration target for the deleted .archie/gate.go hook", and nothing an operator can
reach says so:

  • internal/domain/workflow/steps.go:227 still refuses a legacy .archie/gate.go with
    "migrate its behavior to a registered YAML workflow step" and names no step type.
  • No runtime surface lists the vocabulary: no control-plane catalog resource, no webui
    route, no CLI command (manager.StepTypes() is read by tests only), and the dashboard
    editor seeds the YAML with just - type: (ui/src/workflows/WorkflowDefinitionsCard.vue:43).
  • Nothing under docs/ mentions the step type at all, including the PRD whose
    requirement this change exists to satisfy (docs/prds/runtime-control-plane.md,
    "Workflows", which still states "Their useful behavior must first be available as
    normal workflow steps" without naming one).
  • The control-plane resource carrying the rules is schema-less: objectSchema is
    {"type":"object"} (internal/app/controlplane/definitions.go), so the dashboard cannot
    suggest the settings shape either. gate.diff-rules is also the first settings-bearing
    step type in the vocabulary -- every shipped stage refuses settings outright.

Fix: name the step type in the guard's message (steps.go:227), document the step type
and its settings schema under docs/, and consider exposing the registered vocabulary
through the catalog so the dashboard can list and validate step types instead of
accepting free-text YAML.

Also consider (raised in review, kept as-is for now): the step type is the only word in
the vocabulary that is not .. gate.diff-rules is a family
name, not a shipped workflow's stage, and a workflow id gate landing later is refused
loudly at Manager.Register rather than shadowing; renaming it to fit the shipped-stage
convention would falsely claim it belongs to a shipped workflow.

Notes

Widened 2026-10-04 after an operator saved 'type: pooface' and the editor showed a green Valid tick until the server refused it.

Root cause: a step type is only Name + Factory(yaml.Node). It carries no description and no settings schema, and the vocabulary is never served, so the dashboard can only check YAML shape, and calls that Valid.

Plan:

  1. StepType gains Description and a JSON Schema for its settings; each provider fills them in.
  2. The service that owns workflows serves the registered vocabulary (name, description, settings schema, needs-repository) over its proto contract; the UI reads it through archie-ui.
  3. The editor marks unknown types and bad settings inline, and adds steps from a picker of registered types instead of a blank '- type:'. YAML stays as the advanced view.
  4. A new workflow starts from a working agent.run step, not an empty type.

Done when typing an unregistered type is flagged before save and every step on the page shows what it does.
Also in scope: the workflow interface fields (inputs, outputs, repository mode, identity, agent profile) exist only as raw YAML. The editor should show them as fields too.

Close reason

Step vocabulary (names + needs-repository) is served as x-step-types in the workflow-definitions catalog schema; the dashboard editor rejects unknown types and repo-needing steps in repo-less workflows, and lists the step types. steps.go guard was removed with Yaegi; docs/prds was deleted, so no in-tree docs. Settings schemas: archie-core-bn0v.


Imported from beads archie-core-4kbg · GitHub #1146 · type task · priority P1 · created 2026-09-21 · closed 2026-10-04

internal/domain/workflow/diff_rules.go documents gate.diff-rules as "the supported migration target for the deleted .archie/gate.go hook", and nothing an operator can reach says so: - internal/domain/workflow/steps.go:227 still refuses a legacy .archie/gate.go with "migrate its behavior to a registered YAML workflow step" and names no step type. - No runtime surface lists the vocabulary: no control-plane catalog resource, no webui route, no CLI command (manager.StepTypes() is read by tests only), and the dashboard editor seeds the YAML with just `- type: ` (ui/src/workflows/WorkflowDefinitionsCard.vue:43). - Nothing under docs/ mentions the step type at all, including the PRD whose requirement this change exists to satisfy (docs/prds/runtime-control-plane.md, "Workflows", which still states "Their useful behavior must first be available as normal workflow steps" without naming one). - The control-plane resource carrying the rules is schema-less: objectSchema is {"type":"object"} (internal/app/controlplane/definitions.go), so the dashboard cannot suggest the settings shape either. gate.diff-rules is also the first settings-bearing step type in the vocabulary -- every shipped stage refuses settings outright. Fix: name the step type in the guard's message (steps.go:227), document the step type and its settings schema under docs/, and consider exposing the registered vocabulary through the catalog so the dashboard can list and validate step types instead of accepting free-text YAML. Also consider (raised in review, kept as-is for now): the step type is the only word in the vocabulary that is not <workflow-id>.<stage-name>. `gate.diff-rules` is a family name, not a shipped workflow's stage, and a workflow id `gate` landing later is refused loudly at Manager.Register rather than shadowing; renaming it to fit the shipped-stage convention would falsely claim it belongs to a shipped workflow. ### Notes Widened 2026-10-04 after an operator saved 'type: pooface' and the editor showed a green Valid tick until the server refused it. Root cause: a step type is only Name + Factory(yaml.Node). It carries no description and no settings schema, and the vocabulary is never served, so the dashboard can only check YAML shape, and calls that Valid. Plan: 1. StepType gains Description and a JSON Schema for its settings; each provider fills them in. 2. The service that owns workflows serves the registered vocabulary (name, description, settings schema, needs-repository) over its proto contract; the UI reads it through archie-ui. 3. The editor marks unknown types and bad settings inline, and adds steps from a picker of registered types instead of a blank '- type:'. YAML stays as the advanced view. 4. A new workflow starts from a working agent.run step, not an empty type. Done when typing an unregistered type is flagged before save and every step on the page shows what it does. Also in scope: the workflow interface fields (inputs, outputs, repository mode, identity, agent profile) exist only as raw YAML. The editor should show them as fields too. ### Close reason Step vocabulary (names + needs-repository) is served as x-step-types in the workflow-definitions catalog schema; the dashboard editor rejects unknown types and repo-needing steps in repo-less workflows, and lists the step types. steps.go guard was removed with Yaegi; docs/prds was deleted, so no in-tree docs. Settings schemas: archie-core-bn0v. --- _Imported from beads `archie-core-4kbg` · GitHub #1146 · type task · priority P1 · created 2026-09-21 · closed 2026-10-04_
sam added the hightask labels 2026-10-27 13:38:51 +00:00
sam self-assigned this 2026-10-27 13:38:51 +00:00
sam closed this issue 2026-10-27 13:38:51 +00:00
sam added a new dependency 2026-10-27 13:42:23 +00:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Reference: sam/archie#1057