Files
archie/docs/architecture/agent-system.md
T
sam 7244f9ea1f feat(memory): four-scope contract and builtin engine CRUD (unification slice 2) (#886)
* feat(memory): four-scope contract with CRUD and revisions

Seam for memory unification slice 2 (docs/prds/memory-engine-unification.md
§1, §2, §7): internal/domain/memory is now a scope-addressed CRUD contract.

- Scope{Kind,Agent,User} with the four ratified kinds, Validate rejecting a
  component present where it is not required, and a length-prefixed Key so
  opaque channel-native ids cannot collide.
- Subject{AgentID,UserID} with Scopes()/WritableScopes(): global is never
  writable, and an absent user id removes every scope requiring one.
- Store becomes Create/Get/Query/List/Update/Forget/Revisions over
  NewRecord/RecordUpdate/Record/Revision, with ErrNotFound/ErrStaleRevision.
  Observation, Identity and Metadata are deleted.
- The content scanner moves into the family (internal/domain/memory) so every
  engine applies it in Create and Update; internal/memory re-exports the types
  until slice 5 deletes it.
- The markdown store moves to internal/infrastructure/memory/builtin, its
  correct home per organisation.md.

WIP: internal/infrastructure/memory and internal/infrastructure/sessioncurator
are converted in the lanes that follow this commit.

* feat(memory): builtin engine CRUD, retained revisions and the curator's agent-user write

Slice 2 implementation (docs/prds/memory-engine-unification.md §1, §2, §6,
§7), on top of the contract seam in the previous commit.

- internal/infrastructure/memory: per-scope markdown heads with a JSON
  provenance marker, per-scope HISTORY.md retaining superseded and deleted
  states, Update superseding before replacing the live block, ErrStaleRevision
  via RecordUpdate.Expected, idempotent Forget, and the family scanner applied
  in Create and Update. Scope directories are hex(sha256(Scope.Key())).
- internal/infrastructure/sessioncurator: the participant is derived from the
  session's user-role senders; exactly one writes agent-user scope, zero or
  several write nothing and return ActionSkipped naming the count.
- docs/architecture: the settled decision recorded in migration-decisions §5
  (superseding the 2026-09-02 marker entry) and agent-system.md pointing at it.

Draft: to be squashed and reviewed before publication.

* test(curator): conform the registry's fake memory engine to the CRUD contract

The fake still implemented the pre-CRUD Store surface (Write taking an
Observation, List/Forget keyed by a bare string), so the package's test
binary no longer compiles: fakeMemoryEngine is missing Create, Get, Update
and Revisions, and domainmemory.Observation no longer exists. That took
`go fix ./...`, `go vet ./...` and `go test ./...` down with it, which is
what `task check` runs first.

Missed by the same commit that updated internal/infrastructure/sessioncurator's
own fake to the new interface. Repaired on the fake, not by loosening the
interface: the fake is the only thing out of date.

* fix(sessioncurator): refuse to attribute a session with unidentified user messages

sessionParticipant skipped user-role messages with an empty SenderID and
counted only the identified ones, so a session holding one identified sender
plus any number of unidentified user messages yielded that sender as the
single participant. Those messages are still part of the excerpt the
extraction model reads, so facts derived from content of unknown provenance
were written into the identified sender's agent-user scope: user A's memory
can end up crediting content that may belong to someone else. It is exactly
the case the function's own doc comment claims to handle, which it only
caught when no message at all was identified.

An unidentified user message now makes the session unattributable outright,
beside any number of identified senders, and the skip action's reason names
the count instead of reporting a sender count that no longer explains the
skip. Assistant-role messages are unaffected: they carry the bot, so they
still cannot manufacture a participant.

Fixed in sessionParticipant rather than at the write, because it is the
single producer of the attribution decision: it now returns the participant
or the reason there is none, so the caller cannot print a reason that
disagrees with what it decided. The fail-closed path (nothing written, one
ActionSkipped) and the extraction flow are unchanged.

* fix(memory): carry record content through the block format intact

builtin.Store's format ends a block at a blank line and starts a section at a
"## " line, but storeContent only trimmed the content and rejected an empty
one. Content holding either delimiter was accepted, written, and answered back
to the caller in full -- then read back truncated at the delimiter by Get,
List, or a process restart, with the remainder unaddressable and no error
anywhere along the path.

Fixed at the producer, in the render/parse pair that owns the block format:
renderBlock escapes the two delimiter shapes (an empty line becomes a single
backslash, a line already starting with a backslash or "## " gains one) and
parseBlocks undoes it on the way back, so a record's content survives the
write whole. Rejecting the content instead would have made an ordinary
multi-paragraph note or a quoted heading unrepresentable; escaping every line
would have changed the on-disk shape of every record. Only the lines that need
it are escaped, so a one-paragraph record is byte-identical to what the
unfixed engine wrote and the document stays hand-editable.

Reachable from both producers: the chat tool's note and the curator's
model-extracted fact are free text, and neither is constrained to one
paragraph.

Tests: TestBuiltinEngineRenderedBlockRoundTripsContent asserts
parseBlocks(renderBlock(c)) == c for eleven content shapes, and
TestBuiltinEngineContentSurvivesTheWriteAndAReopen carries the same shapes
through Create, Get, and a second engine reading the file a restart would.

* fix(memory): compare Update's expected revision against the file, not the cache

Update read the record to compare against out of findBlock(stores.live, ...)
-- the engine's cached copy of the scope document -- and checked Expected
against that copy. This engine caches one document per scope and rewrites it
whole, so a second engine over the same scope file (archied and the gateway,
or a restart) holds a copy taken when it last read the file: its view of the
record's revision is superseded, Expected matches the revision it remembers,
ErrStaleRevision never fires, and the rewrite that follows writes that stale
copy back over the file -- discarding the other writer's update and every
record written since the copy was loaded. The field existed and could not
fire.

Reload the scope document before anything is decided from it, so the check
answers about the revision actually on disk and the rewrite starts from the
current document. That is the smaller of the two fixes the PRD leaves open
("Not determined": a reload-before-mutate or an advisory lock); no locking
scheme, no retry loop, and no change to the read paths.

Still unsolved, and deliberately: the whole-document rewrite is
last-writer-wins between the reload and the write, so two engines writing one
scope concurrently can still lose one of the two writes, and HISTORY.md is
rewritten from the cached copy the same way.

Tests: TestBuiltinEngineSecondEngineCannotReuseAStaleRevision asserts the
second engine gets ErrStaleRevision and the first writer's state survives;
TestBuiltinEngineUpdateDoesNotEraseRecordsItHasNotLoaded asserts the record
written after the second engine loaded is still there after its update.

* fix(memory): emit the scanner's warning instead of dropping it

scanContent returned nil for every result that was not ThreatBlock, so a
ThreatWarn result -- documented in the scanner as "allow the write but emit a
warning", and what every sensitive-data match produces (API keys, passwords,
tokens, private keys) -- was stored with no audit signal anywhere. The
comment justified the silence by pointing at Bind, but Bind's argument is
about Registrar.Events: internal/events declares no memory kind and the
composition binds no memory event sink, so an invented kind would look wired
and not be. A scanner warning is a diagnostic rather than an event, and there
was nothing else to carry it: the registrar had no logger.

