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

id	type	title	domain	repo	status	owner	topic_slug	flavor	created	updated	related	origin	origin_ref	state_hub_workstream_id
STATE-WP-0092	workplan	Workplan flavor, depends_on indexing, and residual default-exclusion	infotech	state-hub	finished	grok	infotech	planning	2026-09-14	2026-09-14	CUST-WP-0072 RAIL-FAB-WP-0030 COORDINATION-WP-0005 CUST-WP-0060	residual-policy	the-custodian/history/20260914-open-workplan-chokepoints.md	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

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

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

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

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

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.