Decide the .archie/stages/*.go equivalent: plugin-supplied step types or a command step type #1692

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

internal/domain/workflow/steps.go:215 (StageRepoStages) hard-errors on the deleted
repository-authored stage hook and tells the operator to migrate the behaviour to a
registered YAML workflow step, but nothing provides one -- the migration half of
archie-core-8szi that has no target. This escalation has to be tracked somewhere: it
was previously recorded only in the lane's commit message.

What the deleted hook actually did (from 924b02a1, which removed it, and its parent
wfeval/yaegi.go): each .archie/stages/*.go was interpreted in-process and had to
export func Stage() workflow.Stage. That is an ARBITRARY stage holding the whole
TaskContext -- it could call tc.Forge, tc.Agent, read tc.Trees and set tc.Outcome --
not a command. The closest YAML-expressible approximation is a step type that runs a
configured argv in the worktree, and that is NOT behaviour-equivalent for a stage that
did more than run a command.

Why it was not landed in the gate.diff-rules lane: a command step type would make the
stored workflow-definitions resource (archie.db, administrative token, editable from
the dashboard) a command-execution surface on the agent host. Today only config.toml's
repo.gate commands and the builder agent's own tools execute commands; nothing stored
in the control plane does. That is a maintainer trust decision (see
ARCHITECTURE.md#plugin-engine-rule-strict invariant 6: a trust boundary is explicit,
not implied).

Options to decide between:
A. Land both gate.diff-rules (already landed) and a command step type, accepting
that stored definitions may execute host commands.
B. Land only gate.diff-rules, and leave .archie/stages/*.go hard-erroring; then fix
steps.go:215's message so it stops promising a migration target that does not exist.
C. Provide a plugin-supplied step type instead: build the Yaegi-plugin -> workflow
StepFactory bridge that internal/infrastructure/workflowsteps documents as
non-existent, so a repository can supply its own stage as interpreted Go again
(which re-opens the in-process interpretation 924b02a1 deleted).

Either way, archie-core-8szi cannot close until this is decided.

Notes

ANSWERED by the maintainer 2026-09-21 (option B): land only the .archie/gate.go equivalent now - that landed as gate.diff-rules (archie-core-8szi) plus a follow-up making it fail closed on an empty diff, merged to main. The .archie/stages/.go equivalent is NOT built: it would make stored, admin-token-writable workflow definitions a command-execution surface on the agent host, changing the trust tier from repository-authored code in the task container, and ARCHITECTURE.md#plugin-engine-rule-strict invariant 6 requires an explicit trust boundary ('a subprocess boundary alone is not a security sandbox'). This bead stays open as the home of that trust decision. Open questions: may stored settings execute argv at all; must it run in a container sandbox rather than as the agent process; does the audited actor bear on what may run; does an advisory/warn level widen it. steps.go:215's repo-stages error is deliberately left untouched rather than made true with a command step.
Decided alongside m7oc (docs/prds/workflow-step-vocabulary.md): the stage half of the deleted .archie/stages/
.go hook gets NO replacement -- interpreted Go stays deleted and no command step is created to approximate it; StageRepoStages' refusal of stages/*.go stands until ndm8 decides command.run. If ndm8 ever allows it, command.run arrives as a provider in the compiled-in set under m7oc's naming and agreement rules, not as a plugin-contribution mechanism. ndm8 remains open.

Close reason

Closed


Imported from beads archie-core-ze7y · GitHub #1048 · type decision · priority P1 · created 2026-09-21 · closed 2026-09-29

internal/domain/workflow/steps.go:215 (StageRepoStages) hard-errors on the deleted repository-authored stage hook and tells the operator to migrate the behaviour to a registered YAML workflow step, but nothing provides one -- the migration half of archie-core-8szi that has no target. This escalation has to be tracked somewhere: it was previously recorded only in the lane's commit message. What the deleted hook actually did (from 924b02a1, which removed it, and its parent wfeval/yaegi.go): each .archie/stages/*.go was interpreted in-process and had to export `func Stage() workflow.Stage`. That is an ARBITRARY stage holding the whole TaskContext -- it could call tc.Forge, tc.Agent, read tc.Trees and set tc.Outcome -- not a command. The closest YAML-expressible approximation is a step type that runs a configured argv in the worktree, and that is NOT behaviour-equivalent for a stage that did more than run a command. Why it was not landed in the gate.diff-rules lane: a command step type would make the stored workflow-definitions resource (archie.db, administrative token, editable from the dashboard) a command-execution surface on the agent host. Today only config.toml's repo.gate commands and the builder agent's own tools execute commands; nothing stored in the control plane does. That is a maintainer trust decision (see ARCHITECTURE.md#plugin-engine-rule-strict invariant 6: a trust boundary is explicit, not implied). Options to decide between: A. Land both `gate.diff-rules` (already landed) and a command step type, accepting that stored definitions may execute host commands. B. Land only `gate.diff-rules`, and leave .archie/stages/*.go hard-erroring; then fix steps.go:215's message so it stops promising a migration target that does not exist. C. Provide a plugin-supplied step type instead: build the Yaegi-plugin -> workflow StepFactory bridge that internal/infrastructure/workflowsteps documents as non-existent, so a repository can supply its own stage as interpreted Go again (which re-opens the in-process interpretation 924b02a1 deleted). Either way, archie-core-8szi cannot close until this is decided. ### Notes ANSWERED by the maintainer 2026-09-21 (option B): land only the .archie/gate.go equivalent now - that landed as gate.diff-rules (archie-core-8szi) plus a follow-up making it fail closed on an empty diff, merged to main. The .archie/stages/*.go equivalent is NOT built: it would make stored, admin-token-writable workflow definitions a command-execution surface on the agent host, changing the trust tier from repository-authored code in the task container, and ARCHITECTURE.md#plugin-engine-rule-strict invariant 6 requires an explicit trust boundary ('a subprocess boundary alone is not a security sandbox'). This bead stays open as the home of that trust decision. Open questions: may stored settings execute argv at all; must it run in a container sandbox rather than as the agent process; does the audited actor bear on what may run; does an advisory/warn level widen it. steps.go:215's repo-stages error is deliberately left untouched rather than made true with a command step. Decided alongside m7oc (docs/prds/workflow-step-vocabulary.md): the stage half of the deleted .archie/stages/*.go hook gets NO replacement -- interpreted Go stays deleted and no command step is created to approximate it; StageRepoStages' refusal of stages/*.go stands until ndm8 decides command.run. If ndm8 ever allows it, command.run arrives as a provider in the compiled-in set under m7oc's naming and agreement rules, not as a plugin-contribution mechanism. ndm8 remains open. ### Close reason Closed --- _Imported from beads `archie-core-ze7y` · GitHub #1048 · type decision · priority P1 · created 2026-09-21 · closed 2026-09-29_
sam added the highdecision labels 2026-10-27 13:41:24 +00:00
sam self-assigned this 2026-10-27 13:41:24 +00:00
sam closed this issue 2026-10-27 13:41:25 +00:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Reference: sam/archie#1692