Bind now takes Registrar.Log, optional and mirroring the curator family's
Registrar for the same reason, scanContent emits the warn-level result
through it before the write is allowed, and bootstrap passes the daemon's
logger so the line reaches archied's configured sinks instead of only the
process default. The write is still allowed: only the silence changed.

Tests: TestBuiltinEngineScanWarnsWithoutRefusingTheWrite runs Create and
Update over warn, clean and block content, asserting the write lands either
way, that a warn-level scan result logs exactly one warning carrying the
scanner's own message, that clean content logs none, and that a refused
block-level match logs none.

* test(memory): carry every content shape through Update and Revisions

Update replaces the block it read out of the document by that text, and
retains the superseded state in HISTORY.md, so an escaped block has to be
found, superseded and retained exactly like an unescaped one. Covered here
rather than left to the Create path: without the escaping, every shape in
this table came back truncated after an update, including the plain
one-paragraph record whose replacement holds a blank line.

The test asserts values only: the updated record as a second engine reads it
off disk, and the superseded content as Revisions returns it.

* style(memory): apply the linter's gofumpt form to the Update revision error

golangci-lint's bundled gofumpt wants the closing paren of that wrapped
fmt.Errorf on its own line; the standalone gofumpt binary the fmt task uses
(0.7.0, a different version) leaves it as it was. The text is unchanged from
before the engine fixes in this branch, so this is pre-existing drift inside a
function these commits already touch -- taken so the file is clean under both
formatters rather than only one.
2026-09-19 11:13:21 +10:00

