state-hub/workplans/STATE-WP-0092-workplan-flavor-and-depends-on-policy.md

---
id: STATE-WP-0092
type: workplan
title: "Workplan flavor, depends_on indexing, and residual default-exclusion"
domain: infotech
repo: state-hub
status: finished
owner: grok
topic_slug: infotech
flavor: planning
created: "2026-09-14"
updated: "2026-09-14"
related:
  - CUST-WP-0072
  - RAIL-FAB-WP-0030
  - COORDINATION-WP-0005
  - CUST-WP-0060
origin: residual-policy
origin_ref: the-custodian/history/20260914-open-workplan-chokepoints.md
state_hub_workstream_id: "2a2d8bcd-4a34-537b-b72e-f093d46f6cb4"
---

# Workplan flavor, depends_on indexing, and residual default-exclusion

Founder direction 2026-09-14 (assessment
`the-custodian/history/20260914-open-workplan-chokepoints.md`): the open
workplan count will not fall by agent closure alone. First change the
schema and policy so residuals are a **flavor**, not equal open demand,
and so `depends_on` in workplan frontmatter is actually indexed.

This is workplan 1 of 3 for that change. Canon lands in `the-custodian`;
the hub remains a read model (ADR-001). Do not register workplans by
hand. Do not treat `flavor: residual` as a new work-record **kind**.

## Policy to encode

Flavor is a bucket on workplans **and** tasks, orthogonal to kind:

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

Residuals are leftovers that are **not deemed as valuable** as the main
functional and non-functional requirements. Default State Hub views of
open workplans, `/state/summary` `open_workplans`, `/state/next_steps`,
and agent “should we implement this?” **exclude** `flavor: residual`
unless an explicit include flag is set.

Demand or risk **promotes** a residual into another flavor. After
promotion it is no longer residual and it re-enters the default view.
`origin: residual` on intakes may remain as provenance; flavor is the
live classification.

`depends_on` in workplan frontmatter is the canonical edge (list of
workplan ids). C-20 today looks at `depends_on_workplans` /
`depends_on_tasks`, which the fleet does not author. Unify on
`depends_on`. Keep the old keys as aliases until a legacy-meter says
otherwise.

`flavor:` on this file is advisory until T01–T02 land; do not fail
parsing unknown frontmatter keys.

## Ratify flavor and depends_on in custodian canon

```task
id: STATE-WP-0092-T01
status: done
priority: high
state_hub_task_id: "c5c967ec-6f4c-541e-957d-7ae9489fbf6d"
```

In `the-custodian`, extend `canon/standards/work-record-types_v0.1.md`
(and the YAML machine copy / spine schema) so flavor is a closed list on
workplan and task, residual stays a flavor rather than a kind, and
promotion (residual → planning|implementation|refactoring|extension) is
a first-class transition with a recorded reason (`demand` or `risk`).

State the default-view rule: open-workplan lists and implementation
triage omit residuals. Update the workplan-terminology standard and the
workplan convention so frontmatter `depends_on` and `flavor` are
documented. Founder ratification is required for the canon change
(yellow/red lane). Do not silently rewrite `origin: residual` semantics
on intakes.

Done when the canon files are merged, the closed flavor list is
machine-checkable, and the residual section no longer implies that every
live leftover is equal open demand.

## Index flavor and depends_on from files

```task
id: STATE-WP-0092-T02
status: done
priority: high
depends_on: [STATE-WP-0092-T01]
state_hub_task_id: "63d9c134-0b2b-592b-a7df-a58eaa3fdc99"
```

Parse workplan (and task-block) `flavor` and workplan-frontmatter
`depends_on`. Persist them on the hub read model. Expose them on
`GET /workplans/`, `GET /workplans/{id}`, `GET /state/summary`
`open_workplans[]`, and the dependencies endpoint. Accept
`depends_on_workplans` as an alias on read. C-20 creates missing
dependency edges from `depends_on`. Unknown flavor fails closed after
canon lands; before that, warn.

Done when a fixture workplan with `flavor: residual` and
`depends_on: [STATE-WP-0091]` round-trips into the DB and the summary,
and C-20 no longer requires the unused `depends_on_workplans` spelling.

## Default views omit residuals

```task
id: STATE-WP-0092-T03
status: done
priority: high
depends_on: [STATE-WP-0092-T02]
state_hub_task_id: "0d53713b-d6f0-597d-8f87-9f86e5ca2235"
```

`/state/summary` `open_workplans`, `/state/next_steps`, dashboard
open-workplan widgets, and any “implement next” ranking **exclude**
`flavor: residual` by default. Add an explicit query flag
(`include_residuals=true` or `flavor=` filter) for the residual list
the fleet already wanted (`statehub residuals` in the canon). Totals
must still be honest: show residual counts as a separate figure so the
headline cannot hide them, but do not mix them into actionable open
work.

Unspecified flavor is **not** residual; treat it as relevant until
backfill (`CUST-WP-0072`) classifies it. Do not auto-classify.

Done when a residual workplan is absent from the default summary list,
present when included, and next_steps does not recommend implementing
it.

## Policy for agents and operators

```task
id: STATE-WP-0092-T04
status: done
priority: medium
depends_on: [STATE-WP-0092-T03]
state_hub_task_id: "764a4b17-5119-572a-8aa1-581d719f07fa"
```

Document the rule in state-hub agent/API docs: do not pick up residual
workplans or residual tasks for implementation unless the flavor has
been promoted. Promotion is a file edit (`flavor:` + short reason), then
`fix-consistency`. Hub docs point at `CUST-WP-0072` for fleet backfill
and `COORDINATION-WP-0005` for cross-owner waits. No secret-vending
language.

Done when the documented default matches T03 behaviour and a short
agent snippet exists for later instruction rollout.

## Tests and consistency checks

```task
id: STATE-WP-0092-T05
status: done
priority: high
depends_on: [STATE-WP-0092-T02, STATE-WP-0092-T03]
state_hub_task_id: "ab74d06b-acc4-52da-ac20-ac564ca8a7ed"
```

API tests for default exclusion, include flag, flavor filter, and
`depends_on` round-trip. Consistency checks: unknown flavor; residual
without `origin`/`origin_ref` when spawned from a finished parent
(warn, do not invent); `depends_on` target missing (existing C-20).
Do not add a check that forces every historic workplan to declare
flavor — that is `CUST-WP-0072`.

Done when the new tests are green and `fix-consistency` on this repo
does not warn on this file’s advisory `flavor:` / `depends_on` keys.

2026-09-14: T01–T05 landed in repo. Canon v0.2 flavor list is machine-checkable.
Hub indexes `flavor` / `depends_on`, default summary/next_steps/deps omit
`flavor: residual`, and C-20 accepts `depends_on`. Live primary views change
after alembic `c6f7a8b9d0e1` is applied and this revision is deployed. Until
then CUST-WP-0072 should wait.