From 421daae371e24f36d4ee6fa7da5f3744aece6f87 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Thu, 3 Sep 2026 04:19:11 +1000 Subject: [PATCH] docs(architecture): fix stale internal/workflow and internal/nats paths Both packages no longer exist -- internal/workflow moved to internal/domain/workflow at the 2026-08-07 domain migration (7e896c9), confirmed by TaskContext still living there today. internal/nats is gone entirely; verified TaskMessage as a type doesn't exist anywhere in the codebase now, and archie.task.* subjects + TaskEnvelope live in internal/domain/workintake (recorded as a completed migration in migration-decisions.md), with transport in internal/infrastructure/agenttransport/nats. Fixed the two simple path corrections directly. Left the NATS row's deeper question open rather than guessing: whether the row's entire "current meaning" is now superseded by TaskEnvelope (not just its location) needs a closer look this pass didn't have grounds to assert. --- docs/architecture/agent-system.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/architecture/agent-system.md b/docs/architecture/agent-system.md index a4e926171..0ed5118a9 100644 --- a/docs/architecture/agent-system.md +++ b/docs/architecture/agent-system.md @@ -196,7 +196,7 @@ The behaviour is divided across technical packages: strings and persists mutable state and transition history. - `internal/daemon` discovers, claims, schedules, retries, recovers, processes, waits for human input, and reconciles pull requests. -- `internal/workflow` routes work, executes stages, mutates tasks, applies +- `internal/domain/workflow` routes work, executes stages, mutates tasks, applies outcomes, parks failures, and performs forge/worktree operations. - `internal/agentexec` defines and runs individual autonomous-stage protocols. - `internal/taskrun` hands a complete WorkflowExecution to a container worker. @@ -218,10 +218,10 @@ each meaning deliberately; a global text replacement is prohibited. | Persisted `store.Task` row | `internal/store` | WorkflowExecution | Own identity, Workflow ID and version, lifecycle, source-message reference, outputs, attempts, and outcome. Persistence implements the Agent System repository contract. | | Task status and transition history | `store.Status*`, `transitions` | WorkflowExecution lifecycle and domain events | Enforce legal transitions atomically. Domain events and state changes cannot diverge. Remove duplicated status strings from consumers. | | Claimed or queued task | `ClaimNext`, `ClaimByIssue`, `RecoverStale` | Scheduled WorkflowExecution | Claim by WorkflowExecution ID and expected version/state. Crash recovery and leases must not silently create a new execution. | -| `workflow.TaskContext` | `internal/workflow` | WorkflowExecution context | Replace the mutable service bag with execution state plus narrow step-required contracts. Complete application configuration and unrelated services are forbidden. | +| `workflow.TaskContext` | `internal/domain/workflow` | WorkflowExecution context | Replace the mutable service bag with execution state plus narrow step-required contracts. Complete application configuration and unrelated services are forbidden. | | `taskrun.Request` and `taskrun.Response` | `internal/taskrun`; consumed by `internal/app/agentworker`, decoded by `internal/infrastructure/agenttransport/nats` | WorkflowExecution handoff | This is the versioned worker contract for executing a WorkflowExecution. It carries domain-owned execution data, not store rows or global configuration DTOs. | | Per-stage `agentexec.Request.TaskID` | `internal/agentexec` | WorkflowExecutionID correlation | An agent invocation is a bounded WorkflowStep execution. Correlate request/result with WorkflowExecutionID, StepExecutionID, attempt, and protocol version. | -| NATS `TaskMessage` and `archie.task.*` | `internal/nats` | Channel request or WorkflowExecution transport | Discovery messages and execution dispatch are different contracts and subjects. Domain meaning stays outside NATS infrastructure. Identity and source-message idempotency must be explicit. | +| NATS `TaskMessage` and `archie.task.*` | `internal/domain/workintake` (subjects, `TaskEnvelope`); `internal/infrastructure/agenttransport/nats` (transport) -- `internal/nats` no longer exists; whether this row's "current meaning" itself is now superseded by `TaskEnvelope` needs a closer look, not asserted here | Channel request or WorkflowExecution transport | Discovery messages and execution dispatch are different contracts and subjects. Domain meaning stays outside NATS infrastructure. Identity and source-message idempotency must be explicit. | | `taskDispatcher` work item | `internal/daemon` | WorkflowExecution scheduling | Scheduling operates on execution references and declared concurrency policy. Repository serialization is policy, not identity derived from an incomplete task struct. | | `container.TaskPayload` and `task.json` | `internal/container`; read by `internal/infrastructure/agentboot` | WorkflowExecution brief | Rename the boot artifact and schema. It identifies the mounted execution and required workspace only; it is not an alternative execution definition. Missing or malformed input must fail startup before the worker subscribes. | | `storage.TaskRef` | `internal/storage` | WorkflowExecution workspace lease | Storage receives the minimal execution/workspace reference and policy required to provision and release resources. It does not receive the WorkflowExecution aggregate. |