34 KiB

Agent System

Status: Current-state investigation in progress
Date: 2026-07-28
Tracking issue: #73

Domain framing

The domain is the Agent System.

Task is not a core Agent System concept. Forge tasks, forge issues, Jira issues, email, Telegram messages, webhooks, and future external inputs are channel-specific messages. Channels translate those messages into requests to the Agent System; external issue or task models MUST NOT shape execution state.

The current store.Task is a persisted workflow execution. Treating that row as a task-domain aggregate would incorrectly turn Archie into an agentic issue board.

Canonical agent interaction model

An Agent is a persistent assistant selected for an interaction. It is not a model invocation and is not a WorkflowExecution.

Each Agent has its own:

  • immutable acting IdentityID for ownership and audit;
  • durable memory and learned information about the user;
  • perspective, specialisation, instructions, and communication behaviour;
  • conversation history and channel bindings;
  • available tools, capabilities, and policy;
  • continuity across model or provider changes.

The underlying model is a replaceable runtime dependency. Changing a model, provider, or model version MUST NOT create a new Agent, discard its memory, or change ownership of its history.

A user MAY create multiple Agents. Each Agent develops its own memory and view of the user from the interactions and responsibilities assigned to it. Memories MUST NOT be silently pooled merely because Agents belong to the same user or application.

Agent and Identity are separate aggregates. Every Agent references exactly one acting IdentityID, and no two Agents share an agent identity. User, system, and service-account identities may exist without an Agent.

An action initiated through an Agent records the Agent's acting IdentityID and, when applicable, the initiating user's IdentityID. A future fully automated WorkflowExecution MAY use an explicitly selected service-account identity for a concrete unattended use case; this is not the default execution identity.

Workflow execution identity

A Workflow is owned by an IdentityID. By default, every WorkflowExecution acts as the Workflow owner's identity.

Future delegated execution MAY add an explicit RunAsIdentityID assignment to a Workflow. This allows a Workflow owner to select another user or service-account identity for execution without changing Workflow ownership. Until that capability is deliberately introduced, owner identity and execution identity are the same.

WorkflowExecution audit records MUST preserve the Workflow owner, effective execution identity, initiating user when one exists, and any explicit delegation that selected a different run-as identity.

Memory scopes

The Agent System requires four distinct durable memory scopes:

  • global shared memory: information intentionally available across the Archie application;
  • agent-wide memory: general expertise, operating knowledge, and perspective owned by one Agent and safe for that Agent to use across users;
  • user-wide memory: information associated with one user and available to authorized Agents serving that user;
  • Agent-user relationship memory: private history and learned context from one particular Agent's relationship with one particular user.

Agent-wide memory is private to its owning Agent by default. Another Agent MUST NOT read, inherit, search, or mutate it implicitly.

Agent-user relationship memory is addressed by both AgentID and User IdentityID. Neither another Agent serving the same user nor another user speaking to the same Agent may access it implicitly.

Archie is a multi-user system even when initially deployed for one person. Multiple users, including family members, may interact with the same configured Agents. Per-user memory is therefore an isolation and personalization boundary, not merely an attribution tag on the primary user's records.

An Agent MUST resolve the initiating user before assembling memory context. Memory belonging to one user MUST NOT become visible to another user merely because both users interact with the same Agent.

Shared memory does not erase provenance. Every memory record retains its scope, author or acting identity, originating user when applicable, source, and revision history. The rules for selecting a write scope, granting access to global and user-wide memory, and authorizing explicit cross-scope sharing are settled by docs/prds/memory-engine-unification.md and recorded in migration-decisions.md section 5.

An Agent interaction may answer conversationally, use a tool or capability, read or send messages, retain information, or propose durable workflow-backed work. None of these operations inherently requires a WorkflowExecution.

Agent and Workflow domain boundary

Agent and Workflow are separate domains:

internal/domain/agent
internal/domain/workflow

The Agent domain owns persistent assistants, their specialisation, instructions, model-independent continuity, capability context, and associations with identity and memory.

The Workflow domain owns reusable, user- or Agent-defined behaviour and every durable execution of that behaviour. An Agent may invoke or define a Workflow, but the Workflow is not part of the Agent aggregate and does not require a conversational Agent interaction to execute.

Canonical workflow model

