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)

```yaml
---
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)

````markdown
```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:

```text
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)

```bash
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

```bash
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):

```text
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](/policy/intake-doc)
- [Work-item DoR](/policy/work-item-dor)
- [Workplan DoD](/policy/workstream-dod)
- [Repository DoI](/policy/repo-doi)
- [Service DoM](/policy/service-dom)