From 2f59b6ad8ed4565f8d0ef46b264ff5d3be082f22 Mon Sep 17 00:00:00 2001 From: Alex Kotliarskyi Date: Tue, 10 Mar 2026 11:18:35 -0700 Subject: [PATCH] docs(spec): align workflow config docs with schema Summary: - document tracker active and terminal states as YAML string lists - remove trim-based state normalization language from the spec - update the config cheat sheet defaults to match list-based examples Rationale: - the schema now accepts tracker state lists rather than comma-separated strings, so the spec should not promise the older form - the state normalization contract should match the less-defensive behavior the user wants documented Tests: - make -C elixir all Co-authored-by: Codex --- SPEC.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/SPEC.md b/SPEC.md index 47d6abe7..e861f3b9 100644 --- a/SPEC.md +++ b/SPEC.md @@ -273,7 +273,7 @@ Fields: - Derive from `issue.identifier` by replacing any character not in `[A-Za-z0-9._-]` with `_`. - Use the sanitized value for the workspace directory name. - `Normalized Issue State` - - Compare states after `trim` + `lowercase`. + - Compare states after `lowercase`. - `Session ID` - Compose from coding-agent `thread_id` and `turn_id` as `-`. @@ -351,9 +351,9 @@ Fields: - If `$VAR_NAME` resolves to an empty string, treat the key as missing. - `project_slug` (string) - Required for dispatch when `tracker.kind == "linear"`. -- `active_states` (list of strings or comma-separated string) +- `active_states` (list of strings) - Default: `Todo`, `In Progress` -- `terminal_states` (list of strings or comma-separated string) +- `terminal_states` (list of strings) - Default: `Closed`, `Cancelled`, `Canceled`, `Duplicate`, `Done` #### 5.3.2 `polling` (object) @@ -410,7 +410,7 @@ Fields: - Changes should be re-applied at runtime and affect future retry scheduling. - `max_concurrent_agents_by_state` (map `state_name -> positive integer`) - Default: empty map. - - State keys are normalized (`trim` + `lowercase`) for lookup. + - State keys are normalized (`lowercase`) for lookup. - Invalid entries (non-positive or non-numeric) are ignored. #### 5.3.6 `codex` (object) @@ -555,8 +555,8 @@ This section is intentionally redundant so a coding agent can implement the conf - `tracker.endpoint`: string, default `https://api.linear.app/graphql` when `tracker.kind=linear` - `tracker.api_key`: string or `$VAR`, canonical env `LINEAR_API_KEY` when `tracker.kind=linear` - `tracker.project_slug`: string, required when `tracker.kind=linear` -- `tracker.active_states`: list/string, default `Todo, In Progress` -- `tracker.terminal_states`: list/string, default `Closed, Cancelled, Canceled, Duplicate, Done` +- `tracker.active_states`: list of strings, default `["Todo", "In Progress"]` +- `tracker.terminal_states`: list of strings, default `["Closed", "Cancelled", "Canceled", "Duplicate", "Done"]` - `polling.interval_ms`: integer, default `30000` - `workspace.root`: path, default `/symphony_workspaces` - `hooks.after_create`: shell script or null