Co-authored-by: Carlos Florencio <carlosmflorencio@gmail.com>
2.9 KiB
status, system, requirements, created, owners
| status | system | requirements | created | owners | ||
|---|---|---|---|---|---|---|
| current | tasks |
|
2026-09-16 |
|
Dependency Gate Skip Visibility System Design
Purpose and boundaries
This design owns the backend log contract for automated launches that the dependency gate deliberately skips. A skipped auto-start is exceptional and operator-visible by definition: a task moved onto an auto-start step and did not launch. The skip is therefore logged at WARN, matching the gate's adjacent lookup-failure path.
Gate semantics, the fail-closed read behavior, and launch-token handling are owned by Task Dependencies and Auto-Start Chains. This design changes only the observability of the genuine blocked verdict; it adds no endpoint, feature flag, database column, or user-facing copy.
Requirement mapping
| Criterion | Design section |
|---|---|
| AC-TASKS-DEPENDENCY-GATE-SKIP-VISIBILITY-001.1 | Blocked-skip log contract |
| AC-TASKS-DEPENDENCY-GATE-SKIP-VISIBILITY-001.2 | Non-blocking paths |
Blocked-skip log contract
dependencyBlocksAutoStart in internal/orchestrator is the single gate
consulted by every automated launch path: step entry
(task.workflow_step_entered), WIP queue promotion (task.queue_promoted),
and automated session launch (session.launch). The caller's event name is
passed in and prefixes the log message, so one log site identifies which path
skipped the launch.
When the gate's read succeeds and reports blocked, the service logs one WARN entry through its structured zap logger:
- Message:
<eventName>: task has unresolved dependencies; skipping auto-start. - Fields:
task_id(string) andblocked_reason(string, the gate's reason such aspendingor the failed-predecessor reason).
A read error keeps the existing separate WARN entry (dependency lookup failed; skipping auto-start, with the error field) and the fail-closed
return; it is not conflated with the genuine-block entry because the blocked
reason differs from a read error. No launch, error surface, or task-state
change accompanies the blocked-skip entry: the task simply stays where it is
until its dependencies resolve.
Non-blocking paths
A task that passes the gate logs nothing at this site. The WARN level is reserved for the exceptional skip so ordinary launches do not train operators to ignore warnings. Debug-level detail for unrelated gate decisions stays at Debug.
Verification
TestDependencyBlocksAutoStartWarnsOnBlockedSkip in
event_handlers_dependencies_test.go drives the gate with a blocked reader,
asserts exactly one WARN entry with the event-prefixed message, and checks the
task_id and blocked_reason fields. This test covers the blocked path.
The unblocked and lookup-error paths are not asserted in this file.