The Workflow feature uses these canonical terms:

  • Workflow: a reusable, versioned definition of how an agent behaves and performs a kind of work.
  • WorkflowExecution: one durable execution of a specific Workflow version.
  • WorkflowStep: one defined operation in a Workflow.
  • StepExecution: the recorded execution and outcome of one WorkflowStep.
  • Attempt: a retry of the same WorkflowExecution, not a new execution.

A Workflow MAY structure any repeatable agent behaviour, including personal assistance and scheduled routines. For example, a morning email review may combine a schedule event, message retrieval tool, LLM classification and summarisation, and delivery of the resulting rundown. Workflow is therefore not restricted to forge work, source changes, or requests submitted by a user at execution time.

Workflows are extensible through Workflow-owned plugins. The Workflow domain defines the typed plugin registration, definition, validation, versioning, and execution contracts. Users and Agents may define reusable Workflows through those contracts.

The generic plugin contract remains metadata-only. It MUST NOT own Workflow semantics or replace the Workflow registry with generic hooks.

Workflow and WorkflowExecution are the names used in architecture, generated reference, configuration, commands, events, and external contracts. The implementation MAY use package qualification to remain concise:

workflow.Definition
workflow.Execution
workflow.Step
workflow.StepExecution

The unqualified name Execution MUST NOT be used in cross-domain contracts or documentation because it is ambiguous among workflow, tool, command, policy, and service execution.

Current workflow-execution feature

The current feature takes a channel request through agent execution and a durable outcome.

Current execution state includes source-message references, owning identity, repository, selected workflow and stage, agent output, branch and pull-request references, token and iteration counts, retry information, human-wait information, and failure details.

The current store.Task lifecycle uses:

queued -> running
running -> waiting_human | pr_open | merged | parked | closed_wont_do
waiting_human -> queued | closed_wont_do
parked -> queued | dead
pr_open -> merged | rejected
running after crash -> queued

Workflows select and sequence deterministic and agent-run stages. Implement, TDD, feasibility, and bootstrap are current Workflow definitions. Every WorkflowExecution is handed wholesale over core NATS to a task-scoped archie-agent container, which owns the workflow stage loop.

Current workflow-feature placement

The behaviour is divided across technical packages:

  • internal/store defines the current Task execution record and status 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/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.
  • internal/gate and repository configuration define execution constraints.
  • internal/gateway duplicates task status strings and applies task-control rules.
  • forge, worktree, NATS, SQLite, containers, and agent runtimes are concrete dependencies mixed into orchestration.

Current task meanings and required replacements

The existing code uses task for unrelated concepts. Migration MUST resolve each meaning deliberately; a global text replacement is prohibited.

Current meaning Representative locations Target concept Requirements
Forge issue or external task internal/forge, daemon polling Channel message Preserve the channel's native reference and payload. Translate it into an Agent System request without importing forge or issue semantics into Workflow.
Jira issue or other external work item Messaging infrastructure adapter Channel message or external artifact The external system retains its own vocabulary inside its integration. Its record may lead to an accepted work request but is not a Workflow or WorkflowExecution.
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/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/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.
Gateway TaskCreator internal/gateway Accepted work request handoff A channel may carry a request for durable workflow-backed work, but it does not request or create a WorkflowExecution directly. Work intake admits and routes the request; the Agent System consumes the accepted work request and is the sole owner of selecting a Workflow version and creating the WorkflowExecution. Ordinary agent interactions do not require this handoff.
Gateway TaskController and ChatTaskStatus internal/gateway/tasks.go WorkflowExecution commands and query view Approve, cancel, and status use Agent System contracts. Channel code does not duplicate lifecycle constants or decide transitions.
Gateway TaskProfile internal/gateway/tasks.go, cmd/archied Channel/identity execution defaults This is configuration selecting allowed source targets and default Workflow inputs, not task state. Split it into settings owned by the relevant channel and Agent System features.
config.TaskConfig and TaskForge internal/config Worker execution settings and channel/service references Dissolve with internal/config. Each field moves to its owning runtime settings or versioned WorkflowExecution handoff contract. Secrets and external configuration forms do not enter the domain.
events.Event.TaskID, task event timelines internal/events, stores, web UI WorkflowExecutionID and WorkflowExecution events Authoritative events are Agent System events. Observability and timelines project those events rather than inventing parallel generic task events.
Web UI task lists and counts internal/webui, store query APIs WorkflowExecution read model Dashboard status, history, and counts are projections of WorkflowExecution state and events. The UI does not depend on persistence records.
Task-scoped forge/store/worktree RPC forgerpc, storerpc, worktreerpc, registerTaskRPCServers Execution-scoped capability ports Worker calls use narrow domain-required service contracts, carry WorkflowExecutionID and IdentityID, and resolve the owning capability binding. Root-client fallback is forbidden.
Per-task worktree, branch, volume, and cleanup daemon, worktree, storage, container WorkflowExecution workspace Every WorkflowExecution receives isolated workspace state. Workspace lifecycle is explicit, identity-aware, recoverable, and controlled outside the model.
Task retry, dead, waiting-human, PR reconciliation daemon, workflow, gateway WorkflowExecution lifecycle policies Retry, waiting, cancellation, reconciliation, and terminal outcomes are Agent System behaviour. Channels and infrastructure report facts or submit commands; they do not mutate state.
Task-run readiness and retry timeouts daemon taskrun request loop Worker-dispatch settings and policy These settings govern WorkflowExecution handoff availability. They are not Workflow data and must be owned by the worker-dispatch capability.

