state-hub/workplans/STATE-WP-0077-dox-assessment-recording-and-soft-visibility.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-0077	workplan	DoX assessment recording and soft visibility	infotech	state-hub	ready	grok	infotech	2026-07-22	2026-07-22	2026-07-22	grok	3008d9e	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	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

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

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

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

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