state-hub/docs/work-record-quality-gates.md

Work-record quality gates (Definition family)

Status: active convention (STATE-WP-0076 policies; STATE-WP-0077 recording + soft visibility)
Related: dashboard/src/docs/work-records.md, policies/intake-doc.md, policies/work-item-dor.md, policies/workstream-dod.md, policies/repo-doi.md, policies/service-dom.md, policies/retirement-freeze.md

Purpose

Define how Definition-of-X policies relate to work records without merging quality into lifecycle status and without a freeform badge product.

Definition family

Policy	Key (API /policy/<key>)	Rates	Applies to
DoI — Definition of Integrated	repo-doi	Repo integration maturity (tiered)	managed repos
DoM — Definition of Mature	service-dom	Service operability/maturity (leveled)	long-running services
DoC — Definition of Comprehension	intake-doc	Discovery quality	intake only
DoR — Definition of Ready	work-item-dor	Implementation-readiness	task, workplan (per-kind sections)
DoD — Definition of Done	workstream-dod	Completion quality	workplan (filename legacy; title is Workplan DoD)

DoI/DoM rate assets (repo/service). DoC/DoR/DoD rate work-record quality at discovery / ready / done. Do not mix the axes.

Lifecycle vs assessment

Axis	Field / surface	Meaning
Lifecycle	kind-specific status	Process position (e.g. workplan ready, intake vetted)
Definition assessment	convention / prose (later optional storage)	Whether a named policy was satisfied when last assessed

These are independent:

• status=ready is a process claim; DoR-Ok means the DoR checklist passed.
• status=finished is a process claim; DoD-Ok means the DoD checklist passed.
• Counting finished workplans without DoD-Ok is a valid quality metric, not an error.

Badge spelling (closed)

For each Definition policy that applies to a record:

Outcome	Spelling	Meaning
Not assessed	unassessed (or absent)	No assessment recorded
Passed	DoC-Ok, DoR-Ok, DoD-Ok	Last assessment passed
Failed	DoC-Failed, DoR-Failed, DoD-Failed	Assessment ran and failed
Tiered (DoI/DoM)	DoM-Ok-1, DoI-Ok-2, …	Level/tier met; DoM-Failed if assessed and short

No open-ended custom badges. New badge families require a new Definition policy in policies/.

Recording assessments (STATE-WP-0077)

Canonical storage is file fields (preferred) plus optional progress events. No badge DB table.

Field names

Policy	Field	Values
DoC	quality_doc	DoC-Ok | DoC-Failed (or bare Ok / Failed)
DoR	quality_dor	DoR-Ok | DoR-Failed (or bare Ok / Failed)
DoD	quality_dod	DoD-Ok | DoD-Failed (or bare Ok / Failed)

Optional companions (same prefix): quality_*_at (ISO date), quality_*_by, quality_*_note.

Workplan frontmatter example (DoR + later DoD)

---
id: STATE-WP-0077
status: ready
quality_dor: DoR-Ok
quality_dor_at: "2026-07-22"
quality_dor_by: "grok"
# quality_dod: DoD-Ok   # when finishing with quality complete
---

Task block example (DoR)

```task
id: STATE-WP-0077-T01
status: todo
priority: high
quality_dor: DoR-Ok
quality_dor_at: "2026-07-22"
quality_dor_by: "grok"
```

Intake YAML example (DoC)

Use a real {PREFIX}-IN-NNNN id only in the owning repo file — not in docs (examples with live id patterns get registered by fix-consistency). Field shape:

id: <PREFIX>-IN-NNNN
status: routed
quality_doc: DoC-Ok
quality_doc_at: "YYYY-MM-DD"
quality_doc_by: "agent-or-human"
quality_doc_note: "optional"

Hub-only intakes (no file yet): add a note whose body includes DoC-Ok or quality_doc: DoC-Ok, and/or post a progress event (below).

Progress event (optional audit)

curl -s -X POST http://127.0.0.1:8000/progress/ \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "quality_assessment",
    "summary": "DoR-Ok for workplan STATE-WP-0077",
    "author": "grok",
    "topic_id": "<uuid>",
    "workplan_id": "<uuid>",
    "detail": {
      "policy": "DoR",
      "outcome": "Ok",
      "badge": "DoR-Ok",
      "record_kind": "workplan",
      "record_id": "STATE-WP-0077",
      "assessed_by": "grok",
      "note": null
    }
  }'

Helpers: scripts/quality_assessment.py (badge(), progress_event_body()).

Soft visibility

statehub quality-debt                  # cwd repo + hub intakes
statehub quality-debt --json --no-hub
python scripts/quality_debt.py --here

Reports:

• workplans status=ready without quality_dor DoR-Ok
• workplans status=finished without quality_dod DoD-Ok
• file intakes vetted/routed without quality_doc DoC-Ok
• hub intakes vetted/routed without DoC-Ok in notes

fix-consistency soft warns C-34 (ready without DoR-Ok). Finished plans without DoD-Ok appear in quality-debt only (not C-warns), so historical finished workplans do not flood every consistency run. Never fixable auto-write; never FAIL.

Unit vs structure (reminder)

Role	Kinds	Quality gates of interest
Unit	task, intake, decision, …	DoC (intake); DoR (task); others later
Structure	workplan	DoR (plan-level); DoD (completion)

Workplan is a work record mechanically; it is not a “large task.”

Outside-originated profile

When signal or work originates outside structural knowledge of the owning repo (external demand, true third-party, sparse founder/mail signal), use the Outside-originated sections in DoC and DoR. Detection is by fields/tags such as origin, origin_ref, third-party, external-demand — not by inventing a new kind.

Pipeline (unenforceable mental model):

outside / sparse signal
  → intake
  → DoC assessment (DoC-Ok before confident route/promote)
  → task / workplan
  → DoR assessment (DoR-Ok before confident implementation)
  → work
  → DoD assessment (DoD-Ok when claiming quality-complete)

Enforcement level (STATE-WP-0077)

Mechanism	Behaviour
Convention + this doc	Primary
statehub quality-debt	Read-only debt list
C-34	Soft WARN in fix-consistency (ready without DoR-Ok)
promote-intake	Soft WARNING on stderr if no DoC-Ok; still promotes
Hard API / status blocks	None

Task-flow assertions must implement policy, not replace it.

Non-goals

• Freeform badge product
• Renaming kinds (intake→find, task→item)
• DiscoveryMap as a kind
• Enforced value-chain typing (exp→def→…→evo)
• Contribution retirement (separate)

Dashboard

• Intake DoC
• Work-item DoR
• Workplan DoD
• Repository DoI
• Service DoM