Terms that do not migrate

  • The task command in Taskfile.yml is the external Task build tool and keeps its name.
  • A forge may call its own records issues or tasks inside its channel adapter.
  • General prose may use “task” informally only when it clearly refers to an external system. Agent System contracts and generated reference MUST use the canonical Workflow vocabulary.

Current WorkflowExecution data inventory

This inventory is the migration ledger for data currently spread across store.Task, database-only columns, workflow.TaskContext, worker messages, and surrounding configuration. Implementation SHOULD NOT require another repository-wide search to determine what existing execution data must be preserved or deliberately removed.

Current data Current representation Required target
Execution identity Task.ID, task_id, NATS subjects, logs Immutable WorkflowExecutionID used consistently by state, events, workers, projections, and capability calls
Owning actor Task.Identity string Canonical IdentityID
Source type Task.Source (forge or chat) Typed channel and SourceMessageReference; no closed source enum in WorkflowExecution
Source address Owner, Repo, IssueNumber; synthetic chat issue number Channel-owned source reference with native message/thread/object identifiers; synthetic identifiers removed
Requested work Title, Body, Labels Immutable execution input captured from the source request; channel-specific metadata retained in the source envelope
Workflow selection Workflow string Immutable WorkflowID plus selected WorkflowVersion
Lifecycle Status string Enforced WorkflowExecution state
Current position mutable Stage string Derived current WorkflowStep reference plus durable StepExecution history
Attempts Attempt, RetryCount Execution attempt history and retry-policy evidence; distinguish worker delivery retry from workflow retry
Failure ParkReason, transition detail, response errors Typed failure classification, evidence, retryability, and resulting lifecycle event
Human wait WatchCommentID, waiting_human Channel-neutral wait condition and correlation reference; forge comment IDs stay in the forge channel
Workspace Dir, Branch, worktree path, task.json Execution workspace reference and independently managed workspace lifecycle
Change outcome BuildSummary, BuildNoChanges, changed files Step outputs and final WorkflowExecution outcome
Reproduction evidence ReproProof Typed TDD step evidence retained with the StepExecution and final outcome
Planning output Plan Typed step output referenced by later steps rather than a special aggregate field
Notes Notes, appended agent notes Ordered execution annotations with actor, source step, and timestamp
Pull request PRNumber, forge host/repository assumptions Forge-channel delivery reference and reconciliation state
Agent usage TokensUsed, Iterations StepExecution usage measurements aggregated into execution projections
Decision capture private feasibility decision, capture-tool output Typed WorkflowStep output defined by that Workflow version
Terminal outcome mutable Outcome{Status, Detail} Explicit WorkflowExecution outcome command/event validated by the state machine
Skill context SkillBody, SkillPlugins Resolved Workflow version dependencies or execution inputs, with provenance
Agent prompt context SystemPrompt, ExtraRules, mission strings Versioned WorkflowStep definition plus resolved execution context; mutable global prompt callbacks removed
Gates and protection Gate, Preflight, Protection, repository config Agent System policy definitions resolved for the WorkflowExecution and enforced outside the agent
Budgets steps, tokens, wall clock, gate failures Execution and StepExecution policy values with measured usage and evidence
Tool access capture tools, registry, guardrails, skill plugins Resolved step capability set and policy; global registry pointers do not enter execution state
Persistence timestamps SQL created_at and updated_at Domain timestamps and version used for optimistic concurrency and audit
Transition history SQL transitions and generic events Authoritative WorkflowExecution domain events stored atomically with state

