1b305ee36c
Co-authored-by: nova28 <17953305+nova28@users.noreply.github.com> Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com> Co-authored-by: Carlos Florencio <carlosmflorencio@gmail.com>
582 lines
32 KiB
Markdown
582 lines
32 KiB
Markdown
---
|
|
status: draft
|
|
system: plugins
|
|
requirements:
|
|
- REQ-PLUGINS-STEP-MOVE-001
|
|
- REQ-PLUGINS-STEP-MOVE-002
|
|
- REQ-PLUGINS-STEP-MOVE-003
|
|
- REQ-PLUGINS-STEP-MOVE-004
|
|
- REQ-PLUGINS-STEP-MOVE-005
|
|
created: 2026-08-26
|
|
owners:
|
|
- nova28
|
|
---
|
|
|
|
# Plugin-Initiated Workflow Step Transitions System Design
|
|
|
|
## Purpose and boundaries
|
|
|
|
This design carries the technical detail behind
|
|
`docs/specs/plugins/requirements/plugin-initiated-step-transitions.md`: the
|
|
wire contract a third party compiles against, the enforcement seam, the error
|
|
mapping, the two trigger vocabularies, and the code-path facts that constrain
|
|
what the acceptance criteria can promise. The requirements file owns the behavior; this
|
|
file owns how it is expressed and why the alternatives were rejected.
|
|
|
|
Nothing here redefines the task system's move semantics. The move path is
|
|
reused unchanged; the design decisions are about the plugin-facing surface.
|
|
|
|
## Corrections to the originating report
|
|
|
|
**`UpdateTask` is not silent about the transition.** It sets `steptelemetry`
|
|
attribution and calls `recordManualStepTransition`, so the task-level ledger row
|
|
*is* written. What is missing is the `task.moved` event, WIP admission,
|
|
target-step validation, and the queue-vacate pull.
|
|
|
|
**`StepHistoryActor` is never persisted as a value.** It only decides whether an
|
|
authenticated user id is looked up, so the persisted actor of record is
|
|
`task_step_transitions.actor_kind` / `actor_id`.
|
|
|
|
## Prior art
|
|
|
|
|
|
**Our own wiki: unavailable, no substitute consulted.** The configured vault is
|
|
outside this sandbox's readable tree and `obsidian-wiki` / `qmd` are not
|
|
installed, so the semantic pass could not run; the one reachable vault has zero
|
|
Kandev pages. This leg returned nothing useful, and the reason is tooling access
|
|
rather than an empty wiki — a later pass on a machine with vault access may find
|
|
prior reasoning this spec did not see.
|
|
|
|
**What other products shipped (`saas-kb`, `category: ai_sdlc`).** One hit was on
|
|
point: Factory.ai's audit model splits attribution into **Actor** ("the user or
|
|
service principal who initiated the action") and **Source** ("the surface that
|
|
originated the event") (`Factory.ai/Guides/enterprise_audit-log.md`) — the same
|
|
shape as `actor_kind`/`actor_id` plus `trigger`, confirming a service principal
|
|
is a first-class actor rather than a stand-in for the human who configured it.
|
|
Everything else scored ~0.009 and is noise.
|
|
|
|
**What we are doing differently.** Factory.ai reports a `null` actor for
|
|
system-initiated events. We do not: that would lose *which* plugin moved the
|
|
card, the only question an operator will ask.
|
|
|
|
## Why the actor is `integration`, identified by `plugin:<id>`
|
|
|
|
The originating report offered a new `plugin` actor kind, or the authenticated
|
|
user driving the plugin surface. Neither is right.
|
|
|
|
**The authenticated user is not implementable and not honest.** `hostForPlugin`
|
|
(`internal/plugins/service.go:612`) binds a host to `pluginID` and capabilities
|
|
only. There is no `authn` identity on a plugin gRPC context — that seam exists
|
|
only in the HTTP handlers (`authn.FromGin`). A plugin's Go backend can act on a
|
|
webhook, a timer, or its own logic with no human anywhere, so "the user driving
|
|
the surface" frequently does not exist. The frontend Host API
|
|
(`apps/web/lib/plugins/host-api.ts`) contributes UI components and exposes no
|
|
task-write path, so it supplies no authenticated alternative.
|
|
|
|
**A new `plugin` actor kind invents a value we already have.**
|
|
`steptelemetry.ActorKind` includes `ActorIntegration`
|
|
(`internal/steptelemetry/steptelemetry.go:51`) with a production writer for
|
|
exactly this shape of caller: registered external automation with a stable id
|
|
(`watcher_dispatch.go:378` sets `ActorID: src.WatchID(evt)`, under
|
|
`ActorKind: ActorIntegration` on 377, for Jira and Linear creates). A plugin is that.
|
|
|
|
**`ActorID = "plugin:<id>"` reuses one provenance string.** The same value is
|
|
already produced by `pluginHost.pluginSource()` and already appears in
|
|
`metadata.source` on plugin-created tasks and plugin-sent messages, so the
|
|
ledger joins to those rows without a second vocabulary.
|
|
|
|
**`MoveTaskOptions.StepHistoryActor` must not be `Human`.** It is a control
|
|
flag, not a stored value: `recordManualStepTransition`
|
|
(`service_workflow.go:1199`) uses it only to decide whether to look up an
|
|
authenticated user id, and `CreateStepTransition` takes no actor-kind argument.
|
|
`Human` is what causes the operator's user id to be stamped on the row, and an
|
|
unattended automated move must not inherit it — the same reasoning the field's
|
|
own doc comment gives for agent moves. Because the value itself is never
|
|
persisted, `Agent`, `System` and the zero value are observationally identical
|
|
here; the requirement is only that it is not `Human`.
|
|
|
|
## Why `api_write:tasks` and not a new capability
|
|
|
|
A plugin holding `api_write:tasks` can already create tasks and start agents, so
|
|
a move-specific capability closes no door that is open today. It can also set
|
|
`workflow_step_id` through `UpdateTask` right now — that is the defect — so
|
|
gating the *fixed* path behind a new capability would make the correct path
|
|
harder to reach than the broken one, and every existing plugin would keep the
|
|
broken behavior until it re-declared.
|
|
|
|
The `PluginOwnedTaskTree` ownership rule that guards plugin-owned task deletion
|
|
is deliberately not applied here. Moving a task is not destructive, and
|
|
restricting moves to plugin-created tasks would defeat the purpose: a dispatch
|
|
plugin exists precisely to move work it did not create. Safety comes from the
|
|
auto-start gates the move runs through, not from ownership.
|
|
|
|
## The two trigger vocabularies
|
|
|
|
The "why" column is already caller-specific, but the two persisted surfaces
|
|
have **separate, non-overlapping** vocabularies. A plugin move writes to both,
|
|
so `plugin_move` must be added to both.
|
|
|
|
| | Task-level ledger | Session-level history |
|
|
|---|---|---|
|
|
| Table | `task_step_transitions` | `session_step_history` |
|
|
| Enum | `steptelemetry.Trigger` (`steptelemetry.go:28-42`) | `wfmodels.StepTransitionTrigger` (`workflow/models/models.go:310-325`) |
|
|
| Written by | `steptelemetry.FromContext`, in-transaction (`step_transitions.go:88`) | `recordManualStepTransition` → `CreateStepTransition` |
|
|
| Declares | `task_created`, `manual_move`, `task_update`, `mcp_move`, `mcp_deferred_move`, `engine_transition`, `user_cancellation`, `wip_pull`, `bulk_move`, `unarchive_restore`, `workflow_attached`, `workflow_detached`, `unknown` | `manual`, `auto_complete`, `approval`, `on_turn_start`, `on_children_completed`, `task_update`, `queue_promotion` |
|
|
| Notably lacks | `queue_promotion` | `mcp_move`, `wip_pull` |
|
|
|
|
**The session-level row is conditional, and usually absent.**
|
|
`recordManualStepTransition` returns early when the task has no session; its
|
|
comment gives the reason: `session_step_history.session_id` is a NOT NULL FK to
|
|
`task_sessions`, so a session-less move cannot be recorded without a schema
|
|
change. This feature's most common case — a plugin moving a card onto a step
|
|
whose `on_enter` starts an agent — is by definition a task with no session yet,
|
|
because the move is what creates it. So a plugin move writes the task-level
|
|
ledger row always and the session-level row only when a session already exists,
|
|
and `plugin_move` in `wfmodels.StepTransitionTrigger` is exercised only by the
|
|
latter. AC-003.5 states this; adding the value is still required, because the
|
|
moment a task has a session the fallback below applies.
|
|
|
|
Adding `plugin_move` to only the first is the failure mode this design exists to
|
|
prevent. `recordManualStepTransition` defaults an empty trigger to
|
|
`StepTransitionTriggerManual`, so a plugin move would persist
|
|
`session_step_history.trigger = "manual"` — the value reserved for human board
|
|
moves — under a requirement whose entire point is that a plugin move is not a
|
|
person's action.
|
|
|
|
`steptelemetry.ContractVersion`'s doc states it is bumped "only for a change to
|
|
what a row means, **not** for adding a new Trigger/ActorKind value", so
|
|
`plugin_move` costs no contract bump and no telemetry re-activation. Neither
|
|
`trigger` column carries a CHECK constraint, so neither addition needs a
|
|
migration.
|
|
|
|
## The wire contract
|
|
|
|
This is externally consumed: third-party plugin authors compile against it
|
|
through `pkg/pluginsdk` and the generated clients. It is specified here rather
|
|
than invented during build, because a correction after release is a *second*
|
|
breaking change on top of the `UpdateTask` one.
|
|
|
|
Added to the existing `Host` service in
|
|
`apps/backend/proto/kandev/plugin/v1/plugin.proto`, beside `CreateTask` and
|
|
`UpdateTask`:
|
|
|
|
```proto
|
|
rpc MoveTask(MoveTaskRequest) returns (MoveTaskResponse);
|
|
|
|
message MoveTaskRequest {
|
|
string task_id = 1;
|
|
string workflow_step_id = 2;
|
|
optional string workflow_id = 3;
|
|
int32 position = 4;
|
|
}
|
|
|
|
message MoveTaskResponse {
|
|
Task task = 1;
|
|
bool transitioned = 2;
|
|
optional string queued_for_step_id = 3;
|
|
string from_step_id = 4;
|
|
}
|
|
```
|
|
|
|
- **`task_id`, not `id`.** `GetTaskRequest` uses a bare `id`, but this message
|
|
carries three identifiers; `DeletePluginOwnedTaskTreeRequest` sets the
|
|
precedent for qualifying (`root_task_id`) when a bare `id` would be
|
|
ambiguous.
|
|
- **`workflow_step_id` is a bare `string`, required.** There is no move with no
|
|
destination, so omitted and empty are the same error and presence adds
|
|
nothing.
|
|
- **`workflow_id` is `optional`; `position` is a bare `int32`.** proto3 cannot
|
|
distinguish an omitted bare `string` from `""`, and `workflow_id` has a
|
|
meaningful absent case — inherit the task's current workflow — that is
|
|
genuinely distinct from a present empty value, which AC-005.5 rejects. So it
|
|
carries presence. `position` does **not**: AC-005.4 defines an omitted
|
|
position and a position of zero as the same request, both placing the task at
|
|
the top of the target step, so presence would encode a distinction with no
|
|
behavioral consequence and invite an implementer to invent one. An earlier
|
|
draft made `position` `optional` on the reasoning that "no position stated"
|
|
was distinct from zero; it is not, because Out of scope keeps position
|
|
semantics to pass-through and AC-002.3 applies a position change even on a
|
|
same-step move — so a load-bearing absent case would have silently changed
|
|
where a step-only move lands. `int32` matches `plugin.proto:378` and `:445`.
|
|
- **Exactly one admission discriminator: the presence of
|
|
`queued_for_step_id`.** There is deliberately no `bool admitted` beside it,
|
|
because two fields encoding one fact can disagree and a builder would have to
|
|
decide which wins. Read as: `transitioned = false` → the task was
|
|
already on the target step; `transitioned = true` with `queued_for_step_id`
|
|
absent → admitted; `transitioned = true` with `queued_for_step_id` present →
|
|
queued for that step, holding no slot. `queued_for_step_id` is reported on
|
|
**both** values of `transitioned`, never suppressed by a no-transition answer:
|
|
per Terminology a queued task *is* on its target step, so a repeat against a
|
|
full step is a same-step move whose honest answer is "no transition, still
|
|
queued here". Suppressing it would make the retry AC-005.1 describes
|
|
indistinguishable from a successful admission.
|
|
- **`from_step_id`** is the step the task left, empty when `transitioned` is
|
|
false, so a plugin can render the transition without a second read.
|
|
- **Both outcome fields come from the write transaction, not from a pre-read.**
|
|
`MoveTaskResult` (`service_workflow.go:388-391`) carries only `Task` and
|
|
`WorkflowStep` today, so this feature adds `FromStepID string` and
|
|
`Transitioned bool` to it. **Neither is populated from the `oldStepID` and
|
|
`stepChanged` values `MoveTaskWithOptions` computes near `:493`.** Those come
|
|
from the earlier unlocked `GetTask`, and the ledger row is not written from
|
|
them: `updateTaskTx` and every sibling step-writer
|
|
(`UpdateTaskIfWorkflowStepHasCapacity`, the admission-gated path, …)
|
|
independently re-derive the from-step through `readTaskStepInTx` — a
|
|
`FOR UPDATE` read taken *inside* the transaction, after the workspace row
|
|
lock — and pass that to `recordStepTransition`. Under the concurrency
|
|
AC-005.10 pins, the two reads can name different steps, so a response built
|
|
on the earlier one would contradict its own ledger row. *(Round-4
|
|
correction: round 3 specified the `:493` variables here. AC-002.6 itself was
|
|
right and is unchanged; only this mechanism was wrong.)*
|
|
- **`Transitioned` is `WorkflowStepTransitionID != 0`.** That field already
|
|
exists on `models.Task`, is assigned from `recordStepTransition`'s return on
|
|
every write path, and reaches the event payload as `step_transition_id`.
|
|
`recordStepTransition` returns `0` and writes no row when the from-step
|
|
equals the to-step, so zero *is* "no transition".
|
|
Deriving it from `stepChanged` instead would let a stale snapshot report
|
|
`transitioned = true` with no ledger row behind it, breaking AC-003.1.
|
|
- **`FromStepID` has no carrier yet, so it gets the same one.** The from-step
|
|
the ledger row was written from is carried up beside the transition id: one
|
|
more transient `json:"-"` field on `models.Task`, assigned at the same
|
|
statement, from the same variable. That is the existing
|
|
`WorkflowStepTransitionID` pattern applied to the other half of the same row,
|
|
not a new mechanism. Adding reported fields changes no move semantics, so
|
|
this stays inside Out of scope's boundary. A plugin-seam pre-read is still
|
|
rejected: its own snapshot can disagree with the ledger too. Taking both
|
|
fields from the row the transaction wrote makes AC-002.6's agreement
|
|
structural rather than something a builder must maintain.
|
|
- **No enum is introduced.** `plugin.proto` declares none today, and a
|
|
three-value outcome enum would be the only one in the file; the
|
|
presence-based reading carries the same information in the file's existing
|
|
style.
|
|
- **The response carries the full `Task`**, so no follow-up `GetTask` is
|
|
needed. Its admission fields are whatever the read shape offers at the time;
|
|
because the outcome is readable from `transitioned` / `queued_for_step_id`
|
|
alone, this feature does not depend on PR #3044 landing.
|
|
|
|
### Why not route `UpdateTask` internally to the move path
|
|
|
|
`UpdateTaskRequest` has no `workflow_id` or `position` field, so cross-workflow
|
|
moves would stay unrepresentable and position would silently default to the top
|
|
of the step. A partial failure across two service methods with no shared
|
|
transaction has no defined outcome. And a dedicated RPC lets the response report
|
|
admission, which `UpdateTaskResponse` cannot.
|
|
|
|
## Where `UpdateTask`'s rejection is enforced
|
|
|
|
The rejection lives on the plugin-facing update path, **not** in the shared task
|
|
service. `taskservice.UpdateTask` keeps accepting `WorkflowStepID` unchanged:
|
|
its own comment describes it as "a mutation boundary used by plugins and MCP"
|
|
(`service_tasks.go:1643`), so rejecting there would break the MCP use that
|
|
comment anticipates and would exceed this feature's plugin-only scope.
|
|
|
|
The seam is the plugins package's own task-update entry and the adapter behind
|
|
it — `internal/plugins/host_write.go:203`, which builds `TaskUpdateInput`, and
|
|
`pluginsTaskWriterAdapter.UpdateTask` (`internal/backendapp/services.go:1281`),
|
|
which is constructed exactly once (`services.go:233`) and wired only into
|
|
`pluginsSvc.SetDataSources`, so nothing but the plugin path reaches it.
|
|
|
|
That adapter already sets the precedent: it validates `state` there and returns
|
|
`codes.InvalidArgument`, with a comment saying it does so because "the REST/MCP
|
|
path validates state at its HTTP handler". Plugin-only input validation already
|
|
belongs at this layer; `workflow_step_id` joins `state`.
|
|
|
|
The field stays declared in the proto and starts returning an error, rather than
|
|
being removed, so a plugin compiled against the current proto gets a named
|
|
rejection instead of wire-level unknown-field silence.
|
|
|
|
**"Carries" means present, not non-empty.** `UpdateTaskRequest.workflow_step_id`
|
|
is `optional string` (`plugin.proto:774`), so presence and emptiness are
|
|
distinguishable on the wire, and AC-004.3 rejects on *presence* — an explicitly
|
|
present `""` is rejected exactly like a present step id. The reasoning is
|
|
AC-005.5's, inverted: a present empty value states an intent, and here the
|
|
intent it states is "update the step", which is the operation this path no
|
|
longer serves. Treating present-empty as absent would leave a silently accepted
|
|
no-op on the one path the feature exists to close.
|
|
|
|
**It is checked before the request's other field validations.** The adapter
|
|
already validates `state` and returns `InvalidArgument`; AC-004.3 requires the
|
|
error to *name the move operation*, which it cannot do if a co-submitted invalid
|
|
`state` answers first. Ordering the step check first makes the guidance
|
|
deterministic for a request that is wrong in two ways at once, and matches
|
|
AC-004.3's "change no persisted field including the other fields in the same
|
|
request".
|
|
|
|
## Why the session gate wins over retry idempotency
|
|
|
|
AC-001.8 rejects a move against a task holding any starting or running session.
|
|
AC-005.1 promises an identical repeat succeeds as a same-step move. **Spec
|
|
Review round 3 found these collide on this feature's own headline path**, and
|
|
this section records the decision: **AC-001.8 wins, and AC-005.1 is narrowed to
|
|
the window where no session is active.**
|
|
|
|
The collision is structural, not a wording accident.
|
|
`MoveTaskWithOptions` calls `validateTaskMove` at `service_workflow.go:486`;
|
|
`stepChanged := oldStepID != workflowStepID` is not computed until `:494`. The
|
|
session gate therefore runs *before* the same-step determination exists and
|
|
cannot consult it. `validateMoveSessions` (`:1155-1169`) then rejects on **any**
|
|
session in `Starting`/`Running` unless `AllowActivePrimarySession` is set — the
|
|
option the board's handlers pass and the agent-initiated path does not, and
|
|
which AC-001.8 declines by choosing the agent shape.
|
|
|
|
It bites on the common case, not an edge: AC-003.5 records that a move onto an
|
|
auto-start step *precedes* the session it creates, so the first successful move
|
|
produces a live session within moments. A webhook redelivery — exactly what
|
|
REQ-005's Intent names — arrives inside that window.
|
|
|
|
**Why AC-001.8 is the one that survives.** Narrowing it instead would need a
|
|
same-step carve-out either inside `MoveTaskWithOptions`, which changes move
|
|
semantics for every existing caller and is out of scope, or in front of it in
|
|
the plugin seam, which AC-001.1 forbids and which races anyway: the task's step
|
|
can change between the seam's check and the shared path's read. Narrowing
|
|
AC-005.1 needs no shared-path change at all and leaves AC-001.8 a truthful
|
|
`(pin)`.
|
|
|
|
**What the rejection tells a plugin, and why it is a usable answer.** A
|
|
`FailedPrecondition` here is not a bare failure — it is the signal that this
|
|
task already has a live session, which for a redelivery is precisely the
|
|
information the caller wanted: the first delivery landed and the agent is
|
|
running, so do not retry. A re-read to "same step, live session" cannot prove
|
|
this move caused it — a pre-existing session looks identical, so certainty
|
|
needs the plugin's own delivery state. The cost is that a plugin cannot treat
|
|
move-and-forget as unconditionally idempotent; it must handle this code. That
|
|
cost is stated here and in AC-005.1 rather than discovered at build time.
|
|
|
|
The narrower promise still holds where it matters: a redelivery arriving after
|
|
the agent finished, or against a step with no `auto_start_agent`, finds no live
|
|
session and gets AC-005.1's clean no-op.
|
|
|
|
## Error mapping
|
|
|
|
Third parties branch on these codes, so they are fixed here rather than left to
|
|
the handler. AC-004.6 makes the table binding.
|
|
|
|
| Case | AC | Code |
|
|
|---|---|---|
|
|
| Target step unknown, not in the named workflow, or in another workspace | 001.6 | `InvalidArgument` |
|
|
| Task is archived | 001.7 | `FailedPrecondition` |
|
|
| Task has a starting or running session | 001.8 | `FailedPrecondition` |
|
|
| Plugin lacks `api_write:tasks` | 004.1 | `PermissionDenied` |
|
|
| `UpdateTask` carries `workflow_step_id` | 004.3 | `InvalidArgument` |
|
|
| Empty `task_id` or `workflow_step_id`; present-but-empty `workflow_id` | 005.5 | `InvalidArgument` |
|
|
| Task id names no task | 005.6 | `NotFound` |
|
|
| Named `workflow_id` is well-formed but no such workflow exists | 001.6 | `InvalidArgument` |
|
|
| Task on no workflow and none named | 005.11 | `InvalidArgument` |
|
|
| Negative `position` | 005.4 | `InvalidArgument` |
|
|
| Target step at its WIP limit | 002.1 | **not an error** — success reporting queued |
|
|
|
|
**`NotFound` is reserved for the addressed resource.** The task is what the RPC
|
|
addresses, so naming no task answers `NotFound`; every other identifier in the
|
|
request — the target step, and the workflow qualifying it — describes the
|
|
*destination* and is request content, so naming nothing answers
|
|
`InvalidArgument`. That rule is what places the unknown-workflow row above, and
|
|
it is stated because the table is binding under AC-004.6 and a builder must be
|
|
able to place a case the table does not enumerate verbatim.
|
|
|
|
**When one request trips two rows, the first check in this ladder wins.** The
|
|
table lists cases, not order; this orders them: capability (004.1) → request
|
|
shape, including `UpdateTask`'s rejected `workflow_step_id` and a negative
|
|
position (004.3, 005.5, 005.4) → the task load (005.6) → the task's own state
|
|
(001.7, 001.8) → the destination, which can only be checked once the task has
|
|
supplied the workflow it is qualified against (001.6, 005.11) → WIP admission,
|
|
which is not an error at all. So a request naming both a task that does not
|
|
exist and an unknown target step answers `NotFound`, and one from a plugin
|
|
lacking the capability answers `PermissionDenied` whichever else is wrong —
|
|
which also stops a non-writer probing which task ids exist, the reasoning Reach
|
|
applies to a future per-workspace scope. Stated because AC-004.6 gives every row
|
|
its own test, so two implementations checking in different orders return
|
|
different codes for the same request.
|
|
|
|
`InvalidArgument` versus `FailedPrecondition` splits on whether the *request* is
|
|
malformed or the *task's state* forbids an otherwise well-formed request. An
|
|
archived or busy task is the latter: the caller sent nothing wrong and retrying
|
|
the identical request can succeed once the state changes.
|
|
|
|
**The existing classifier must not be reused.** `classifyMoveTaskError`
|
|
(`internal/mcp/handlers/config_task_handlers.go:243`) is the only precedent for
|
|
turning these errors into caller-facing codes, and it buckets *four* of the
|
|
cases above — archived, active session, different workspace, and step not
|
|
belonging to the target workflow — into a single `Conflict` by lowercase
|
|
substring matching. Two of those are cases AC-001.6 requires to answer
|
|
`InvalidArgument`, so adopting it would violate the requirement it appears to
|
|
serve. The plugin path maps its own codes at the plugin-facing seam, beside the
|
|
`state` validation already there.
|
|
|
|
The shared validators (`validateTaskMove`, `validateMoveSessions`) stay
|
|
untouched: they return bare `fmt.Errorf` strings today, every other caller
|
|
depends on that, and adding typed sentinels would be a change to shared move
|
|
semantics this feature puts out of scope. The seam therefore recognises those
|
|
errors to classify them. That is a real coupling to message text, and it is the
|
|
lesser cost — the alternative changes a shared path for every existing caller.
|
|
It is contained by keeping the mapping in one function with a test per row of
|
|
the table above, so a reworded validator error fails a test rather than silently
|
|
degrading a plugin's error handling to `Unknown`.
|
|
|
|
## Reading the `(pin)` and `(new)` labels
|
|
|
|
REQ-005's criteria carry one of two labels. A **`(pin)`** records behavior the
|
|
system already has, so that routing plugin moves through the shared path cannot
|
|
silently change it: it is discharged by a test that the behavior still holds,
|
|
needs no new implementation, and a failure is a shared-path regression rather
|
|
than work to build here. A **`(new)`** is construction this feature owes.
|
|
|
|
## Code-path facts that constrain the criteria
|
|
|
|
### The defect's call sites, in full
|
|
|
|
`publishTaskMovedEvent` (`service_events.go:719`) has exactly three call sites,
|
|
all in `service_workflow.go` — `579`, `882`, `900` — inside `MoveTaskWithOptions`
|
|
and the queue-promotion paths. None is reachable from `taskservice.UpdateTask`,
|
|
which is why a plugin-set `workflow_step_id` relocates a card and dispatches
|
|
nothing.
|
|
|
|
### The post-commit failure window is real and is not narrowed here
|
|
|
|
`MoveTaskWithOptions` commits the step change and its in-transaction ledger row
|
|
through `updateMovedTask`, and only then publishes `task.moved`, records session
|
|
history, runs `pullNextTaskOnVacate` and `pullTasksFromNewFeederWork`, and
|
|
finally re-reads the task — returning an error if that re-read fails
|
|
(`"failed to refresh task after feeder pull"`). A move can therefore return an
|
|
error with the row already written and the agent already dispatched.
|
|
|
|
This is why the requirements scope "no ledger row" to failures *before* the
|
|
commit, and pin the post-commit behavior as-is. The consequence for a plugin
|
|
author — a move error does not mean nothing happened, so re-read the task rather
|
|
than assume the move was rolled back — belongs in the plugin authoring guide
|
|
rather than in an acceptance criterion, since no test of this system can
|
|
discharge it. Narrowing the window would
|
|
change move semantics for every existing caller, which is out of scope.
|
|
|
|
### Admitted-versus-queued must be read from `QueuedForStepID`
|
|
|
|
In `updateTaskWithWorkflowStepAdmission` (`repository/sqlite/task.go`):
|
|
|
|
```go
|
|
admitted = task.IsEphemeral || limit <= 0 || occupants < limit
|
|
// on the admitted branch:
|
|
task.WIPAdmitted = !task.IsEphemeral
|
|
task.QueuedForStepID = ""
|
|
```
|
|
|
|
`WIPAdmitted` and `QueuedForStepID` are not complements. An ephemeral task is
|
|
admitted by the function's own return value while persisting
|
|
`WIPAdmitted = false` **and** `QueuedForStepID = ""`. Reading `WIPAdmitted`
|
|
alone would report that task as queued when it is queued for nothing.
|
|
|
|
The discriminator is therefore `QueuedForStepID`: queued if and only if it is
|
|
non-empty, admitted otherwise. This makes the ephemeral case report correctly
|
|
instead of becoming a third outcome. It is defensive rather than reachable
|
|
today — task creation rejects an ephemeral task that names a workflow
|
|
(`service_tasks.go:594`), so an ephemeral task is not expected to be on a board
|
|
— but the branch exists in the writer and an implementer reading it would
|
|
otherwise infer a third reportable state.
|
|
|
|
### Rejections are checked before the write, not atomically with it
|
|
|
|
`MoveTaskWithOptions` runs `validateTaskMove` (`:486`) — archived task, target
|
|
step, workspace, and sessions — before it computes any change and before the
|
|
admission write. AC-001.9 states the consequence plainly: "change no persisted
|
|
field" in AC-001.6 through AC-001.8 binds *the rejected move*, which writes
|
|
nothing on the rejecting path, and is not a claim that the task is unchanged
|
|
when the caller observes the error. A concurrent writer committing between the
|
|
check and the write is AC-005.10's territory, and this path serializes on the
|
|
workspace row lock rather than re-validating under it.
|
|
|
|
This is the same shape as the post-commit window above: both are properties of
|
|
the shared path that this feature pins rather than narrows, because narrowing
|
|
either means changing move semantics for every existing caller.
|
|
|
|
### Promotion ordering is by position and priority first
|
|
|
|
AC-005.2 pins the order queued tasks are promoted in. The promotion path is
|
|
`pullNextTaskOnVacate` → `promoteNextQueuedTask` → `nextQueuedCandidate` →
|
|
`NextQueuedTaskForStepExcluding` (`repository/sqlite/task.go:1538`) or
|
|
`NextPullCandidateExcluding` (`:1491`).
|
|
|
|
**AC-005.2's order is the one in `NextQueuedTaskForStepExcluding`**, quoted in
|
|
full because the pin test is written from it:
|
|
|
|
```sql
|
|
ORDER BY t.position ASC,
|
|
CASE LOWER(COALESCE(t.priority, ''))
|
|
WHEN 'critical' THEN 0
|
|
WHEN 'high' THEN 1
|
|
WHEN 'medium' THEN 2
|
|
WHEN 'low' THEN 3
|
|
WHEN 'none' THEN 4
|
|
ELSE 4
|
|
END ASC,
|
|
COALESCE(t.queued_at, t.created_at) ASC,
|
|
t.created_at ASC,
|
|
t.id ASC
|
|
```
|
|
|
|
That `CASE` is the "priority tier" AC-005.2 names: five declared values, with
|
|
any unrecognised or absent priority folded onto the same rank as `none`. A pin
|
|
test must therefore not assume unknown priorities sort last on their own — they
|
|
tie with `none` and are separated by the keys below.
|
|
|
|
**The two queries do not share this order, and the sibling is not on the
|
|
production path.** `NextPullCandidateExcluding` has **four** keys — position,
|
|
the same priority `CASE`, `created_at`, `id` — and **no `queued_at` tier at
|
|
all**. `nextFeederQueuedCandidate` (`service_workflow.go:1006-1026`) prefers
|
|
`NextQueuedTaskForStepExcluding` whenever the repository satisfies that
|
|
narrower interface, which the real sqlite `*Repository` always does, so
|
|
`NextPullCandidateExcluding` is reached only by test doubles. Pinning AC-005.2
|
|
against it would produce a red test that looks like a shared-path regression and
|
|
is not one.
|
|
|
|
Position and priority tier are the primary and secondary keys; queued-at is only
|
|
the third. An earlier draft of AC-005.2 named queued-at as the primary key,
|
|
having read the `ORDER BY` of `ListQueuedTasks` (`:1705`) — a general listing
|
|
helper that is not on the promotion path at all. A pin test written from that
|
|
wording fails against any data with mixed positions or priorities, and the
|
|
`(pin)` convention would then have pointed the implementer at a shared-path
|
|
regression that does not exist.
|
|
|
|
### The plugin path does not rebase onto a concurrent writer's state
|
|
|
|
AC-005.10 pins concurrent-move behavior, and what it can pin is bounded by which
|
|
admission writer this path uses. `updateTaskWithWorkflowStepAdmission` runs
|
|
`rebaseTaskForStepAdmissionCAS` only when `expectedStepID != ""`, and the sole
|
|
caller passing a non-empty expected step is the workflow engine's guarded
|
|
re-evaluation (`orchestrator/workflow_store.go:429`). `MoveTaskWithOptions`
|
|
reaches the writer with no expected step and captures `oldStepID` from a read
|
|
taken before the transaction.
|
|
|
|
That is deliberate. The writer's own comment: "The unconditional
|
|
(`expectedStepID == ""`) callers — manual/bulk/feeder moves — must NOT call
|
|
this: their caller-built `task` already carries this operation's own field
|
|
changes (Position, move-lifecycle metadata, …) that have no other source of
|
|
truth, so rebasing from a fresh row would drop them instead of protecting them."
|
|
|
|
So the plugin path serializes on the workspace row lock, commits in arrival
|
|
order, and writes the caller's snapshot: the *destination* and caller-built
|
|
fields are the ones this caller asked for, not a rebase onto what the earlier
|
|
writer committed. The recorded *from*-step is a separate read — `readTaskStepInTx`,
|
|
inside the write transaction under its row lock — so the ledger chain stays
|
|
contiguous even where the caller's snapshot had gone stale. AC-005.10 states that
|
|
split rather than promising a rebase, because promising one would mean changing
|
|
shared move semantics for every existing caller — out of scope, and the reason the
|
|
CAS variant exists as a separate entry point in the first place.
|
|
|
|
## Reach
|
|
|
|
AC-005.6 answers `NotFound` for a task id that names no task, and deliberately
|
|
says nothing more restrictive. Should a future contract introduce per-workspace
|
|
plugin scoping — listed under Out of scope — a task outside a plugin's scope
|
|
should also answer `NotFound` rather than a permission error, so that scoping
|
|
cannot be used to probe which task ids exist. That is recorded as the intended
|
|
direction, not as a criterion this feature discharges.
|
|
|
|
A plugin holding `api_write:tasks` may move any task in the install, in any
|
|
workspace. There is no narrower scope available to enforce: `hostForPlugin`
|
|
binds no workspace, and `authorizeTaskID` (`service_access.go:59`) returns `nil`
|
|
immediately when `callerScope(ctx)` reports the caller unscoped, which is every
|
|
plugin gRPC context. A plugin is an install-level extension the operator chose
|
|
to install — the same trust level at which it can already create tasks and start
|
|
agents.
|
|
|
|
Per-workspace plugin scoping is a separate contract. If it is ever added, this
|
|
reach narrows with it and no acceptance criterion changes, because the criteria
|
|
state the not-found convention rather than a workspace filter.
|