docs: work-record consolidation references and STATE-WP-0076 ready
Align dashboard reference pages with intake-as-discovery and suggestions as legacy, frame work records as unit vs structure artefacts, and add the ready STATE-WP-0076 plan for DoC/DoR quality policies. Include generated work-record index and recent legacy-meter evidence captures.
This commit is contained in:
parent
21d576c96f
commit
d8a2bb5c6b
15 changed files with 5951 additions and 103 deletions
226
workplans/STATE-WP-0076-definition-of-ready-and-comprehension.md
Normal file
226
workplans/STATE-WP-0076-definition-of-ready-and-comprehension.md
Normal file
|
|
@ -0,0 +1,226 @@
|
|||
---
|
||||
id: STATE-WP-0076
|
||||
type: workplan
|
||||
title: "Definition of Ready (DoR) and Definition of Comprehension (DoC) quality gates"
|
||||
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: "HEAD"
|
||||
context_paths:
|
||||
- "policies/"
|
||||
- "dashboard/src/docs/work-records.md"
|
||||
- "dashboard/src/docs/intakes.md"
|
||||
- "dashboard/src/docs/workstream-lifecycle.md"
|
||||
- "dashboard/src/policy/"
|
||||
- "docs/work-record-quality-gates.md"
|
||||
- "workplans/STATE-WP-0076-definition-of-ready-and-comprehension.md"
|
||||
state_hub_workstream_id: "72d64a42-bb87-4842-839d-3d4ed783ff2d"
|
||||
---
|
||||
|
||||
# STATE-WP-0076 — DoR and DoC quality gates
|
||||
|
||||
## Goal
|
||||
|
||||
Ship the next slice of the work-record quality model that pays off soon:
|
||||
|
||||
1. **Policies** in the existing DoI / DoM / DoD family: **DoC** (intake) and **DoR**
|
||||
(task + workplan sections).
|
||||
2. **Dashboard** edit/view surfaces like the other policies.
|
||||
3. **Docs** that fix terminology: work-record as generic coordination artefact
|
||||
(units *and* structure), lifecycle **≠** definition assessment, badge spelling
|
||||
`DoX-Ok` / `DoX-Failed` / unassessed.
|
||||
|
||||
No badge engine, no hard API blocks, no new kinds, no value-chain typing.
|
||||
|
||||
## Where we are (context)
|
||||
|
||||
| Already true | Gap this plan closes |
|
||||
|--------------|----------------------|
|
||||
| Work-record kinds + spine (canon) | DoC/DoR not written as hub policies |
|
||||
| Intake = discovery; promote → delivery | No transparent “comprehended enough?” checklist |
|
||||
| Workplan `ready` / `finished` lifecycle | No separate DoR/DoD assessment language; status ≠ quality |
|
||||
| DoI, DoM, DoD as `policies/*.md` + UI | DoC/DoR missing from that family |
|
||||
| Reference docs for kinds/lifecycle | Need unit-vs-structure + quality-vs-state framing |
|
||||
|
||||
Prior session also left doc updates for suggestions→intake and work-records
|
||||
pages; this plan assumes those land or already landed in the same branch.
|
||||
|
||||
## Non-goals
|
||||
|
||||
- Freeform badge product or badge persistence API
|
||||
- Soft/hard enforcement hooks (convention only until policies are used)
|
||||
- Renaming kinds (`intake`→find, `task`→item)
|
||||
- DiscoveryMap / mon-pro-sal / enforced exp→…→evo chains
|
||||
- Contribution retirement
|
||||
- Full DoD rewrite (link only; optional one-line title note)
|
||||
|
||||
## Design constraints (fixed for this plan)
|
||||
|
||||
1. **Lifecycle state ≠ definition badge.**
|
||||
`status=finished` may lack `DoD-Ok`; `status=ready` may lack `DoR-Ok`. That
|
||||
is intentional (fluid progress + quality metrics later).
|
||||
|
||||
2. **Badge family is closed and named after policies.**
|
||||
Outcomes: **unassessed** | **`DoC-Ok` / `DoR-Ok` / `DoD-Ok`** | **`DoC-Failed` /
|
||||
`DoR-Failed` / `DoD-Failed`**. Tiered policies (DoI/DoM) may use `DoM-Ok-1`
|
||||
etc. Assessment is manual/convention in this plan; storage can be prose or
|
||||
frontmatter later.
|
||||
|
||||
3. **Policies declare `applies_to` kinds** and may have **per-kind sections**
|
||||
(e.g. DoR for task vs workplan). Workplan is a **structure** record; task is
|
||||
a **unit** work-item — do not call workplans “work-items” in policy text.
|
||||
|
||||
4. **DoC** applies only to **`intake`**. It justifies treating discovery as
|
||||
understood enough to route/promote — not implementation design.
|
||||
|
||||
5. **DoR** applies to **`task`** and **`workplan`**. It justifies
|
||||
implementation-readiness. Workplan lifecycle `ready` remains a process claim;
|
||||
DoR is the checklist behind a `DoR-Ok` assessment.
|
||||
|
||||
6. **Outside-originated** = extra **sections** in DoC/DoR (origin/boundary
|
||||
fields), not a new kind.
|
||||
|
||||
7. **Enforcement = convention + docs.** No promote-intake/API blocking in this
|
||||
plan.
|
||||
|
||||
---
|
||||
|
||||
## Task: Quality model + work-record roles in docs
|
||||
|
||||
```task
|
||||
id: STATE-WP-0076-T01
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: "53aac055-97a7-405b-bb9b-48427de4296a"
|
||||
```
|
||||
|
||||
Short design/reference write-up only (no product build):
|
||||
|
||||
- Update `dashboard/src/docs/work-records.md`: work-record as **generic** mode
|
||||
for units *and* structure (plans/collections); unit vs structure table; quality
|
||||
badges vs lifecycle; link to policies when they exist.
|
||||
- Add `docs/work-record-quality-gates.md`: Definition family (DoI/DoM/DoC/DoR/DoD),
|
||||
badge spelling, applies_to matrix, outside profile pointer, explicit non-goals.
|
||||
- One cross-link from intakes + workplan lifecycle docs.
|
||||
|
||||
**Done when:** an agent can explain unit vs structure and DoR-Ok vs `status=ready`
|
||||
from the docs alone.
|
||||
|
||||
---
|
||||
|
||||
## Task: Author DoC policy
|
||||
|
||||
```task
|
||||
id: STATE-WP-0076-T02
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: "2498bd9f-e773-4dad-a2e3-9c32b5585d73"
|
||||
```
|
||||
|
||||
Create `policies/intake-doc.md` (Definition of Comprehension).
|
||||
|
||||
- `applies_to: intake`
|
||||
- Core checklist (signal, why it matters, unknowns, provisional ownership or
|
||||
“unknown”, next action)
|
||||
- Outside-originated section
|
||||
- Explicit: DoC ≠ DoR; assessment outcomes DoC-Ok / DoC-Failed / unassessed
|
||||
- Loadable as `GET /policy/intake-doc`
|
||||
|
||||
**Done when:** policy file exists and is readable via the policy API.
|
||||
|
||||
---
|
||||
|
||||
## Task: Author DoR policy
|
||||
|
||||
```task
|
||||
id: STATE-WP-0076-T03
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: "a1e7ab93-c0b9-423c-84d8-1e9dcff9ebc7"
|
||||
```
|
||||
|
||||
Create `policies/work-item-dor.md` (Definition of Ready) — filename keeps
|
||||
“work-item” as the delivery-side gate name; body uses **task** and **workplan**
|
||||
sections (not “workplan is a work-item”).
|
||||
|
||||
- Per-kind sections: task, workplan
|
||||
- Outside-originated section
|
||||
- Link to `workstream-dod.md` as exit companion (DoD-Ok separate from finished)
|
||||
- Assessment outcomes DoR-Ok / DoR-Failed / unassessed
|
||||
- Loadable as `GET /policy/work-item-dor`
|
||||
|
||||
**Done when:** policy file exists and is readable via the policy API.
|
||||
|
||||
---
|
||||
|
||||
## Task: Dashboard policy pages + nav
|
||||
|
||||
```task
|
||||
id: STATE-WP-0076-T04
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: "d4aa3c53-3aa0-492f-b721-1c4e7e75bcb6"
|
||||
```
|
||||
|
||||
Mirror DoI/DoM/DoD:
|
||||
|
||||
- `dashboard/src/policy/intake-doc.md`, `dashboard/src/policy/work-item-dor.md`
|
||||
- Policies entries in `observablehq.config.js`
|
||||
- Links from work-records reference (+ quality-gates doc)
|
||||
|
||||
**Done when:** Policies menu shows DoC and DoR; edit/view works against the API.
|
||||
|
||||
---
|
||||
|
||||
## Cancelled / deferred tasks
|
||||
|
||||
Soft enforcement and DoD family-index tasks were dropped from scope after
|
||||
review (policy + docs first).
|
||||
|
||||
```task
|
||||
id: STATE-WP-0076-T05
|
||||
status: cancel
|
||||
priority: medium
|
||||
state_hub_task_id: "80f612f4-4a8a-4e2c-9cbb-08dfb27264af"
|
||||
```
|
||||
|
||||
Soft enforcement hooks — deferred until DoC/DoR text is in use.
|
||||
|
||||
```task
|
||||
id: STATE-WP-0076-T06
|
||||
status: cancel
|
||||
priority: low
|
||||
state_hub_task_id: "fb6b81a0-208e-4a33-af33-776867411b7d"
|
||||
```
|
||||
|
||||
Standalone DoD naming / family index task — folded into T01 quality-gates doc.
|
||||
|
||||
## Deferred (not in this plan)
|
||||
|
||||
| Idea | Why defer |
|
||||
|------|-----------|
|
||||
| Soft warnings on promote / ready without assessment | Needs lived policy text first |
|
||||
| Badge fields in DB/frontmatter + “finished ∧ ¬DoD-Ok” KPI | Mid-term metric; convention first |
|
||||
| DoD body rewrite + filename migration | Low urgency; link from DoR is enough |
|
||||
| Optional type tags (dev/sec/ops, exp/def/try/sol) | No gate dependency |
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] Docs: generic work-record (unit + structure), lifecycle ≠ DoX badge
|
||||
- [ ] `policies/intake-doc.md` and `policies/work-item-dor.md` live and API-served
|
||||
- [ ] Outside-originated sections present in both
|
||||
- [ ] Dashboard Policies nav includes both
|
||||
- [ ] No new kinds, no badge engine, no hard enforcement
|
||||
|
||||
## References
|
||||
|
||||
- `the-custodian/canon/standards/work-record-types_v0.1.md`
|
||||
- `policies/repo-doi.md`, `policies/service-dom.md`, `policies/workstream-dod.md`
|
||||
- `dashboard/src/docs/work-records.md`, `intakes.md`, `workstream-lifecycle.md`
|
||||
- `api/routers/policy.py`
|
||||
Loading…
Add table
Add a link
Reference in a new issue