Current runtime responsibilities to unify

The following behaviours currently act on the same WorkflowExecution but are implemented in different packages:

  • accept a request from a channel and enforce idempotency;
  • select and version a Workflow;
  • create, queue, claim, schedule, and execute a WorkflowExecution;
  • serialize same-repository execution where policy requires it;
  • resolve identity-specific capabilities;
  • prepare, retain, recover, and clean up the workspace;
  • run deterministic and agent-backed WorkflowSteps;
  • enforce gates, budgets, protected paths, tool constraints, and result review;
  • persist state and StepExecution outputs;
  • publish authoritative lifecycle events;
  • wait for channel input and resume;
  • classify failure, retry, park, mark exhausted, cancel, or recover after crash;
  • deliver and reconcile forge changes;
  • project status, history, counts, and audit for channels and the web UI;
  • hand execution to a worker without moving domain ownership to the worker.

Current workflow-feature hazards

  • There is no enforced WorkflowExecution state machine. Store.Transition ignores the supplied from state when updating the row.
  • State update and transition-history insertion are separate operations, so state and audit can diverge.
  • Callers frequently discard persistence and transition errors.
  • Gateway task control duplicates lifecycle status constants by hand.
  • workflow.TaskContext is a mutable service bag containing complete configuration plus forge, store, worktree, agent, event bus, logging, memory, guardrails, skills, and scratch state.
  • Lifecycle changes occur in both daemon and workflow code.
  • Workflow orchestration runs inside task-scoped agent containers while the daemon retains lifecycle, admission, and authority-bearing RPC ownership.
  • Forge-backed and chat-created work share one record through source flags and synthetic issue numbers.
  • Repository labels currently select workflows and mirror task state, coupling domain transitions to forge presentation.
  • Failure generally becomes parked, but failure classification and retryability are not represented explicitly.
  • Generic observability events are emitted alongside state changes rather than being the authoritative domain events.

Existing invariants to preserve

  • The model never performs git operations directly.
  • Deterministic policy and gates cannot be waived by the agent.
  • TDD captures a failing reproduction before implementation and protects the test during the fix.
  • Every run ends in an explicit outcome; definition errors and stage errors do not disappear silently.
  • Crash recovery requeues interrupted work.
  • Agent execution crosses a versioned data boundary.
  • Forge, persistence, workspace, transport, container, and model runtimes remain replaceable infrastructure.
  • Work from the same repository is serialized by default.

Required migration

  • Rename the current persisted store.Task concept to WorkflowExecution.
  • Replace task lifecycle terminology in core commands, events, persistence, worker contracts, logs, and generated reference.
  • Preserve external source terminology only inside its channel adapter.
  • Replace synthetic issue numbers with explicit source-message references.
  • Associate every WorkflowExecution with an immutable Workflow identifier and version.
  • Record StepExecutions explicitly rather than treating one mutable stage field as complete execution history.
  • Keep Attempt as retry state within the same WorkflowExecution.

Curator isolation invariant

Decided 2026-08-05 (#435 epic, #98 runtime). Recovered 2026-08-09 from the pre-migration issue tracker.

Curators are peers, not dependencies. They must never block, delay, or take down chat turns, agent runs, or the daemon.

  1. Registry-owned goroutines, one per curator, with per-pass recover(), per-pass budgets (max steps, tokens, timeout), and a configurable maximum of concurrent passes (default 1) so curators cannot saturate the shared LLM runtime against chat.
  2. Wake events ride the in-process events.Bus, which is mutex fan-out with bounded per-subscriber buffers that drop on overflow (internal/events/events.go). A slow curator can never backpressure the chat publisher.
  3. Wake is a best-effort nudge. The trigger is a deterministic read of persisted primary-input state at pass time, so a dropped wake only delays a run to the next check-in and never corrupts trigger accounting (#22).
  4. The curator registry lifecycle is independent of the agent loop. Daemon shutdown cancels in-flight passes and waits bounded.

Chat turns keep their per-session lanes; agent runs keep their workflow goroutines and containers. Rule of thumb: no code path a curator executes may ever appear on a chat turn's critical path.