docs(development): checklists for every kind of change

docs/development/ holds one page per kind of change (settings, State Store
and persistence, task lifecycle, workflows and steps, event automation,
dashboard, agent execution and containers, processes and wiring, merging
work), each naming every layer the change must reach and pointing at the
document that owns the design. The docs build puts them in the development
set; docs/index.md and CLAUDE.md link them.

Also adds the container-profile case to the validator agreement test, the
check the profiles work skipped.
This commit is contained in:
sam committed 2026-09-24 21:03:34 +10:00
1 parent 4046766abe
commit 4fe3bc13ee
17 files changed
+569 -3

No files matched your search

+3
View File
@@ -33,6 +33,9 @@ git, and agent execution functions as a strict data boundary. Before adding a ne
plugin engine, satisfy
`docs/architecture/plugins-and-extensions.md#plugin-engine-rule-strict`.
Before changing a subsystem, read its checklist in `docs/development/`: each
page names every layer that kind of change must reach.
## Scope Discipline
`docs/architecture/` is authoritative for settled design.
+102
View File
@@ -102,6 +102,66 @@
"section": "Architecture",
"body": "# Safe Change and Recovery\n\n**Status:** Requirements approved; mechanics are under design. Database-backed settings are implemented through the control plane (2026-09): see the degrade/recovery section below, which records a gap rather than a solution. The full runtime-supervision protocol (bounded observation, versioned audit trail) remains under design.\n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nArchie is built and improved by agents as well as humans. The architecture MUST\nmake a change easy to locate, understand, test, audit, extend, and reverse\nwithout requiring its author to understand unrelated parts of the application.\n\nSeparation of concerns is therefore an operational safety boundary, not only a\ncode-organisation preference.\n\n## Required outcomes\n\n- An agent can improve a focused feature without receiving authority over\n unrelated domains.\n- Every event, function, action, setting, and policy has an identifiable owner\n and provenance.\n- Source and runtime changes pass deterministic checks outside the actor making\n the change.\n- A rejected or unhealthy candidate cannot replace the last known working\n version.\n- Invalid user configuration does not terminate an otherwise healthy\n application.\n- Configuration and service failures are observable, attributed, and eligible\n for bounded remediation or rollback.\n- The application continues serving unaffected capabilities when one\n capability is misconfigured or unhealthy.\n- Recovery failure is reported and contained rather than hidden in an\n unbounded retry loop.\n\n## Source changes\n\nAgent-authored source changes occur through the task-execution boundary in an\nisolated workspace. The agent does not directly mutate the running\ninstallation.\n\nPromotion is controlled by deterministic repository-owned policy, including\ntests, generated-reference drift checks, protected paths, change scope, and\nother required gates. The actor proposing a change cannot waive these checks.\n\nRepository and domain separation SHOULD allow a task to load and modify only\nthe governing requirements and code for its declared scope.\n\n## Runtime changes\n\nConfiguration and other runtime changes are proposed as candidates rather than\nmutating the active state in place.\n\nThe affected domain owns:\n\n- the command describing the semantic change;\n- validation of its typed settings;\n- health signals that demonstrate correct operation;\n- domain-specific remediation and rollback consequences.\n\nShared policy supplies consistent evaluation, evidence, and audit mechanics.\nIdentity supplies actor attribution. Infrastructure supplies external\nconfiguration storage, service control, and other operational adapters.\n\n## Runtime change protocol\n\nLast-known-good preservation and candidate promotion are the universal runtime\nchange protocol.\n\n1. An identity proposes an immutable candidate version.\n2. Infrastructure parses it without changing active state.\n3. Each affected domain validates its typed settings.\n4. Shared policy evaluates cross-cutting constraints.\n5. Each affected capability prepares the candidate without destroying its\n active instance.\n6. Capability-specific health checks prove the candidate works.\n7. Runtime supervision atomically promotes the candidate.\n8. A bounded observation period watches for delayed failure.\n9. Failure restores the last-known-good version and records the reason,\n evidence, actor, and involved versions.\n10. Repeated remediation failure stops retrying, isolates the capability, and\n reports the fault.\n\nThe affected domain owns the semantic change command, typed validation, health\nsignals, and remediation consequences. Shared runtime supervision owns the\npromotion transaction. Infrastructure performs storage and service-control\noperations.\n\nThe protocol's exact Go contracts, storage model, atomicity boundary, and\nobservation rules require a focused runtime-supervision design pass.\n\n## Failure isolation\n\nInvalid input MUST leave the active valid configuration unchanged and produce a\ndiagnostic record.\n\nA capability that cannot start or reload SHOULD fail independently where its\nabsence does not violate a declared application invariant. Unaffected\ncapabilities continue operating.\n\nRemediation MUST be bounded, observable, and policy-driven. Recovery MUST NOT\nsilently oscillate between versions or retry forever.\n\n## Database settings: degrade paths and recovery (2026-09)\n\nThe control plane owns runtime-tunable settings and stores them in the State\nStore's PostgreSQL database.\nThis replaced a dashboard overlay store that degraded to file config on any\nfailure and had three documented ways back. The replacement has none, and the\nposture is the opposite: **the daemon fails closed.**\n\n### Degrade paths\n\n| Failure | Boot behaviour | Where the operator sees it |\n| --- | -Line truncated
},
{
"url": "/dev/development/",
"title": "Development guides",
"section": "Development",
"body": "# Development guides\n\nChecklists for changing Archie. Each page covers one kind of change and names\nevery place that change must reach, so a feature that works in one layer does\nnot silently stop at the next. The pages point at the documents that own the\ndesign (`docs/architecture/`, the PRDs, `CLAUDE.md`) rather than restating\nthem.\n\n| Changing | Guide |\n| --- | --- |\n| A setting in `config.toml` or the dashboard | [Configuration settings](/dev/development/config-settings/) |\n| A stored field, table, RPC or error | [State Store and persistence](/dev/development/state-store-and-persistence/) |\n| Task statuses, fields or the task brief | [Task lifecycle](/dev/development/task-lifecycle/) |\n| Workflow definitions or step types | [Workflows and steps](/dev/development/workflows-and-steps/) |\n| Sources, event types, mappings or bindings | [Event automation](/dev/development/event-automation/) |\n| Anything under `ui/` | [Dashboard](/dev/development/dashboard/) |\n| The agent container, its image or its tools | [Agent execution and containers](/dev/development/agent-execution-and-containers/) |\n| A process, plugin engine, channel or NATS subject | [Processes and wiring](/dev/development/processes-and-wiring/) |\n| Merging a lane or a branch | [Merging work](/dev/development/merging-work/) |\n\n## Every change\n\n- Write the failing test first for anything with logic, branching or a\n contract, and check it fails on an assertion, not a compile error.\n- Test through the path production uses. A test that sets a value directly on\n the consumer proves nothing about the layers that normally deliver it.\n- Run `task check` and let its exit status decide the commit:\n `task check \u0026\u0026 git commit ...`. `task test` passes `-short`, which skips the\n process and Postgres tests, so run `go test -count=1 ./cmd/... ./internal/...`\n too when a change crosses a process or the database.\n- Regenerate, never hand-edit, generated output: `task proto:generate`,\n `go -C tools tool sqlc generate -f $PWD/internal/infrastructure/postgres/sqlc.yaml`,\n `task ui`, `task docs:artifact`. `task proto:check` compares against the git\n index, so stage regenerated contracts before running it.\n- Stage by path, or read `git status` before `git add -A`. Tests that start\n embedded NATS or write logs must use `t.TempDir()`; anything they leave in the\n tree gets committed. `task check` also adds linter-tool lines to `go.sum`\n (bead 1e37); restore `go.sum` before committing unless you changed a\n dependency.\n- A change to `docs/prds/` or `docs/architecture/` carries the regenerated\n `docs/data/generated/dev-docs.json`, and PRD edits follow\n `docs/prds/RULES.md` and pass `task docs:prds`.\n"
},
{
"url": "/dev/development/agent-execution-and-containers/",
"title": "Agent execution and containers",
"section": "Development",
"body": "# Agent execution and containers\n\nAuthority: `docs/architecture/agent-system.md` (execution boundary, the model\nnever runs git) and the Deployment Model section of `CLAUDE.md`.\n\nThe daemon prepares a workspace, starts one container per task from a profile's\nimage, and hands the whole task to `archie-agent` over NATS in one\n`taskrun.Request`. The agent reaches the State Store, forge and worktree push\nonly through the daemon's RPC servers, using task-scoped credentials.\n\n## Giving the agent something new\n\n- **Data about the task** goes in `taskrun.Request` or the task brief\n (`container.TaskPayload`), never in an environment variable. Add a test that\n the request carries it (`TestRunViaAgentSendsMCPServers` is the pattern).\n- **A credential** is scoped to the task and revoked when it ends, like the\n State Store grant and the worktree publication grant. The daemon's own\n administrative token never enters a container.\n- **A tool** reaches the agent through the central registry, MCP, a repository\n script or a skill plugin. A profile's `tools` list filters those; ai-sdk\n agentloop's built-in file tools are outside it. A tool that must stay inside\n the workspace uses the agent loop's confinement, not its own path handling.\n\n## Changing the agent image or a profile image\n\n1. The agent image is `Dockerfile`; example profile images live in\n `examples/profiles/`, each with a build-only service in\n `docker-compose.yml` (`profiles: [\"build\"]`, so `up -d` never starts it).\n2. Anything the agent runs must be in the image. The container gets no\n package manager at run time beyond what the image ships.\n3. A locally built image needs `containers.pull_policy = \"missing\"`;\n `\"always\"` tries to pull it and fails.\n4. Profiles are configured under `[containers.profiles.\u003cname\u003e]` and resolved\n by the daemon before the container starts (`pinTaskProfile`). An unknown\n profile parks the task; it never falls back to the default image.\n\n## Changing how a task runs\n\n- Workspace preparation happens in the daemon (`prepareWorkspace`) before the\n container starts, because the container binds the directory. Clones need the\n daemon's forge credential; the agent never clones.\n- A task with no repository gets `worktree.Manager.ScratchDir`, which is\n removed when the task ends.\n- The agent runs as root in the container. Anything it writes into the\n bind-mounted workspace is handed back to the daemon's UID\n (`restoreWorktreeOwnership`); a new write path must stay inside that\n workspace.\n- NATS rules are in `CLAUDE.md`: task responses use `msg.Respond`, a responder\n is flushed after it registers, and `ARCHIE_TASKS` is a work queue.\n"
},
{
"url": "/dev/development/config-settings/",
"title": "Configuration settings",
"section": "Development",
"body": "# Configuration settings\n\nAuthority: `docs/architecture/configuration.md`. The wiring matrix, the\ndecoded-but-unwired ledger and the three shapes an unwired field takes are in\n`.agents/skills/archie-config-and-flags`.\n\nA field that parses is not a field that works. Before adding one, name the code\nthat reads it and the path the value takes to get there.\n\n## Decide what kind of setting it is\n\n- **Bootstrap-only** (read once at process start: `database_url`, `state_dir`,\n `work_dir`). It stays in the file, is checked by `validateBootstrap` in\n `internal/infrastructure/configuration/validate.go`, and the runtime overlay\n refuses changes to it.\n- **Database-owned** (repository policies, scheduling, tools, plugins,\n channels, containers). The file only seeds it. Once the State Store holds the\n control-plane resource, the stored document is layered over the file\n (`controlplane.Client.RuntimeConfig`) and the file key stops mattering. It is\n checked by `validateDatabaseOwned` and by the resource's validator.\n- **Worker-carried.** A value the agent container needs travels in\n `config.TaskConfig` (`Config.ForTask`) or on `taskrun.Request`. Never pass it\n as an environment variable the daemon did not already define, and never carry\n a secret this way.\n\n## Adding a database-owned field\n\n1. Add it to the struct the resource's `Document` names in\n `internal/app/controlplane/operational_settings.go`. The resource's JSON\n schema and the dashboard's Advanced settings editor are generated from that\n type, so no UI work is needed for the editor itself.\n2. Stored documents use Go field names as keys (`Image`, `MaxConcurrency`).\n Give the field no `json` tag unless its neighbours have one.\n3. A map or a nested struct needs its layering checked. `json.Unmarshal`\n merges into an existing map, so a stored map would add to the file's rather\n than replace it. A field the stored document omits keeps the file's value\n (a document stored before the field existed). Add a case to\n `internal/app/controlplane/runtime_config_test.go` for both.\n4. Validate it in one function both sides call, and add a case to\n `TestResourceValidatorsRejectWhatEffectiveValidationRejects` in\n `validators_agree_test.go`, so the file and the resource cannot disagree.\n5. Decide whether it reloads: it does only if every consumer re-reads it from\n `config.Holder`. The allowlist is `internal/app/archied/reload.go`; anything\n not on it requires a restart.\n6. If the settings page shows it as a plain field, add it to\n `internal/webui/config_schema.go` and the view in `api_config.go`.\n\n## Every new field\n\n- Test through the layering: build the effective config the way boot does,\n not by setting the field on the consumer.\n- Add a commented example to `config.example.toml`. Touch `deployments/*.toml`\n only when a profile there needs a value different from the default.\n- Update the wiring matrix in `.agents/skills/archie-config-and-flags`.\n- Secrets are `SecretRef`s resolved through the secret registry. Never inspect\n a resolved value, even in a test.\n- Reject a configuration that sets a field with no consumer rather than\n accepting and ignoring it (per-identity `forge.intake` is the precedent).\n"
},
{
"url": "/dev/development/dashboard/",
"title": "Dashboard",
"section": "Development",
"body": "# Dashboard\n\nAuthority: `.agents/skills/archie-web-ui` (stack facts, design-system rules,\ntone and accessibility). This page covers what a change must reach, not how it\nshould look.\n\n## Adding or changing a feature\n\n1. The feature lives in `ui/src/\u003cfeature\u003e/`. Move a helper to `ui/src/base/`\n only when a second feature needs it.\n2. Keep wire shapes, draft state and payload building in a plain `.ts` module\n beside the components (`ui/src/bindings/binding-draft.ts` is the pattern),\n and test it in `ui/test/*.test.ts`. Components stay thin.\n3. Every mutation goes through `api.*` in `ui/src/lib/api`, which sends the\n CSRF and Content-Type headers the server's mutation guard requires. A bare\n `fetch` is refused.\n4. A value the server also describes (task statuses, actions, workflow inputs)\n comes from the server. Keep a local default only so the first render works,\n and keep it in step (`ui/src/lib/task-meta.ts`).\n5. Run `task ui`, `task test:ui` and `cd ui \u0026\u0026 npm run typecheck`. Commit the\n regenerated `ui/dist/`; the Go binaries embed it.\n\n## Adding an API route\n\n1. The handler goes in the `internal/webui/api_\u003cconcern\u003e.go` file for its\n concern. Check the request fully on the server; the UI's checks are only a\n convenience.\n2. A mutation calls `authorizeTaskMutation` first.\n3. A route whose store is not configured answers 503, and\n `internal/app/archieui/degraded_routes_test.go` pins what each route\n returns without its contract. Add the route there.\n4. The dashboard runs in its own process (`archie-ui`) and must not link the\n daemon or the workflow engine (`cmd/archie-ui/architecture_test.go`). Reach\n stored data through `storecontract` interfaces wired in\n `internal/app/archieui/compose.go`.\n5. Settings that live in a control-plane resource need no new route: the\n Advanced settings page edits every resource from its generated schema.\n"
},
{
"url": "/dev/development/event-automation/",
"title": "Event automation",
"section": "Development",
"body": "# Event automation\n\nAuthority: `docs/prds/event-automation.md` (the model: source, event type,\nmapping, binding, workflow, profile) and `docs/architecture/bindings.md`\n(threat model).\n\n## Where each check lives\n\nA binding is checked twice, and a new rule usually belongs in both places:\n\n- **On save**, in `checkedBinding` (`internal/webui/api_binding.go`), so the\n operator sees the problem while editing. It calls the domain checks\n `binding.Validate`, `binding.CompileFilter` and `Binding.CheckWorkflow`.\n- **At dispatch**, in `dispatchOneBinding` and `resolveBindingTarget`\n (`internal/daemon`), because the workflow or mapping may have changed since\n the save. A refusal is recorded with `recordDispatchFailure` and starts no\n task.\n\nPut the rule itself in `internal/domain/binding` or\n`internal/domain/workflow/task` and call it from both, rather than writing it\ntwice.\n\n## Adding a binding field\n\n1. Domain type and `Validate` in `internal/domain/binding`.\n2. Column, queries, store mapping, wire field, `newColumns`\n ([State Store and persistence](/dev/development/state-store-and-persistence/)).\n3. The request type and `checkedBinding` in `api_binding.go`.\n4. The draft, payload and editor in `ui/src/bindings/`\n ([Dashboard](/dev/development/dashboard/)).\n5. Its effect at dispatch, with a case in\n `internal/daemon/dispatch_inputs_test.go` or `dispatch_bindings_test.go`.\n\n## Rules that must hold\n\n- Signing belongs to the source. Intake verifies the HMAC against the source's\n secret before the payload is parsed.\n- An event must be identified as an event type before anything dispatches it,\n and a binding applies only to its mapping's event type. Dispatch test\n fixtures therefore create an event type before inserting captures.\n- The dispatch ledger is claimed before the task is enqueued (at most once).\n- Anything an event supplies that selects what the agent acts on, such as a\n repository, must be checked against configuration. An event never widens\n what an agent can reach.\n"
},
{
"url": "/dev/development/merging-work/",
"title": "Merging work",
"section": "Development",
"body": "# Merging work\n\nParallel lanes (see `.agents/skills/archie-agent-fleet`) merge into an\nintegration branch before `main`. Each merge is a change in its own right and\npasses the same gate.\n\n## Resolving conflicts\n\n- **Generated files** (`*.pb.go`, `postgresdb/*.go`, `ui/dist/`,\n `docs/data/generated/*.json`): take either side, then regenerate. Never merge\n them by hand.\n- **One side deletes a file, the other edits it**: the deletion wins when the\n deleting lane replaced the thing the file served. Move the other side's\n change onto its replacement.\n- **One side changes how code is built (a new store, renamed packages), the\n other what it does**: take the behaviour side's version and reapply the\n mechanical change to it. That is usually cleaner than merging line by line.\n- **Error sentinels** are rows in `wireErrors`, not switch cases.\n\n## After resolving\n\n1. Search for leftovers of anything the other side removed: the old package\n path, the old type, and comments describing the old behaviour.\n2. Tests written against one side's semantics may pass there and fail after\n the merge. A test that used to pass on the old store may be asserting a rule\n the other side deliberately changed. Fix the test's setup to the merged\n rule; do not loosen the rule to the test.\n3. Run the full suite without `-short`, then `task check`, then commit. Check\n `git status` for files a test wrote into the tree before staging.\n"
},
{
"url": "/dev/development/processes-and-wiring/",
"title": "Processes and wiring",
"section": "Development",
"body": "# Processes and wiring\n\nAuthority: `docs/architecture/organisation.md` (layers, process boundaries),\n`docs/architecture/dependencies-and-contracts.md` (dependency direction, wire\ncontracts) and `docs/architecture/plugins-and-extensions.md` (the plugin engine\nrule).\n\n## Placing new code\n\n- Domain logic, entities and the interfaces it needs go in\n `internal/domain/\u003carea\u003e/`, which imports no infrastructure or app package.\n- Implementations of those interfaces go in `internal/infrastructure/\u003cservice\u003e/`.\n- Construction and wiring go in `internal/app/\u003capplication\u003e/`; `cmd/` only\n parses flags and calls it.\n- `logging`, `events`, `eventbus`, `policy` and `taskstate` import no internal\n package. There is no `shared/`, `utils/` or `common/` package.\n- A behaviour has one authoritative path. Before adding a second way to do\n something, remove or redirect the first.\n\n## Adding a capability to a process\n\n1. Decide which process owns it. A new binary is justified only when the\n surface must fail, scale or run somewhere independently.\n2. Wire it at that process's composition root. An optional capability\n degrades: a missing provider logs a warning and marks health degraded\n rather than stopping the process (MCP providers are the model).\n3. Every process that reaches the capability through the State Store gets it\n through a `storecontract` interface asserted on the client\n ([State Store and persistence](/dev/development/state-store-and-persistence/)).\n4. The architecture tests (`cmd/archie-ui/architecture_test.go`,\n `cmd/archie-messaging/architecture_test.go`, `TestOpenStoresNeverOwnsTaskDB`)\n pin what each binary may link. A failure there means the placement is wrong,\n not the test.\n\n## Adding a plugin engine\n\nSatisfy every invariant in \"Plugin engine rule (strict)\" in\n`plugins-and-extensions.md`: typed domain contract, an owning manager,\nlifecycle and health, narrow host access, and an explicit trust boundary.\n`internal/plugin/architecture_test.go` checks the parts that can be checked.\n\n## Adding a channel or a NATS subject\n\n- Channel rules (Telegram's pending-update drop, command scopes) are in\n `CLAUDE.md` under Per-Package Invariants.\n- A subject is part of the wire contract. Its payload type belongs to the\n domain that defines its meaning, and the transport code lives in\n infrastructure.\n"
},
{
"url": "/dev/development/state-store-and-persistence/",
"title": "State Store and persistence",
"section": "Development",
"body": "# State Store and persistence\n\nAuthority: `docs/prds/state-store-contract.md` and the State Store section of\n`CLAUDE.md`. All persistence is PostgreSQL behind the standalone State Store\nprocess; nothing else opens the database.\n\n## Adding a column\n\n1. Write the next migration in `internal/infrastructure/postgres/migrations/`\n (`00NN_name.sql`, goose Up and Down). Give the column a `NOT NULL DEFAULT`\n that is correct for existing rows.\n2. Update the queries in `internal/infrastructure/postgres/queries/` and\n regenerate with sqlc. A query that lists columns (`ListTaskSummaries`, the\n binding selects) does not pick the new one up; `SELECT *` queries do.\n3. Map it in the store (`taskFromRow`, `bindingValue` and friends). If the\n column holds encoded data, the package that owns the type owns the encoding\n (`task.EncodeInputs`), and the store and the wire both use it.\n4. Add the column to `newColumns` in\n `internal/infrastructure/legacyimport/load.go` if legacy data has no value\n for it. The importer refuses a target column it cannot fill otherwise.\n5. Carry it over the wire (next section) if any process other than the State\n Store reads it.\n\n## Adding a field to a wire message\n\n1. Add it to `proto/state/v1/state.proto` with a new field number. Never reuse\n a number; retire one with `deprecated = true`.\n2. `task proto:generate`, then map it both ways in\n `internal/infrastructure/staterpc/values.go`.\n3. `TestTaskProtoCarriesEveryDomainField` fills every `task.Task` field and\n fails on one the mapping forgets. If it cannot fill the field's kind, extend\n it. Other messages have no such test, so add a round trip to\n `conformance_test.go`.\n\n## Adding an RPC or a store method\n\n1. Put the Go method on the narrow consumer interface in\n `internal/domain/storecontract` (keep each at eight methods or fewer) and add\n the matching RPC. A Go method without an RPC does not cross the process.\n2. Implement it in the Postgres store, in `staterpc.Client` (with its `var _`\n assertion) and in `staterpc.server`. A missing dependency answers\n `codes.Unavailable`, never a fabricated default.\n3. Wire the dependency in every composition that serves or consumes it:\n `stateStoreDeps` in `internal/app/archied/state_store.go`, the daemon's\n assertions in `bootstrap.go`, and `internal/app/archieui/compose.go` for the\n dashboard process.\n4. Task-scoped tokens may call only `Update`, `Transition` and `InsertEvent` on\n their own task (`staterpc.TaskGrants`). A new RPC is admin-only unless it is\n added there deliberately.\n5. Add it to `conformance_test.go`, which runs every surface over a real gRPC\n connection.\n\n## Adding an error sentinel\n\nAdd the sentinel to `storecontract`, a row to `wireErrors` in `values.go`, and\na case to `error_test.go`. The canonical message is part of the wire contract:\nchanging it breaks `errors.Is` on the client silently.\n"
},
{
"url": "/dev/development/task-lifecycle/",
"title": "Task lifecycle",
"section": "Development",
"body": "# Task lifecycle\n\nAuthority: `docs/architecture/agent-system.md`. The status vocabulary lives in\n`internal/taskstate`, which imports no internal package.\n\n## Adding a status\n\n1. Add the constant to `internal/taskstate/taskstate.go` and place it in\n `Terminal`, `Actions` and `Statuses`. Its value is stored, so renaming it\n later is a migration.\n2. Alias it in `internal/domain/workflow/task/task.go` and\n `internal/domain/workflow/task_aliases.go`.\n3. Add it to the default catalog in `ui/src/lib/task-meta.ts`. The server\n catalog replaces the defaults when it loads, but the defaults render first.\n4. Find every hand-written status list in SQL:\n `grep -rn \"'merged'\" internal/infrastructure/postgres/queries`.\n `ClearTerminalTasks` must match `taskstate.Terminal`, which\n `TestClearTerminalTasksMatchesTaskstate` enforces. The stats queries count\n outcomes by name; decide whether the new status counts.\n5. Extend the table in `taskstate_test.go`.\n\n## Adding a task field\n\nFollow [State Store and persistence](/dev/development/state-store-and-persistence/) for the\ncolumn and the wire. Then decide who writes it: `UpdateTask` writes a fixed\ncolumn set, so a field set at enqueue needs its own statement (as\n`StampTaskBinding` does for binding provenance and inputs).\n\n## Changing what the agent receives\n\n- The task brief is `container.TaskPayload`, written to\n `\u003cworkspace\u003e/.git/task.json` by `WriteTaskJSON`. Never write it to the\n workspace root: the commit stage stages everything there.\n- The run request is `taskrun.Request`. `Validate` rejects a request that\n cannot run; a new requirement goes there.\n- Parking always carries a class (`taskstate.ParkTransient`,\n `ParkNeedsHuman`, `ParkTerminal`) chosen by the code that parks. Pick the one\n that says what an operator must do.\n- A task with no repository (`Task.HasRepository`) runs in a scratch workspace\n with no worktree grant. Code that assumes an owner and repo must check first.\n"
},
{
"url": "/dev/development/workflows-and-steps/",
"title": "Workflows and steps",
"section": "Development",
"body": "# Workflows and steps\n\nAuthority: `docs/architecture/agent-system.md` for the lifecycle,\n`docs/prds/event-automation.md` for inputs, repository modes and profiles.\n\nWorkflow definitions are YAML stored as a control-plane resource. The State\nStore validates them and the agent compiles them, each against the step\nvocabulary it registers, so both must see the same step types.\n\n## Adding a step type\n\n1. Write the factory in `internal/domain/workflow` as a `StepType`. It decodes\n and validates its settings and returns an error for anything it cannot\n honour. The factory runs when a definition is saved and again when it is\n compiled, so a bad definition is refused on save.\n2. Register it through a provider in\n `internal/infrastructure/workflowsteps/workflowsteps.go`. That one list is\n what every process registers, which is how the validating and executing\n sides agree.\n3. An agent-driven step builds on `AgentStage`; do not start a second path to\n the agent runner.\n4. A step that needs no repository goes in `repoFreeStepTypes` in\n `definition.go`, or workflows declaring `repository: none` or `optional`\n cannot use it. A step that needs one may assume `tc.Dir` holds a worktree\n only when the workflow's repository is `required`.\n5. A step that ends the workflow sets `tc.Outcome`. A workflow that runs out of\n steps without an outcome is parked as a definition bug.\n6. Add a parse test (settings accepted and refused) and a run test with fake\n `Trees` and agent runner.\n\n## Changing the definition format\n\n- The fields a caller needs without the engine (inputs, repository, profile)\n live in `task.WorkflowInterface`, because the dashboard process must not\n import the workflow engine (`cmd/archie-ui/architecture_test.go`). Anything a\n binding or the dashboard checks goes there.\n- The YAML decoder rejects unknown keys. Existing stored definitions must keep\n parsing, so a new key is optional with a default that preserves today's\n behaviour.\n- Examples in `examples/workflows/` are parsed against the registered\n vocabulary by `TestExampleWorkflowsParse`. Add one for a new capability.\n"
},
{
"url": "/dev/prds/01-project-management/",
"title": "Architecture Decision Index",
@@ -528,6 +588,48 @@
}
]
},
{
"title": "Development guides",
"url": "/dev/development/",
"items": [
{
"title": "Agent execution and containers",
"url": "/dev/development/agent-execution-and-containers/"
},
{
"title": "Configuration settings",
"url": "/dev/development/config-settings/"
},
{
"title": "Dashboard",
"url": "/dev/development/dashboard/"
},
{
"title": "Event automation",
"url": "/dev/development/event-automation/"
},
{
"title": "Merging work",
"url": "/dev/development/merging-work/"
},
{
"title": "Processes and wiring",
"url": "/dev/development/processes-and-wiring/"
},
{
"title": "State Store and persistence",
"url": "/dev/development/state-store-and-persistence/"
},
{
"title": "Task lifecycle",
"url": "/dev/development/task-lifecycle/"
},
{
"title": "Workflows and steps",
"url": "/dev/development/workflows-and-steps/"
}
]
},
{
"title": "PRDs",
"items": [
+1 -1
View File
@@ -4,7 +4,7 @@
"url": "/docs/",
"title": "Archie",
"section": "",
"body": "# Archie\n\nEvent Driven Agentic Automation.\n\nArchie is an agent platform that reacts to events. A forge issue, a signed\nwebhook from any app you run, a message in a chat channel: each arrives as an\nevent, a playbook decides what a matching event sets off, and the work happens\nin an isolated git worktree. GitHub and Gitea issues were the first case. A\nforge is now one event source among several, and a pull request one outcome\namong several.\n\nNothing about that path is wired to a particular forge, channel, or sender.\nSources, the fields they carry, and the workflows they reach are configuration\nyou add without touching code or restarting anything.\n\n## Start here\n\n- [First playbook](/docs/guides/first-playbook/) points an external app's webhook\n at archie, maps the fields of a real payload, and binds them to a workflow.\n- [Architecture](/dev/architecture/) is the authority for settled design:\n the domain boundaries, the workflow engine, the task lifecycle, and the\n invariants that hold the whole thing together.\n\n## What runs where\n\nA deployment is a set of services, each owning one typed contract. The Gateway\nserves conversation turns and sessions, the Messaging Service runs the\nchannels, the State Store owns the database outright, the dashboard is its own\nprocess, and `archied` admits work and drives each task through its workflow.\ngRPC carries the synchronous calls between them; NATS carries asynchronous\nfan-out. Agents execute in containers that receive a task-scoped credential,\nissued per task and revoked when the worktree is handed back.\n\nConfiguration lives at `${XDG_CONFIG_HOME:-~/.config}/archie/config.toml`.\nNothing in a working tree is load-bearing at runtime.\n\n## A note on these docs\n\nThis site is generated from the `docs/` directory of the\n[archie-core repository](https://github.com/samcharles93/archie-core) on every\nchange to `main`. The repository is the source; this site is a view of it. If\nthe two ever disagree, the repository is right.\n"
"body": "# Archie\n\nEvent Driven Agentic Automation.\n\nArchie is an agent platform that reacts to events. A forge issue, a signed\nwebhook from any app you run, a message in a chat channel: each arrives as an\nevent, a playbook decides what a matching event sets off, and the work happens\nin an isolated git worktree. GitHub and Gitea issues were the first case. A\nforge is now one event source among several, and a pull request one outcome\namong several.\n\nNothing about that path is wired to a particular forge, channel, or sender.\nSources, the fields they carry, and the workflows they reach are configuration\nyou add without touching code or restarting anything.\n\n## Start here\n\n- [First playbook](/docs/guides/first-playbook/) points an external app's webhook\n at archie, maps the fields of a real payload, and binds them to a workflow.\n- [Architecture](/dev/architecture/) is the authority for settled design:\n the domain boundaries, the workflow engine, the task lifecycle, and the\n invariants that hold the whole thing together.\n- [Development guides](/dev/development/) list everything a change of each\n kind must reach: settings, persistence, tasks, workflows, bindings, the\n dashboard, containers and process wiring.\n\n## What runs where\n\nA deployment is a set of services, each owning one typed contract. The Gateway\nserves conversation turns and sessions, the Messaging Service runs the\nchannels, the State Store owns the database outright, the dashboard is its own\nprocess, and `archied` admits work and drives each task through its workflow.\ngRPC carries the synchronous calls between them; NATS carries asynchronous\nfan-out. Agents execute in containers that receive a task-scoped credential,\nissued per task and revoked when the worktree is handed back.\n\nConfiguration lives at `${XDG_CONFIG_HOME:-~/.config}/archie/config.toml`.\nNothing in a working tree is load-bearing at runtime.\n\n## A note on these docs\n\nThis site is generated from the `docs/` directory of the\n[archie-core repository](https://github.com/samcharles93/archie-core) on every\nchange to `main`. The repository is the source; this site is a view of it. If\nthe two ever disagree, the repository is right.\n"
},
{
"url": "/docs/guides/first-playbook/",
@@ -0,0 +1,49 @@
# Agent execution and containers
Authority: `docs/architecture/agent-system.md` (execution boundary, the model
never runs git) and the Deployment Model section of `CLAUDE.md`.
The daemon prepares a workspace, starts one container per task from a profile's
image, and hands the whole task to `archie-agent` over NATS in one
`taskrun.Request`. The agent reaches the State Store, forge and worktree push
only through the daemon's RPC servers, using task-scoped credentials.
## Giving the agent something new
- **Data about the task** goes in `taskrun.Request` or the task brief
(`container.TaskPayload`), never in an environment variable. Add a test that
the request carries it (`TestRunViaAgentSendsMCPServers` is the pattern).
- **A credential** is scoped to the task and revoked when it ends, like the
State Store grant and the worktree publication grant. The daemon's own
administrative token never enters a container.
- **A tool** reaches the agent through the central registry, MCP, a repository
script or a skill plugin. A profile's `tools` list filters those; ai-sdk
agentloop's built-in file tools are outside it. A tool that must stay inside
the workspace uses the agent loop's confinement, not its own path handling.
## Changing the agent image or a profile image
1. The agent image is `Dockerfile`; example profile images live in
`examples/profiles/`, each with a build-only service in
`docker-compose.yml` (`profiles: ["build"]`, so `up -d` never starts it).
2. Anything the agent runs must be in the image. The container gets no
package manager at run time beyond what the image ships.
3. A locally built image needs `containers.pull_policy = "missing"`;
`"always"` tries to pull it and fails.
4. Profiles are configured under `[containers.profiles.<name>]` and resolved
by the daemon before the container starts (`pinTaskProfile`). An unknown
profile parks the task; it never falls back to the default image.
## Changing how a task runs
- Workspace preparation happens in the daemon (`prepareWorkspace`) before the
container starts, because the container binds the directory. Clones need the
daemon's forge credential; the agent never clones.
- A task with no repository gets `worktree.Manager.ScratchDir`, which is
removed when the task ends.
- The agent runs as root in the container. Anything it writes into the
bind-mounted workspace is handed back to the daemon's UID
(`restoreWorktreeOwnership`); a new write path must stay inside that
workspace.
- NATS rules are in `CLAUDE.md`: task responses use `msg.Respond`, a responder
is flushed after it registers, and `ARCHIE_TASKS` is a work queue.
+58
View File
@@ -0,0 +1,58 @@
# Configuration settings
Authority: `docs/architecture/configuration.md`. The wiring matrix, the
decoded-but-unwired ledger and the three shapes an unwired field takes are in
`.agents/skills/archie-config-and-flags`.
A field that parses is not a field that works. Before adding one, name the code
that reads it and the path the value takes to get there.
## Decide what kind of setting it is
- **Bootstrap-only** (read once at process start: `database_url`, `state_dir`,
`work_dir`). It stays in the file, is checked by `validateBootstrap` in
`internal/infrastructure/configuration/validate.go`, and the runtime overlay
refuses changes to it.
- **Database-owned** (repository policies, scheduling, tools, plugins,
channels, containers). The file only seeds it. Once the State Store holds the
control-plane resource, the stored document is layered over the file
(`controlplane.Client.RuntimeConfig`) and the file key stops mattering. It is
checked by `validateDatabaseOwned` and by the resource's validator.
- **Worker-carried.** A value the agent container needs travels in
`config.TaskConfig` (`Config.ForTask`) or on `taskrun.Request`. Never pass it
as an environment variable the daemon did not already define, and never carry
a secret this way.
## Adding a database-owned field
1. Add it to the struct the resource's `Document` names in
`internal/app/controlplane/operational_settings.go`. The resource's JSON
schema and the dashboard's Advanced settings editor are generated from that
type, so no UI work is needed for the editor itself.
2. Stored documents use Go field names as keys (`Image`, `MaxConcurrency`).
Give the field no `json` tag unless its neighbours have one.
3. A map or a nested struct needs its layering checked. `json.Unmarshal`
merges into an existing map, so a stored map would add to the file's rather
than replace it. A field the stored document omits keeps the file's value
(a document stored before the field existed). Add a case to
`internal/app/controlplane/runtime_config_test.go` for both.
4. Validate it in one function both sides call, and add a case to
`TestResourceValidatorsRejectWhatEffectiveValidationRejects` in
`validators_agree_test.go`, so the file and the resource cannot disagree.
5. Decide whether it reloads: it does only if every consumer re-reads it from
`config.Holder`. The allowlist is `internal/app/archied/reload.go`; anything
not on it requires a restart.
6. If the settings page shows it as a plain field, add it to
`internal/webui/config_schema.go` and the view in `api_config.go`.
## Every new field
- Test through the layering: build the effective config the way boot does,
not by setting the field on the consumer.
- Add a commented example to `config.example.toml`. Touch `deployments/*.toml`
only when a profile there needs a value different from the default.
- Update the wiring matrix in `.agents/skills/archie-config-and-flags`.
- Secrets are `SecretRef`s resolved through the secret registry. Never inspect
a resolved value, even in a test.
- Reject a configuration that sets a field with no consumer rather than
accepting and ignoring it (per-identity `forge.intake` is the precedent).
+37
View File
@@ -0,0 +1,37 @@
# Dashboard
Authority: `.agents/skills/archie-web-ui` (stack facts, design-system rules,
tone and accessibility). This page covers what a change must reach, not how it
should look.
## Adding or changing a feature
1. The feature lives in `ui/src/<feature>/`. Move a helper to `ui/src/base/`
only when a second feature needs it.
2. Keep wire shapes, draft state and payload building in a plain `.ts` module
beside the components (`ui/src/bindings/binding-draft.ts` is the pattern),
and test it in `ui/test/*.test.ts`. Components stay thin.
3. Every mutation goes through `api.*` in `ui/src/lib/api`, which sends the
CSRF and Content-Type headers the server's mutation guard requires. A bare
`fetch` is refused.
4. A value the server also describes (task statuses, actions, workflow inputs)
comes from the server. Keep a local default only so the first render works,
and keep it in step (`ui/src/lib/task-meta.ts`).
5. Run `task ui`, `task test:ui` and `cd ui && npm run typecheck`. Commit the
regenerated `ui/dist/`; the Go binaries embed it.
## Adding an API route
1. The handler goes in the `internal/webui/api_<concern>.go` file for its
concern. Check the request fully on the server; the UI's checks are only a
convenience.
2. A mutation calls `authorizeTaskMutation` first.
3. A route whose store is not configured answers 503, and
`internal/app/archieui/degraded_routes_test.go` pins what each route
returns without its contract. Add the route there.
4. The dashboard runs in its own process (`archie-ui`) and must not link the
daemon or the workflow engine (`cmd/archie-ui/architecture_test.go`). Reach
stored data through `storecontract` interfaces wired in
`internal/app/archieui/compose.go`.
5. Settings that live in a control-plane resource need no new route: the
Advanced settings page edits every resource from its generated schema.
+44
View File
@@ -0,0 +1,44 @@
# Event automation
Authority: `docs/prds/event-automation.md` (the model: source, event type,
mapping, binding, workflow, profile) and `docs/architecture/bindings.md`
(threat model).
## Where each check lives
A binding is checked twice, and a new rule usually belongs in both places:
- **On save**, in `checkedBinding` (`internal/webui/api_binding.go`), so the
operator sees the problem while editing. It calls the domain checks
`binding.Validate`, `binding.CompileFilter` and `Binding.CheckWorkflow`.
- **At dispatch**, in `dispatchOneBinding` and `resolveBindingTarget`
(`internal/daemon`), because the workflow or mapping may have changed since
the save. A refusal is recorded with `recordDispatchFailure` and starts no
task.
Put the rule itself in `internal/domain/binding` or
`internal/domain/workflow/task` and call it from both, rather than writing it
twice.
## Adding a binding field
1. Domain type and `Validate` in `internal/domain/binding`.
2. Column, queries, store mapping, wire field, `newColumns`
([State Store and persistence](state-store-and-persistence.md)).
3. The request type and `checkedBinding` in `api_binding.go`.
4. The draft, payload and editor in `ui/src/bindings/`
([Dashboard](dashboard.md)).
5. Its effect at dispatch, with a case in
`internal/daemon/dispatch_inputs_test.go` or `dispatch_bindings_test.go`.
## Rules that must hold
- Signing belongs to the source. Intake verifies the HMAC against the source's
secret before the payload is parsed.
- An event must be identified as an event type before anything dispatches it,
and a binding applies only to its mapping's event type. Dispatch test
fixtures therefore create an event type before inserting captures.
- The dispatch ledger is claimed before the task is enqueued (at most once).
- Anything an event supplies that selects what the agent acts on, such as a
repository, must be checked against configuration. An event never widens
what an agent can reach.
+42
View File
@@ -0,0 +1,42 @@
# Development guides
Checklists for changing Archie. Each page covers one kind of change and names
every place that change must reach, so a feature that works in one layer does
not silently stop at the next. The pages point at the documents that own the
design (`docs/architecture/`, the PRDs, `CLAUDE.md`) rather than restating
them.
| Changing | Guide |
| --- | --- |
| A setting in `config.toml` or the dashboard | [Configuration settings](config-settings.md) |
| A stored field, table, RPC or error | [State Store and persistence](state-store-and-persistence.md) |
| Task statuses, fields or the task brief | [Task lifecycle](task-lifecycle.md) |
| Workflow definitions or step types | [Workflows and steps](workflows-and-steps.md) |
| Sources, event types, mappings or bindings | [Event automation](event-automation.md) |
| Anything under `ui/` | [Dashboard](dashboard.md) |
| The agent container, its image or its tools | [Agent execution and containers](agent-execution-and-containers.md) |
| A process, plugin engine, channel or NATS subject | [Processes and wiring](processes-and-wiring.md) |
| Merging a lane or a branch | [Merging work](merging-work.md) |
## Every change
- Write the failing test first for anything with logic, branching or a
contract, and check it fails on an assertion, not a compile error.
- Test through the path production uses. A test that sets a value directly on
the consumer proves nothing about the layers that normally deliver it.
- Run `task check` and let its exit status decide the commit:
`task check && git commit ...`. `task test` passes `-short`, which skips the
process and Postgres tests, so run `go test -count=1 ./cmd/... ./internal/...`
too when a change crosses a process or the database.
- Regenerate, never hand-edit, generated output: `task proto:generate`,
`go -C tools tool sqlc generate -f $PWD/internal/infrastructure/postgres/sqlc.yaml`,
`task ui`, `task docs:artifact`. `task proto:check` compares against the git
index, so stage regenerated contracts before running it.
- Stage by path, or read `git status` before `git add -A`. Tests that start
embedded NATS or write logs must use `t.TempDir()`; anything they leave in the
tree gets committed. `task check` also adds linter-tool lines to `go.sum`
(bead 1e37); restore `go.sum` before committing unless you changed a
dependency.
- A change to `docs/prds/` or `docs/architecture/` carries the regenerated
`docs/data/generated/dev-docs.json`, and PRD edits follow
`docs/prds/RULES.md` and pass `task docs:prds`.
+29
View File
@@ -0,0 +1,29 @@
# Merging work
Parallel lanes (see `.agents/skills/archie-agent-fleet`) merge into an
integration branch before `main`. Each merge is a change in its own right and
passes the same gate.
## Resolving conflicts
- **Generated files** (`*.pb.go`, `postgresdb/*.go`, `ui/dist/`,
`docs/data/generated/*.json`): take either side, then regenerate. Never merge
them by hand.
- **One side deletes a file, the other edits it**: the deletion wins when the
deleting lane replaced the thing the file served. Move the other side's
change onto its replacement.
- **One side changes how code is built (a new store, renamed packages), the
other what it does**: take the behaviour side's version and reapply the
mechanical change to it. That is usually cleaner than merging line by line.
- **Error sentinels** are rows in `wireErrors`, not switch cases.
## After resolving
1. Search for leftovers of anything the other side removed: the old package
path, the old type, and comments describing the old behaviour.
2. Tests written against one side's semantics may pass there and fail after
the merge. A test that used to pass on the old store may be asserting a rule
the other side deliberately changed. Fix the test's setup to the merged
rule; do not loosen the rule to the test.
3. Run the full suite without `-short`, then `task check`, then commit. Check
`git status` for files a test wrote into the tree before staging.
+48
View File
@@ -0,0 +1,48 @@
# Processes and wiring
Authority: `docs/architecture/organisation.md` (layers, process boundaries),
`docs/architecture/dependencies-and-contracts.md` (dependency direction, wire
contracts) and `docs/architecture/plugins-and-extensions.md` (the plugin engine
rule).
## Placing new code
- Domain logic, entities and the interfaces it needs go in
`internal/domain/<area>/`, which imports no infrastructure or app package.
- Implementations of those interfaces go in `internal/infrastructure/<service>/`.
- Construction and wiring go in `internal/app/<application>/`; `cmd/` only
parses flags and calls it.
- `logging`, `events`, `eventbus`, `policy` and `taskstate` import no internal
package. There is no `shared/`, `utils/` or `common/` package.
- A behaviour has one authoritative path. Before adding a second way to do
something, remove or redirect the first.
## Adding a capability to a process
1. Decide which process owns it. A new binary is justified only when the
surface must fail, scale or run somewhere independently.
2. Wire it at that process's composition root. An optional capability
degrades: a missing provider logs a warning and marks health degraded
rather than stopping the process (MCP providers are the model).
3. Every process that reaches the capability through the State Store gets it
through a `storecontract` interface asserted on the client
([State Store and persistence](state-store-and-persistence.md)).
4. The architecture tests (`cmd/archie-ui/architecture_test.go`,
`cmd/archie-messaging/architecture_test.go`, `TestOpenStoresNeverOwnsTaskDB`)
pin what each binary may link. A failure there means the placement is wrong,
not the test.
## Adding a plugin engine
Satisfy every invariant in "Plugin engine rule (strict)" in
`plugins-and-extensions.md`: typed domain contract, an owning manager,
lifecycle and health, narrow host access, and an explicit trust boundary.
`internal/plugin/architecture_test.go` checks the parts that can be checked.
## Adding a channel or a NATS subject
- Channel rules (Telegram's pending-update drop, command scopes) are in
`CLAUDE.md` under Per-Package Invariants.
- A subject is part of the wire contract. Its payload type belongs to the
domain that defines its meaning, and the transport code lives in
infrastructure.
@@ -0,0 +1,57 @@
# State Store and persistence
Authority: `docs/prds/state-store-contract.md` and the State Store section of
`CLAUDE.md`. All persistence is PostgreSQL behind the standalone State Store
process; nothing else opens the database.
## Adding a column
1. Write the next migration in `internal/infrastructure/postgres/migrations/`
(`00NN_name.sql`, goose Up and Down). Give the column a `NOT NULL DEFAULT`
that is correct for existing rows.
2. Update the queries in `internal/infrastructure/postgres/queries/` and
regenerate with sqlc. A query that lists columns (`ListTaskSummaries`, the
binding selects) does not pick the new one up; `SELECT *` queries do.
3. Map it in the store (`taskFromRow`, `bindingValue` and friends). If the
column holds encoded data, the package that owns the type owns the encoding
(`task.EncodeInputs`), and the store and the wire both use it.
4. Add the column to `newColumns` in
`internal/infrastructure/legacyimport/load.go` if legacy data has no value
for it. The importer refuses a target column it cannot fill otherwise.
5. Carry it over the wire (next section) if any process other than the State
Store reads it.
## Adding a field to a wire message
1. Add it to `proto/state/v1/state.proto` with a new field number. Never reuse
a number; retire one with `deprecated = true`.
2. `task proto:generate`, then map it both ways in
`internal/infrastructure/staterpc/values.go`.
3. `TestTaskProtoCarriesEveryDomainField` fills every `task.Task` field and
fails on one the mapping forgets. If it cannot fill the field's kind, extend
it. Other messages have no such test, so add a round trip to
`conformance_test.go`.
## Adding an RPC or a store method
1. Put the Go method on the narrow consumer interface in
`internal/domain/storecontract` (keep each at eight methods or fewer) and add
the matching RPC. A Go method without an RPC does not cross the process.
2. Implement it in the Postgres store, in `staterpc.Client` (with its `var _`
assertion) and in `staterpc.server`. A missing dependency answers
`codes.Unavailable`, never a fabricated default.
3. Wire the dependency in every composition that serves or consumes it:
`stateStoreDeps` in `internal/app/archied/state_store.go`, the daemon's
assertions in `bootstrap.go`, and `internal/app/archieui/compose.go` for the
dashboard process.
4. Task-scoped tokens may call only `Update`, `Transition` and `InsertEvent` on
their own task (`staterpc.TaskGrants`). A new RPC is admin-only unless it is
added there deliberately.
5. Add it to `conformance_test.go`, which runs every surface over a real gRPC
connection.
## Adding an error sentinel
Add the sentinel to `storecontract`, a row to `wireErrors` in `values.go`, and
a case to `error_test.go`. The canonical message is part of the wire contract:
changing it breaks `errors.Is` on the client silently.
+40
View File
@@ -0,0 +1,40 @@
# Task lifecycle
Authority: `docs/architecture/agent-system.md`. The status vocabulary lives in
`internal/taskstate`, which imports no internal package.
## Adding a status
1. Add the constant to `internal/taskstate/taskstate.go` and place it in
`Terminal`, `Actions` and `Statuses`. Its value is stored, so renaming it
later is a migration.
2. Alias it in `internal/domain/workflow/task/task.go` and
`internal/domain/workflow/task_aliases.go`.
3. Add it to the default catalog in `ui/src/lib/task-meta.ts`. The server
catalog replaces the defaults when it loads, but the defaults render first.
4. Find every hand-written status list in SQL:
`grep -rn "'merged'" internal/infrastructure/postgres/queries`.
`ClearTerminalTasks` must match `taskstate.Terminal`, which
`TestClearTerminalTasksMatchesTaskstate` enforces. The stats queries count
outcomes by name; decide whether the new status counts.
5. Extend the table in `taskstate_test.go`.
## Adding a task field
Follow [State Store and persistence](state-store-and-persistence.md) for the
column and the wire. Then decide who writes it: `UpdateTask` writes a fixed
column set, so a field set at enqueue needs its own statement (as
`StampTaskBinding` does for binding provenance and inputs).
## Changing what the agent receives
- The task brief is `container.TaskPayload`, written to
`<workspace>/.git/task.json` by `WriteTaskJSON`. Never write it to the
workspace root: the commit stage stages everything there.
- The run request is `taskrun.Request`. `Validate` rejects a request that
cannot run; a new requirement goes there.
- Parking always carries a class (`taskstate.ParkTransient`,
`ParkNeedsHuman`, `ParkTerminal`) chosen by the code that parks. Pick the one
that says what an operator must do.
- A task with no repository (`Task.HasRepository`) runs in a scratch workspace
with no worktree grant. Code that assumes an owner and repo must check first.
+41
View File
@@ -0,0 +1,41 @@
# Workflows and steps
Authority: `docs/architecture/agent-system.md` for the lifecycle,
`docs/prds/event-automation.md` for inputs, repository modes and profiles.
Workflow definitions are YAML stored as a control-plane resource. The State
Store validates them and the agent compiles them, each against the step
vocabulary it registers, so both must see the same step types.
## Adding a step type
1. Write the factory in `internal/domain/workflow` as a `StepType`. It decodes
and validates its settings and returns an error for anything it cannot
honour. The factory runs when a definition is saved and again when it is
compiled, so a bad definition is refused on save.
2. Register it through a provider in
`internal/infrastructure/workflowsteps/workflowsteps.go`. That one list is
what every process registers, which is how the validating and executing
sides agree.
3. An agent-driven step builds on `AgentStage`; do not start a second path to
the agent runner.
4. A step that needs no repository goes in `repoFreeStepTypes` in
`definition.go`, or workflows declaring `repository: none` or `optional`
cannot use it. A step that needs one may assume `tc.Dir` holds a worktree
only when the workflow's repository is `required`.
5. A step that ends the workflow sets `tc.Outcome`. A workflow that runs out of
steps without an outcome is parked as a definition bug.
6. Add a parse test (settings accepted and refused) and a run test with fake
`Trees` and agent runner.
## Changing the definition format
- The fields a caller needs without the engine (inputs, repository, profile)
live in `task.WorkflowInterface`, because the dashboard process must not
import the workflow engine (`cmd/archie-ui/architecture_test.go`). Anything a
binding or the dashboard checks goes there.
- The YAML decoder rejects unknown keys. Existing stored definitions must keep
parsing, so a new key is optional with a default that preserves today's
behaviour.
- Examples in `examples/workflows/` are parsed against the registered
vocabulary by `TestExampleWorkflowsParse`. Add one for a new capability.
+3
View File
@@ -20,6 +20,9 @@ you add without touching code or restarting anything.
- [Architecture](architecture/index.md) is the authority for settled design:
the domain boundaries, the workflow engine, the task lifecycle, and the
invariants that hold the whole thing together.
- [Development guides](development/index.md) list everything a change of each
kind must reach: settings, persistence, tasks, workflows, bindings, the
dashboard, containers and process wiring.
## What runs where
@@ -111,6 +111,17 @@ func TestResourceValidatorsRejectWhatEffectiveValidationRejects(t *testing.T) {
mutate: func(cfg *config.Config) {},
wantErr: false,
},
{
name: "container profile with an empty tool name",
kind: ContainerRuntimePoliciesKind,
value: config.ContainerConfig{Image: "archie-agent:test", Profiles: map[string]config.AgentProfile{
"net": {Tools: []string{""}},
}},
mutate: func(cfg *config.Config) {
cfg.Containers.Profiles = map[string]config.AgentProfile{"net": {Tools: []string{""}}}
},
wantErr: true,
},
{
name: "container runtime policies without an image",
kind: ContainerRuntimePoliciesKind,
+3 -2
View File
@@ -155,7 +155,8 @@ type navNode struct {
// may be read by anyone. architecture/ and prds/ are written for contributors --
// the organisation rules, the migration register, the review procedure, the open
// design decisions -- and a reader looking for what Archie is and how to point an
// event at it is not served by meeting them in one sidebar. They are the
// event at it is not served by meeting them in one sidebar. development/ holds
// the checklists for changing Archie, written for the same readers. They are the
// development set. Everything else is the public set.
//
// Selective PRD publication is gone with the split rather than carried into it: it
@@ -169,7 +170,7 @@ type navNode struct {
var (
heldBackTrees = map[string]bool{"archive": true, "inspiration": true, "news": true}
heldBackPages = map[string]bool{"github-token.md": true}
developmentTree = map[string]bool{"architecture": true, "prds": true}
developmentTree = map[string]bool{"architecture": true, "prds": true, "development": true}
)
// setFor is the set one published page belongs to, by its top-level directory.
+1
View File
@@ -48,6 +48,7 @@ func TestTheSplitIsByAudience(t *testing.T) {
for _, want := range []string{
"/dev/architecture/",
"/dev/architecture/organisation/",
"/dev/development/",
"/dev/prds/ui-service-boundary/",
// Selective PRD publication is gone: an open PRD is a development page like
// any other, which is what removes the pressure that published five of them