# Work-record flavor and residual default-exclusion

Status: active (STATE-WP-0092)  
Canon: `the-custodian/canon/standards/work-record-types_v0.1.md` § Flavor

## Rule

Workplans and tasks carry an optional **flavor** bucket:

`planning` | `implementation` | `refactoring` | `extension` | `residual`

Flavor is not a kind and not a status. Unset flavor is **not** residual.

`flavor: residual` means leftover work that is **not** as valuable as the
main functional and non-functional requirements. Default State Hub views of
open work **omit** residuals. Agents must not pick residual workplans or
residual tasks for implementation unless the flavor has been promoted.

Promotion is a file edit:

```yaml
flavor: implementation          # or planning | refactoring | extension
flavor_promoted_from: residual
flavor_promotion_reason: demand # or risk
```

Then `statehub fix-consistency`. After promotion the record re-enters the
default view.

`origin: residual` on intakes remains provenance. It does not hide a
workplan; `flavor` does.

## `depends_on`

Workplan frontmatter `depends_on` is the canonical list of blocker
**workplan ids**. C-20 indexes it (legacy alias: `depends_on_workplans`).
Do not use `depends_on_workplans` on new files.

## API

| Surface | Default | Residual access |
| --- | --- | --- |
| `GET /workplans/` | includes residuals (full index) | `?flavor=residual` or `?include_residuals=false` to hide |
| `GET /state/summary` `open_workplans` | omits residuals | `?include_residuals=true` fills `residual_open_workplans`; `totals.workstreams.residual_open` is always the count |
| `GET /state/next_steps` | never recommends residual work | — |
| `GET /state/deps` | omits residuals | `?include_residuals=true` |

Unknown flavor values fail closed on write (HTTP 422). Consistency check
C-36 warns; it does not invent a flavor for historic files.

## Fleet follow-on

- Backfill existing files: `CUST-WP-0072`
- Fabric graph: `RAIL-FAB-WP-0030`
- Cross-owner waits: `COORDINATION-WP-0005`

Do not message `ops-warden` for secrets; see credential routing.