Index workplan flavor and omit residuals from default views.

STATE-WP-0092: persist flavor from files, treat depends_on as the C-20
canonical edge, exclude flavor=residual from summary/next_steps/deps
unless include_residuals is set. Live primary still needs the alembic
revision applied.

Assistant: grok
Assistant-Session: 01a09dc1-b21e-77e1-919e-fcad2f82b267

docs/work-record-flavor.md

@@ -0,0 +1,57 @@
+# 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.