diff --git a/WORK-RECORDS.md b/WORK-RECORDS.md index 3628e6f..0d8dbb6 100644 --- a/WORK-RECORDS.md +++ b/WORK-RECORDS.md @@ -45,6 +45,7 @@ | workplan | STATE-WP-0074 | finished | — | workplans/STATE-WP-0074-hub-ecosystem-boundary-alignment.md | | workplan | STATE-WP-0075 | finished | — | workplans/STATE-WP-0075-workstream-route-410-stranglers.md | | workplan | STATE-WP-0076 | finished | — | workplans/STATE-WP-0076-definition-of-ready-and-comprehension.md | +| workplan | STATE-WP-0077 | ready | — | workplans/STATE-WP-0077-dox-assessment-recording-and-soft-visibility.md | | task | ADHOC-2026-06-04-T01 | done | — | workplans/ADHOC-2026-06-04.md | | task | ADHOC-2026-07-01-T01 | done | — | workplans/ADHOC-2026-07-01.md | | task | ADHOC-2026-07-01-T02 | done | — | workplans/ADHOC-2026-07-01.md | @@ -258,3 +259,7 @@ | task | STATE-WP-0076-T04 | done | — | workplans/STATE-WP-0076-definition-of-ready-and-comprehension.md | | task | STATE-WP-0076-T05 | cancel | — | workplans/STATE-WP-0076-definition-of-ready-and-comprehension.md | | task | STATE-WP-0076-T06 | cancel | — | workplans/STATE-WP-0076-definition-of-ready-and-comprehension.md | +| task | STATE-WP-0077-T01 | todo | — | workplans/STATE-WP-0077-dox-assessment-recording-and-soft-visibility.md | +| task | STATE-WP-0077-T02 | todo | — | workplans/STATE-WP-0077-dox-assessment-recording-and-soft-visibility.md | +| task | STATE-WP-0077-T03 | todo | — | workplans/STATE-WP-0077-dox-assessment-recording-and-soft-visibility.md | +| task | STATE-WP-0077-T04 | todo | — | workplans/STATE-WP-0077-dox-assessment-recording-and-soft-visibility.md | diff --git a/workplans/STATE-WP-0077-dox-assessment-recording-and-soft-visibility.md b/workplans/STATE-WP-0077-dox-assessment-recording-and-soft-visibility.md new file mode 100644 index 0000000..a3b9b53 --- /dev/null +++ b/workplans/STATE-WP-0077-dox-assessment-recording-and-soft-visibility.md @@ -0,0 +1,176 @@ +--- +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`