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

+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.