diff --git a/WORK-RECORDS.md b/WORK-RECORDS.md index 2a0c350..3628e6f 100644 --- a/WORK-RECORDS.md +++ b/WORK-RECORDS.md @@ -44,7 +44,7 @@ | workplan | STATE-WP-0073 | finished | — | workplans/STATE-WP-0073-legacy-meter-decline-and-remote-audit.md | | 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 | ready | — | workplans/STATE-WP-0076-definition-of-ready-and-comprehension.md | +| workplan | STATE-WP-0076 | finished | — | workplans/STATE-WP-0076-definition-of-ready-and-comprehension.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 | @@ -252,9 +252,9 @@ | task | STATE-WP-0075-T02 | done | — | workplans/STATE-WP-0075-workstream-route-410-stranglers.md | | task | STATE-WP-0075-T03 | done | — | workplans/STATE-WP-0075-workstream-route-410-stranglers.md | | task | STATE-WP-0075-T04 | done | — | workplans/STATE-WP-0075-workstream-route-410-stranglers.md | -| task | STATE-WP-0076-T01 | todo | — | workplans/STATE-WP-0076-definition-of-ready-and-comprehension.md | -| task | STATE-WP-0076-T02 | todo | — | workplans/STATE-WP-0076-definition-of-ready-and-comprehension.md | -| task | STATE-WP-0076-T03 | todo | — | workplans/STATE-WP-0076-definition-of-ready-and-comprehension.md | -| task | STATE-WP-0076-T04 | todo | — | workplans/STATE-WP-0076-definition-of-ready-and-comprehension.md | +| task | STATE-WP-0076-T01 | done | — | workplans/STATE-WP-0076-definition-of-ready-and-comprehension.md | +| task | STATE-WP-0076-T02 | done | — | workplans/STATE-WP-0076-definition-of-ready-and-comprehension.md | +| task | STATE-WP-0076-T03 | done | — | workplans/STATE-WP-0076-definition-of-ready-and-comprehension.md | +| 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 | diff --git a/dashboard/observablehq.config.js b/dashboard/observablehq.config.js index f46fc70..9aebb7a 100644 --- a/dashboard/observablehq.config.js +++ b/dashboard/observablehq.config.js @@ -56,6 +56,8 @@ export default { pages: [ { name: "Repository DoI", path: "/policy/repo-doi" }, { name: "Service DoM", path: "/policy/service-dom" }, + { name: "Intake DoC", path: "/policy/intake-doc" }, + { name: "Work-item DoR", path: "/policy/work-item-dor" }, { name: "Workplan DoD", path: "/policy/workstream-dod" }, ], }, diff --git a/dashboard/src/docs/intakes.md b/dashboard/src/docs/intakes.md index 322ea15..91fdfb8 100644 --- a/dashboard/src/docs/intakes.md +++ b/dashboard/src/docs/intakes.md @@ -16,6 +16,12 @@ Umbrella: [Work Records](/docs/work-records). Intakes **replace** the retired hub **suggestion** backlog for new work. See [Suggestions (legacy)](/docs/suggestions). +**Quality:** discovery comprehension is governed by +[Definition of Comprehension (DoC)](/policy/intake-doc) (`DoC-Ok` / +`DoC-Failed` / unassessed). DoC is independent of lifecycle `status` and is +**not** implementation readiness ([DoR](/policy/work-item-dor)). Model: +`docs/work-record-quality-gates.md`. + --- ## Lifecycle diff --git a/dashboard/src/docs/tasks.md b/dashboard/src/docs/tasks.md index eeab1d2..3923ac8 100644 --- a/dashboard/src/docs/tasks.md +++ b/dashboard/src/docs/tasks.md @@ -8,8 +8,9 @@ The Tasks page shows all tasks across every workplan and domain, with live filtering, a workstation distribution chart, and a waiting-tasks highlight section. -A **task** is a work-record kind: the smallest executable unit. Tasks always -belong to a workplan. Umbrella: [Work Records](/docs/work-records). +A **task** is a work-record kind: the smallest executable unit (work-item). +Tasks always belong to a workplan. Umbrella: [Work Records](/docs/work-records). +Implementation-readiness: [DoR](/policy/work-item-dor). --- diff --git a/dashboard/src/docs/work-records.md b/dashboard/src/docs/work-records.md index 11aaf47..fd0d738 100644 --- a/dashboard/src/docs/work-records.md +++ b/dashboard/src/docs/work-records.md @@ -76,8 +76,16 @@ Assessments do **not** invent extra lifecycle states. Outcomes are: A workplan may be `status=finished` without **DoD-Ok**, or `status=ready` without **DoR-Ok**. That is allowed: process can advance while quality debt stays visible. Policies live under `policies/` (same pattern as Repository DoI -and Service DoM). **DoC** (intake) and **DoR** (task/workplan) are introduced -by workplan `STATE-WP-0076`. +and Service DoM): + +| Policy | Dashboard | Rates | +|--------|-----------|-------| +| **DoC** | [Intake DoC](/policy/intake-doc) | Discovery quality (`intake`) | +| **DoR** | [Work-item DoR](/policy/work-item-dor) | Implementation-readiness (`task`, `workplan`) | +| **DoD** | [Workplan DoD](/policy/workstream-dod) | Completion quality (workplan) | + +Full matrix and badge spelling: repo doc `docs/work-record-quality-gates.md` +(STATE-WP-0076). Discovery quality (intake) is **not** the same as implementation-readiness (task/workplan). Outside or sparse-context signals should be comprehended diff --git a/dashboard/src/docs/workstream-lifecycle.md b/dashboard/src/docs/workstream-lifecycle.md index 6940715..24ac4b7 100644 --- a/dashboard/src/docs/workstream-lifecycle.md +++ b/dashboard/src/docs/workstream-lifecycle.md @@ -16,6 +16,13 @@ The product term is **workplan**. **Workstream** remains a legacy compatibility name in some fields (notably frontmatter `state_hub_workstream_id`) and historical URLs; it refers to the same entity. +**Quality vs lifecycle:** `status=ready` or `status=finished` is process state. +Implementation-readiness and completion quality are separate assessments — +[DoR](/policy/work-item-dor) (`DoR-Ok` / `DoR-Failed`) and +[DoD](/policy/workstream-dod) (`DoD-Ok` / `DoD-Failed`). A finished workplan +without DoD-Ok is allowed quality debt. See +`docs/work-record-quality-gates.md`. + --- ## Stored lifecycle states diff --git a/dashboard/src/policy/intake-doc.md b/dashboard/src/policy/intake-doc.md new file mode 100644 index 0000000..9a3e563 --- /dev/null +++ b/dashboard/src/policy/intake-doc.md @@ -0,0 +1,92 @@ +--- +title: Intake Definition of Comprehension (DoC) +--- + +```js +import {API} from "../components/config.js"; +``` + +```js +import {marked} from "npm:marked"; + +const _resp = await fetch(`${API}/policy/intake-doc`); +if (!_resp.ok) throw new Error(`Failed to load policy: ${_resp.status}`); +const _policy = await _resp.json(); +``` + +```js +let _content = _policy.content; +let _editing = false; + +const _root = display(html`
`); + +async function _save(text) { + const r = await fetch(`${API}/policy/intake-doc`, { + method: "PUT", + headers: {"Content-Type": "application/json"}, + body: JSON.stringify({content: text}), + }); + if (!r.ok) throw new Error(`Save failed: ${r.status}`); + _content = text; +} + +function _toolbar(...nodes) { + return html`
${nodes}
`; +} + +function _btn(label, primary = false) { + return html``; +} + +function _render() { + _root.innerHTML = ""; + + if (_editing) { + const area = html``; + + const saveBtn = _btn("Save", true); + const cancelBtn = _btn("Cancel"); + + saveBtn.onclick = async () => { + saveBtn.disabled = true; + saveBtn.textContent = "Saving…"; + try { + await _save(area.value); + _editing = false; + _render(); + } catch (e) { + saveBtn.disabled = false; + saveBtn.textContent = "Save"; + alert(e.message); + } + }; + + cancelBtn.onclick = () => { _editing = false; _render(); }; + + _root.append(_toolbar(saveBtn, cancelBtn), area); + + } else { + const editBtn = _btn("Edit"); + editBtn.onclick = () => { _editing = true; _render(); }; + + const body = html`
`; + body.innerHTML = marked.parse(_content); + + _root.append(_toolbar(editBtn), body); + } +} + +_render(); +``` diff --git a/dashboard/src/policy/work-item-dor.md b/dashboard/src/policy/work-item-dor.md new file mode 100644 index 0000000..d160123 --- /dev/null +++ b/dashboard/src/policy/work-item-dor.md @@ -0,0 +1,92 @@ +--- +title: Definition of Ready (DoR) +--- + +```js +import {API} from "../components/config.js"; +``` + +```js +import {marked} from "npm:marked"; + +const _resp = await fetch(`${API}/policy/work-item-dor`); +if (!_resp.ok) throw new Error(`Failed to load policy: ${_resp.status}`); +const _policy = await _resp.json(); +``` + +```js +let _content = _policy.content; +let _editing = false; + +const _root = display(html`
`); + +async function _save(text) { + const r = await fetch(`${API}/policy/work-item-dor`, { + method: "PUT", + headers: {"Content-Type": "application/json"}, + body: JSON.stringify({content: text}), + }); + if (!r.ok) throw new Error(`Save failed: ${r.status}`); + _content = text; +} + +function _toolbar(...nodes) { + return html`
${nodes}
`; +} + +function _btn(label, primary = false) { + return html``; +} + +function _render() { + _root.innerHTML = ""; + + if (_editing) { + const area = html``; + + const saveBtn = _btn("Save", true); + const cancelBtn = _btn("Cancel"); + + saveBtn.onclick = async () => { + saveBtn.disabled = true; + saveBtn.textContent = "Saving…"; + try { + await _save(area.value); + _editing = false; + _render(); + } catch (e) { + saveBtn.disabled = false; + saveBtn.textContent = "Save"; + alert(e.message); + } + }; + + cancelBtn.onclick = () => { _editing = false; _render(); }; + + _root.append(_toolbar(saveBtn, cancelBtn), area); + + } else { + const editBtn = _btn("Edit"); + editBtn.onclick = () => { _editing = true; _render(); }; + + const body = html`
`; + body.innerHTML = marked.parse(_content); + + _root.append(_toolbar(editBtn), body); + } +} + +_render(); +``` diff --git a/dashboard/src/reference.md b/dashboard/src/reference.md index 58fed65..9e2641b 100644 --- a/dashboard/src/reference.md +++ b/dashboard/src/reference.md @@ -49,7 +49,7 @@ convention used in the Custodian State Hub. | Topic | What it covers | |-------|---------------| -| [Work Records](/docs/work-records) | Umbrella term, kind registry, spine, lifecycles, legacy name map | +| [Work Records](/docs/work-records) | Umbrella term, unit vs structure, spine, lifecycle vs DoX quality badges | | [State Hub](/docs/state-hub) | Why/how/what — Derived Data Store principle, orchestrator role, architecture diagram, design principles | | [TPSC](/docs/tpsc) | Third-Party Services Catalog — tpsc.yaml format, ingest, MCP tools | | [TPSC — GDPR Maturity](/docs/gdpr-maturity) | 7-level CNIL/IAPP scale, per-level guidance, key GDPR concepts | diff --git a/docs/work-record-quality-gates.md b/docs/work-record-quality-gates.md new file mode 100644 index 0000000..a2dad6d --- /dev/null +++ b/docs/work-record-quality-gates.md @@ -0,0 +1,104 @@ +# 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/`) | 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) diff --git a/policies/intake-doc.md b/policies/intake-doc.md new file mode 100644 index 0000000..0175e7c --- /dev/null +++ b/policies/intake-doc.md @@ -0,0 +1,95 @@ +# Intake Definition of Comprehension (DoC) + +**applies_to:** `intake` +**Assessment outcomes:** `unassessed` | `DoC-Ok` | `DoC-Failed` +**Does not apply to:** workplan, task, decision, engagement, register-entry + +An intake is a **discovery** work record (a find / spark). **DoC** is the quality +policy for “we understand this demand or signal well enough to route or promote.” +It is **not** implementation design and **not** Definition of Ready. + +Lifecycle `status` (open / vetted / routed / closed) is independent of DoC +assessment. Prefer: treat **DoC-Ok** as the quality bar before confident +`vetted` → `routed` → promote. Process may still move without DoC-Ok; that is +quality debt, not forbidden. + +Related: + +- Work-record umbrella: `dashboard/src/docs/work-records.md` +- Quality model: `docs/work-record-quality-gates.md` +- Delivery readiness: `policies/work-item-dor.md` (DoR) +- Intake reference: `dashboard/src/docs/intakes.md` + +--- + +## Core checklist (all intakes) + +An intake may be assessed **DoC-Ok** when all of the following hold: + +- [ ] **Signal stated** — title (and description if non-obvious) says what was + observed, asked, or found, not a vague “look into X.” +- [ ] **Why it matters** — at least one sentence of consequence if ignored + (risk, opportunity, blocker, cost of delay). +- [ ] **Known unknowns listed** — what we do *not* know yet (owner, repo, scope, + feasibility, counterparty intent, …), or an explicit “no material unknowns.” +- [ ] **Provisional ownership** — at least one of: `topic_id` / `workplan_id` / + `repo_id` / domain hypothesis — **or** an explicit statement that ownership is + still unknown and who will decide. +- [ ] **Next action** — one of: route, promote (to which kind if known), decline, + absorb, or “needs more discovery” with a named follow-up. +- [ ] **Not a premature workplan** — the intake does not pretend to be a full + task breakdown, DoD, or implementation design (those belong after promotion + under DoR). + +If any core item fails after assessment, record **DoC-Failed** and note the gap. + +--- + +## Outside-originated profile + +Use this section when the signal is **external** or **structurally sparse**: +external demand into the fleet, true third-party/upstream, mail/founder note +without repo context, or `origin` / tags such as `external-demand` / +`third-party`. + +Additional criteria for **DoC-Ok** (on top of the core checklist): + +- [ ] **Source of signal** — `origin` and, when available, `origin_ref` (or + equivalent note) identify where the demand came from. +- [ ] **Boundary named** — one of: *ecosystem* (another fleet repo), *true + third-party*, *external demand into us*, or *unknown* with a plan to classify. +- [ ] **No invented foreign structure** — we do not schedule *their* backlog as + our workplan graph; we only record *our* understanding and *our* possible + response. +- [ ] **Enough context to avoid premature promote** — promoting to task/workplan + would not require guessing the owning repo or outcome shape; if it would, + keep the intake open/vetted and list the missing facts under known unknowns. +- [ ] **Counterparty or channel** (when third-party or external) — who/what is + outside, even if only “unknown maintainer of package X.” + +Ecosystem-only signals (work for another registered repo) usually need routing +clarity, not the full third-party bar; still record boundary as ecosystem. + +--- + +## Assessment practice (convention) + +- Assessors: owning agent, domain owner, or human operator. +- Record outcome in a note, progress event, or later frontmatter/badge field: + `DoC-Ok` or `DoC-Failed` plus date and short reason if failed. +- Re-assess after material new information; a prior DoC-Ok can become Failed or + be superseded by a new Ok. +- **DoC-Ok does not authorize implementation** — only comprehension for + routing/promotion. Delivery readiness is **DoR** on the resulting task or + workplan. + +--- + +## Explicit non-requirements + +DoC does **not** require: + +- Task breakdown, estimates, or acceptance tests +- Full solution design +- DoR or DoD criteria +- A workplan file to already exist diff --git a/policies/work-item-dor.md b/policies/work-item-dor.md new file mode 100644 index 0000000..59ca581 --- /dev/null +++ b/policies/work-item-dor.md @@ -0,0 +1,129 @@ +# Definition of Ready (DoR) + +**Policy key:** `work-item-dor` +**applies_to:** `task`, `workplan` (separate sections below) +**Assessment outcomes:** `unassessed` | `DoR-Ok` | `DoR-Failed` +**Does not apply to:** intake (use DoC), decision, engagement (no DoR yet) + +**DoR** is the quality policy for **implementation-readiness** of delivery +records. “Work-item” in the policy name means the **delivery side** of the +work-record framework (executable units and their plans). In body text: + +- **task** = unit work-item +- **workplan** = structure (collection/plan over tasks), **not** “a large task” + +Lifecycle `status` is independent of DoR assessment: + +- Workplan `status=ready` is a process claim; **DoR-Ok** means this checklist + passed when last assessed. +- A workplan may be `ready` or `active` without DoR-Ok (quality debt). +- A task may enter `progress` without DoR-Ok; that is allowed but discouraged + for non-trivial work. + +Related: + +- Comprehension (discovery): `policies/intake-doc.md` (DoC) +- Completion: `policies/workstream-dod.md` (DoD; exit companion) +- Model: `docs/work-record-quality-gates.md` +- Lifecycle: `dashboard/src/docs/workstream-lifecycle.md` + +--- + +## Shared criteria (task and workplan) + +For **DoR-Ok**, the following always hold (kind sections add specifics): + +- [ ] **Outcome or done-condition** — what “good enough to stop” looks like, or + an explicit pointer to DoD / acceptance criteria. +- [ ] **Scope in / out** — what is included and what is explicitly out of scope + (or “no material out-of-scope items”). +- [ ] **Owning repo** — delivery repo is known and matches ADR-001 anchoring + (or the task’s parent workplan repo). +- [ ] **Who executes** — owner/assignee or named agent role is clear enough to + start. +- [ ] **Dependencies / blockers** — known dependencies listed, or an explicit + “none.” Unresolved hard blockers mean DoR-Failed until cleared or redesigned. +- [ ] **Verification signal** — how we will know it worked (test, check, + manual verification note, or “N/A: pure docs” with reason). +- [ ] **Lane / autonomy** — lane is set or inherited where the record supports + it; red/yellow work has human expectation stated if required by autonomy + policy. + +--- + +## Section: task (`kind: task`) + +Additional **DoR-Ok** criteria for a task: + +- [ ] **Parent workplan** — task is attached to a workplan (or today’s ADHOC + workplan) so execution context is not free-floating. +- [ ] **Actionable title** — describes a completable unit, not a multi-week + program (programs belong in a workplan with multiple tasks). +- [ ] **Status intent** — starting `progress` is justified (not blocked on + missing input that should keep the task in `wait`). + +Tasks that are pure residual cleanup may be thin; still state done-condition +and verification, even if one line each. + +--- + +## Section: workplan (`kind: workplan`) + +Additional **DoR-Ok** criteria for a workplan: + +- [ ] **Goal** — one paragraph (or equivalent) for why this plan exists. +- [ ] **Task decomposition** — open work is broken into tasks, or an explicit + note that the first task is “decompose further” with a bound. +- [ ] **Review vs execute** — if `status=ready`, review metadata is present when + the plan claims repo-state review (`reviewed_at` / `reviewed_against_commit` + or equivalent narrative). Missing review metadata ⇒ prefer DoR-Failed for a + `ready` claim, or leave unassessed. +- [ ] **Structure role respected** — the plan does not substitute for missing + DoC on a vague external spark; if the plan was promoted from intake, origin + link is present when available (`origin: intake:…`). + +Workplan **DoR-Ok** does not require all child tasks to be DoR-Ok; it requires +the plan itself to be ready to *run as a structure*. Child tasks should be +assessed when they are about to be executed. + +--- + +## Outside-originated profile + +When the work-item or plan came from outside structural knowledge (promoted +intake with external origin, third-party response work, external demand): + +- [ ] **Origin link** — `origin` / `origin_ref` or intake id / progress note + ties back to the discovery record. +- [ ] **Boundary decision recorded** — ecosystem vs true third-party vs + external demand into us. +- [ ] **Our work only** — scope describes *our* deliverable (patch, adapter, + doc, decision), not control of an external backlog. +- [ ] **External reference** — issue/PR/URL or “none yet” with reason, when + third-party interaction is in scope. +- [ ] **Residual unknowns** — still-open external uncertainties listed; none + that would make the first implementation step pure guesswork. + +--- + +## Relationship to DoD and lifecycle + +| Gate | When | Policy | +|------|------|--------| +| DoC | Discovery understood | `intake-doc` | +| DoR | Ready to implement | this file | +| DoD | Quality-complete when finishing | `workstream-dod` | + +Finishing a workplan (`status=finished`) without **DoD-Ok** is allowed; treat +as quality debt. Prefer DoR-Ok before heavy implementation; prefer DoD-Ok before +calling the outcome high-quality complete. + +--- + +## Assessment practice (convention) + +- Assessors: workplan owner, executing agent, or human operator. +- Record `DoR-Ok` or `DoR-Failed` with date and failed criteria if any. +- Re-assess after major scope change; stale DoR-Ok after large context shift + should be treated as unassessed or re-checked. +- Enforcement is convention only (STATE-WP-0076); no API hard-block. diff --git a/workplans/STATE-WP-0076-definition-of-ready-and-comprehension.md b/workplans/STATE-WP-0076-definition-of-ready-and-comprehension.md index a982fbd..52200c7 100644 --- a/workplans/STATE-WP-0076-definition-of-ready-and-comprehension.md +++ b/workplans/STATE-WP-0076-definition-of-ready-and-comprehension.md @@ -4,14 +4,14 @@ type: workplan title: "Definition of Ready (DoR) and Definition of Comprehension (DoC) quality gates" domain: infotech repo: state-hub -status: ready +status: finished 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" +reviewed_against_commit: "d8a2bb5c6ba8d3db73eff565242e6c7fbe63d181" context_paths: - "policies/" - "dashboard/src/docs/work-records.md" @@ -38,56 +38,25 @@ Ship the next slice of the work-record quality model that pays off soon: No badge engine, no hard API blocks, no new kinds, no value-chain typing. -## Where we are (context) +## Delivered (2026-07-22) -| 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 | +| Deliverable | Path | +|-------------|------| +| Quality model note | `docs/work-record-quality-gates.md` | +| DoC policy | `policies/intake-doc.md` → `GET /policy/intake-doc` | +| DoR policy | `policies/work-item-dor.md` → `GET /policy/work-item-dor` | +| Dashboard pages | `dashboard/src/policy/intake-doc.md`, `work-item-dor.md` | +| Nav | Policies: Intake DoC, Work-item DoR | +| Reference links | work-records, intakes, workplan lifecycle, tasks | -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. +## Design constraints (shipped) -## 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. +1. Lifecycle state ≠ definition badge (`DoX-Ok` / `DoX-Failed` / unassessed). +2. Badge family closed and named after policies. +3. Policies declare applies_to; DoR has task and workplan sections. +4. DoC = intake only; DoR = task + workplan. +5. Outside-originated = policy sections, not a new kind. +6. Enforcement = convention + docs only. --- @@ -95,7 +64,7 @@ pages; this plan assumes those land or already landed in the same branch. ```task id: STATE-WP-0076-T01 -status: todo +status: done priority: high state_hub_task_id: "53aac055-97a7-405b-bb9b-48427de4296a" ``` @@ -118,7 +87,7 @@ from the docs alone. ```task id: STATE-WP-0076-T02 -status: todo +status: done priority: high state_hub_task_id: "2498bd9f-e773-4dad-a2e3-9c32b5585d73" ``` @@ -140,7 +109,7 @@ Create `policies/intake-doc.md` (Definition of Comprehension). ```task id: STATE-WP-0076-T03 -status: todo +status: done priority: high state_hub_task_id: "a1e7ab93-c0b9-423c-84d8-1e9dcff9ebc7" ``` @@ -163,7 +132,7 @@ sections (not “workplan is a work-item”). ```task id: STATE-WP-0076-T04 -status: todo +status: done priority: high state_hub_task_id: "d4aa3c53-3aa0-492f-b721-1c4e7e75bcb6" ``` @@ -180,9 +149,6 @@ Mirror DoI/DoM/DoD: ## 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 @@ -201,22 +167,13 @@ 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 +- [x] Docs: generic work-record (unit + structure), lifecycle ≠ DoX badge +- [x] `policies/intake-doc.md` and `policies/work-item-dor.md` live and API-served +- [x] Outside-originated sections present in both +- [x] Dashboard Policies nav includes both +- [x] No new kinds, no badge engine, no hard enforcement ## References