# Constants — No Magic Strings

All cross-cutting status / type / condition values are defined in [`engine/shared.js`](../engine/shared.js). Engine and dashboard code **never** compares against raw strings; tests enforce.

```js
WI_STATUS = { PENDING, DISPATCHED, DONE, FAILED, PAUSED, QUEUED, DECOMPOSED, CANCELLED }
DONE_STATUSES = Set([WI_STATUS.DONE, 'in-pr', 'implemented', 'complete'])  // legacy aliases on read only
WORK_TYPE = { IMPLEMENT, IMPLEMENT_LARGE, FIX, REVIEW, VERIFY, PLAN, PLAN_TO_PRD,
              DECOMPOSE, MEETING, EXPLORE, ASK, TEST, DOCS, SETUP }
PLAN_STATUS = { ACTIVE, AWAITING_APPROVAL, APPROVED, PAUSED, REJECTED, COMPLETED, REVISION_REQUESTED }
PRD_ITEM_STATUS = { MISSING, UPDATED, DONE };  PRD_MATERIALIZABLE = Set([MISSING, UPDATED])
PR_STATUS = { ACTIVE, MERGED, ABANDONED, CLOSED, LINKED };  PR_POLLABLE_STATUSES = Set([ACTIVE, LINKED])
DISPATCH_RESULT = { SUCCESS, ERROR, TIMEOUT }
WATCH_STATUS = { ACTIVE, PAUSED, TRIGGERED, EXPIRED }
WATCH_CONDITION = { MERGED, BUILD_FAIL, BUILD_PASS, COMPLETED, FAILED, STATUS_CHANGE, ANY, NEW_COMMENTS,
  VOTE_CHANGE, CONCLUDED, APPROVED, REJECTED, STAGE_COMPLETE, RAN, ENABLED, DISABLED, ACTIVITY_CHANGE,
  HEAD_COMMIT_CHANGE, MERGEABLE_FLIPPED, READY_FOR_MERGE, BEHIND_MASTER, DRAFT_FLIPPED,
  STALLED, RETRY_LIMIT_REACHED, DEPENDENCY_MET, ALL_ITEMS_DONE, ITEM_FAILED_N_TIMES,
  STAGE_ADVANCED, STUCK_IN_STAGE }
WATCH_ABSOLUTE_CONDITIONS = Set([MERGED, BUILD_FAIL, BUILD_PASS, COMPLETED, FAILED, CONCLUDED, APPROVED,
  REJECTED, READY_FOR_MERGE, RETRY_LIMIT_REACHED, ALL_ITEMS_DONE, ITEM_FAILED_N_TIMES])  // fire-once
```

## Engine defaults

Retry/timeout limits, sweep cadences, fleet ceilings, and managed-spawn caps live in `ENGINE_DEFAULTS` (also in `engine/shared.js`). Read defaults from there rather than re-declaring; per-deployment overrides go in `config.engine.*` and resolve through the per-knob helpers (`resolveAgentMaxBudget`, etc.).

## Invariants

- **Write only `WI_STATUS.DONE`.** Legacy aliases (`in-pr`, `implemented`, `complete`) are accepted on read for backward compat but never written. `updateWorkItemStatus()` validates writes against `WI_STATUS`.
- **`mutateJsonFileLocked` for RMW.** All shared-JSON status writes go through the locked mutator wrappers (`mutateDispatch`, `mutateWorkItems`, `mutatePullRequests`) — see [`CLAUDE.md`](../CLAUDE.md) → **Concurrency**.
- **No string comparisons.** `pr.status === 'active'` ⇒ `pr.status === PR_STATUS.ACTIVE`. Source-inspection tests grep for the constant form.
