tegwick
3008d9e2f0
Add Intake Definition of Comprehension and work-item Definition of Ready as hub policies with dashboard edit surfaces, document the Definition family and DoX-Ok/Failed badge convention, and mark STATE-WP-0076 finished.
104 lines
4.2 KiB
Markdown
104 lines
4.2 KiB
Markdown
# Work-record quality gates (Definition family)
|
|
|
|
Status: active convention (STATE-WP-0076)
|
|
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`
|
|
|
|
## 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/`.
|
|
|
|
Assessment in v1 is **manual/convention** (agent or human notes, PR description,
|
|
progress event). No badge engine or hard API block ships with STATE-WP-0076.
|
|
|
|
## 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
|
|
|
|
Convention + documentation. Soft warnings and metrics may follow once policies
|
|
are in daily use. 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)
|