state-hub/workplans/STATE-WP-0076-definition-of-ready-and-comprehension.md

id	type	title	domain	repo	status	owner	topic_slug	created	updated	reviewed_at	reviewed_by	reviewed_against_commit	context_paths	state_hub_workstream_id
STATE-WP-0076	workplan	Definition of Ready (DoR) and Definition of Comprehension (DoC) quality gates	infotech	state-hub	ready	grok	infotech	2026-07-22	2026-07-22	2026-07-22	grok	HEAD	policies/ dashboard/src/docs/work-records.md dashboard/src/docs/intakes.md dashboard/src/docs/workstream-lifecycle.md dashboard/src/policy/ docs/work-record-quality-gates.md workplans/STATE-WP-0076-definition-of-ready-and-comprehension.md	72d64a42-bb87-4842-839d-3d4ed783ff2d

STATE-WP-0076 — DoR and DoC quality gates

Goal

Ship the next slice of the work-record quality model that pays off soon:

1. Policies in the existing DoI / DoM / DoD family: DoC (intake) and DoR (task + workplan sections).
2. Dashboard edit/view surfaces like the other policies.
3. Docs that fix terminology: work-record as generic coordination artefact (units and structure), lifecycle ≠ definition assessment, badge spelling DoX-Ok / DoX-Failed / unassessed.

No badge engine, no hard API blocks, no new kinds, no value-chain typing.

Where we are (context)

Already true	Gap this plan closes
Work-record kinds + spine (canon)	DoC/DoR not written as hub policies
Intake = discovery; promote → delivery	No transparent “comprehended enough?” checklist
Workplan ready / finished lifecycle	No separate DoR/DoD assessment language; status ≠ quality
DoI, DoM, DoD as policies/*.md + UI	DoC/DoR missing from that family
Reference docs for kinds/lifecycle	Need unit-vs-structure + quality-vs-state framing

Prior session also left doc updates for suggestions→intake and work-records pages; this plan assumes those land or already landed in the same branch.

Non-goals

• Freeform badge product or badge persistence API
• Soft/hard enforcement hooks (convention only until policies are used)
• Renaming kinds (intake→find, task→item)
• DiscoveryMap / mon-pro-sal / enforced exp→…→evo chains
• Contribution retirement
• Full DoD rewrite (link only; optional one-line title note)

Design constraints (fixed for this plan)

1. Lifecycle state ≠ definition badge.
   status=finished may lack DoD-Ok; status=ready may lack DoR-Ok. That is intentional (fluid progress + quality metrics later).

2. Badge family is closed and named after policies.
   Outcomes: unassessed | DoC-Ok / DoR-Ok / DoD-Ok | DoC-Failed / DoR-Failed / DoD-Failed. Tiered policies (DoI/DoM) may use DoM-Ok-1 etc. Assessment is manual/convention in this plan; storage can be prose or frontmatter later.

3. Policies declare applies_to kinds and may have per-kind sections (e.g. DoR for task vs workplan). Workplan is a structure record; task is a unit work-item — do not call workplans “work-items” in policy text.

4. DoC applies only to intake. It justifies treating discovery as understood enough to route/promote — not implementation design.

5. DoR applies to task and workplan. It justifies implementation-readiness. Workplan lifecycle ready remains a process claim; DoR is the checklist behind a DoR-Ok assessment.

6. Outside-originated = extra sections in DoC/DoR (origin/boundary fields), not a new kind.

7. Enforcement = convention + docs. No promote-intake/API blocking in this plan.

---

Task: Quality model + work-record roles in docs

id: STATE-WP-0076-T01
status: todo
priority: high
state_hub_task_id: "53aac055-97a7-405b-bb9b-48427de4296a"

Short design/reference write-up only (no product build):

• Update dashboard/src/docs/work-records.md: work-record as generic mode for units and structure (plans/collections); unit vs structure table; quality badges vs lifecycle; link to policies when they exist.
• Add docs/work-record-quality-gates.md: Definition family (DoI/DoM/DoC/DoR/DoD), badge spelling, applies_to matrix, outside profile pointer, explicit non-goals.
• One cross-link from intakes + workplan lifecycle docs.

Done when: an agent can explain unit vs structure and DoR-Ok vs status=ready from the docs alone.

---

Task: Author DoC policy

id: STATE-WP-0076-T02
status: todo
priority: high
state_hub_task_id: "2498bd9f-e773-4dad-a2e3-9c32b5585d73"

Create policies/intake-doc.md (Definition of Comprehension).

• applies_to: intake
• Core checklist (signal, why it matters, unknowns, provisional ownership or “unknown”, next action)
• Outside-originated section
• Explicit: DoC ≠ DoR; assessment outcomes DoC-Ok / DoC-Failed / unassessed
• Loadable as GET /policy/intake-doc

Done when: policy file exists and is readable via the policy API.

---

Task: Author DoR policy

id: STATE-WP-0076-T03
status: todo
priority: high
state_hub_task_id: "a1e7ab93-c0b9-423c-84d8-1e9dcff9ebc7"

Create policies/work-item-dor.md (Definition of Ready) — filename keeps “work-item” as the delivery-side gate name; body uses task and workplan sections (not “workplan is a work-item”).

• Per-kind sections: task, workplan
• Outside-originated section
• Link to workstream-dod.md as exit companion (DoD-Ok separate from finished)
• Assessment outcomes DoR-Ok / DoR-Failed / unassessed
• Loadable as GET /policy/work-item-dor

Done when: policy file exists and is readable via the policy API.

---

Task: Dashboard policy pages + nav

id: STATE-WP-0076-T04
status: todo
priority: high
state_hub_task_id: "d4aa3c53-3aa0-492f-b721-1c4e7e75bcb6"

Mirror DoI/DoM/DoD:

• dashboard/src/policy/intake-doc.md, dashboard/src/policy/work-item-dor.md
• Policies entries in observablehq.config.js
• Links from work-records reference (+ quality-gates doc)

Done when: Policies menu shows DoC and DoR; edit/view works against the API.

---

Cancelled / deferred tasks

Soft enforcement and DoD family-index tasks were dropped from scope after review (policy + docs first).

id: STATE-WP-0076-T05
status: cancel
priority: medium
state_hub_task_id: "80f612f4-4a8a-4e2c-9cbb-08dfb27264af"

Soft enforcement hooks — deferred until DoC/DoR text is in use.

id: STATE-WP-0076-T06
status: cancel
priority: low
state_hub_task_id: "fb6b81a0-208e-4a33-af33-776867411b7d"

Standalone DoD naming / family index task — folded into T01 quality-gates doc.

Deferred (not in this plan)

Idea	Why defer
Soft warnings on promote / ready without assessment	Needs lived policy text first
Badge fields in DB/frontmatter + “finished ∧ ¬DoD-Ok” KPI	Mid-term metric; convention first
DoD body rewrite + filename migration	Low urgency; link from DoR is enough
Optional type tags (dev/sec/ops, exp/def/try/sol)	No gate dependency

Acceptance criteria

• Docs: generic work-record (unit + structure), lifecycle ≠ DoX badge
• policies/intake-doc.md and policies/work-item-dor.md live and API-served
• Outside-originated sections present in both
• Dashboard Policies nav includes both
• No new kinds, no badge engine, no hard enforcement

References

• the-custodian/canon/standards/work-record-types_v0.1.md
• policies/repo-doi.md, policies/service-dom.md, policies/workstream-dod.md
• dashboard/src/docs/work-records.md, intakes.md, workstream-lifecycle.md
• api/routers/policy.py