state-hub/workplans/STATE-WP-0077-dox-assessment-recording-and-soft-visibility.md

---
id: STATE-WP-0077
type: workplan
title: "DoX assessment recording and soft visibility"
domain: infotech
repo: state-hub
status: ready
owner: grok
topic_slug: infotech
created: "2026-07-22"
updated: "2026-07-22"
reviewed_at: "2026-07-22"
reviewed_by: "grok"
reviewed_against_commit: "3008d9e"
context_paths:
  - "docs/work-record-quality-gates.md"
  - "policies/intake-doc.md"
  - "policies/work-item-dor.md"
  - "policies/workstream-dod.md"
  - "dashboard/src/docs/work-records.md"
  - "scripts/"
  - ".claude/rules/"
  - "AGENTS.md"
state_hub_workstream_id: "a772c7cf-7172-486c-9c80-c70f6101db8f"
---

# STATE-WP-0077 — DoX assessment recording and soft visibility

## Goal

Make the **DoX badge convention from STATE-WP-0076 operational** without a
badge engine or hard gates:

1. **Record** last Definition assessments on work records (convention + light
   storage).
2. **See** quality debt: e.g. workplans `finished` without DoD-Ok, `ready`
   without DoR-Ok, intakes promoted/routed without DoC-Ok.
3. **Guide agents** with soft protocol (and optional cheap warnings).

Parent: `STATE-WP-0076` (DoC/DoR policies and badge spelling — finished).

## Background (what is already true)

| Active | Not active |
|--------|------------|
| DoC / DoR / DoD policy text | First-class badge field on hub rows |
| Spelling: unassessed / `DoX-Ok` / `DoX-Failed` | Dashboard badge column |
| Lifecycle ≠ quality (documented) | “finished ∧ ¬DoD-Ok” KPI/list |
| Convention-only enforcement | Soft warnings on promote / ready |

## Non-goals

- Freeform badge product or open badge taxonomy
- Hard API 422 / blocked transitions on missing DoX-Ok
- Full DoD rewrite (may touch only badge wording alignment)
- New work-record kinds
- Contribution retirement

## Design constraints

1. **Closed badge family only:** `DoC-Ok` / `DoC-Failed`, `DoR-Ok` /
   `DoR-Failed`, `DoD-Ok` / `DoD-Failed`, plus unassessed; tiered DoI/DoM stay
   on assets.
2. **Lifecycle remains independent** — missing Ok is quality debt, not invalid
   status.
3. **Prefer file/progress convention over new tables** in v1; add DB only if a
   list/KPI cannot be built otherwise.
4. **Soft only** — warn or surface; never block promote-intake or status patch
   in this plan.

---

## Task: Assessment recording convention

```task
id: STATE-WP-0077-T01
status: todo
priority: high
state_hub_task_id: "483af4cf-3aa9-49de-910d-034a0895a9bb"
```

Define and document **how** a last assessment is recorded:

- Target shapes (pick minimal set that works with fix-consistency / agents):
  - workplan frontmatter and/or task block fields, and/or
  - intake YAML / notes, and/or
  - progress event `event_type` + `detail` (e.g. `quality_assessment`)
- Required fields: which policy (`DoC`|`DoR`|`DoD`), outcome
  (`Ok`|`Failed`), `assessed_at`, optional `assessed_by`, optional `note`
- Update `docs/work-record-quality-gates.md` with the canonical recording form
- One short example per kind (intake DoC, task/workplan DoR, workplan DoD)

**Done when:** an agent can record DoR-Ok / DoC-Failed the same way every time
without inventing a private format.

---

## Task: Soft visibility — quality-debt list or digest

```task
id: STATE-WP-0077-T02
status: todo
priority: high
state_hub_task_id: "ff318c88-86e6-4231-bc25-3bd936e63035"
```

Expose at least one **read surface** for quality debt (implement the smallest
useful option):

Candidates (choose in implementation; document choice):

- CLI or script: list workplans with `status=ready` and no DoR-Ok; `finished`
  and no DoD-Ok; open intakes `vetted`/`routed` without DoC-Ok
- Optional: include a slice in `GET /state/summary` or next_steps as soft
  signals (not ranked_suggestions revival)
- Optional light dashboard note later — not required if CLI/script is enough

**Done when:** operator/agent can answer “which finished plans lack DoD-Ok?”
from hub tooling without grepping the whole fleet by hand.

---

## Task: Agent protocol and soft warnings

```task
id: STATE-WP-0077-T03
status: todo
priority: medium
state_hub_task_id: "dd3e70b2-0335-438e-8e59-d905c046cee3"
```

- Session / AGENTS guidance: assess DoC before confident promote; assess DoR
  before heavy implementation; record outcome in the T01 form
- Optional cheap soft warnings only (log/stderr/progress note — **no 422**):
  - `promote-intake` when intake has no DoC-Ok recorded
  - consistency warn when `status=ready` without DoR assessment metadata
- Update quality-gates doc “Enforcement level” section to match what shipped

**Done when:** default agent path records assessments; optional warnings exist
or are explicitly deferred with rationale in the doc.

---

## Task: Align DoD policy wording with badge family

```task
id: STATE-WP-0077-T04
status: todo
priority: low
state_hub_task_id: "d620891f-562c-4c1d-8f72-fd13415e4a0a"
```

Light touch on `policies/workstream-dod.md`:

- State applies_to workplan, outcomes `DoD-Ok` / `DoD-Failed` / unassessed
- Note lifecycle `finished` ≠ DoD-Ok
- Do not expand DoD criteria into a large rewrite unless one-liners are broken

**Done when:** DoD speaks the same assessment language as DoC/DoR.

---

## Acceptance criteria

- [ ] Canonical recording form documented and exemplified
- [ ] At least one quality-debt list/digest works against live data
- [ ] Agent protocol documents when to assess and how to record
- [ ] No hard gates; no freeform badge engine
- [ ] DoD policy mentions DoD-Ok / Failed / unassessed

## References

- `docs/work-record-quality-gates.md`
- `policies/intake-doc.md`, `policies/work-item-dor.md`, `policies/workstream-dod.md`
- `STATE-WP-0076` (parent)
- `dashboard/src/docs/work-records.md`