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
|
|
@ -1,9 +1,44 @@
|
|||
# Demand-Weighted Suggestion Backlog
|
||||
---
|
||||
title: Suggestions (legacy) — Reference
|
||||
---
|
||||
|
||||
The `/suggestions` page shows persisted **gated needs** that are not yet real
|
||||
tasks. Each unmet lookup increments `relevance`, which raises WSJF ranking.
|
||||
# Suggestions (legacy) — Reference
|
||||
|
||||
## Stages
|
||||
The **suggestion** entity is **read-only legacy**. It predates the fleet
|
||||
**work-record** model. Gated needs, findings, and unvetted sparks are recorded
|
||||
as **intake** work records (`kind: intake`), not as suggestions.
|
||||
|
||||
| Use | Path |
|
||||
|-----|------|
|
||||
| **Current** | [Intakes](/docs/intakes) · `POST /intakes/` · MCP `create_intake` |
|
||||
| **Canon** | `the-custodian/canon/standards/work-record-types_v0.1.md` |
|
||||
| **Legacy table** | `GET /suggestions/` (historical rows may remain) |
|
||||
|
||||
Umbrella: [Work Records](/docs/work-records).
|
||||
|
||||
---
|
||||
|
||||
## What still exists
|
||||
|
||||
| Surface | Behaviour today |
|
||||
|---------|-----------------|
|
||||
| `GET /suggestions/` | Lists historical suggestion rows (if any). Ranking query params still exist on the read path. |
|
||||
| `GET /suggestions/{id}` | Read one historical row. |
|
||||
| Mutation routes (`POST /suggestions/`, vet, decline, promote, bump-relevance) | **HTTP 410 Gone** — body points at `/intakes/` and the work-record standard |
|
||||
| MCP `create_suggestion`, `vet_suggestion`, `decline_suggestion`, `promote_suggestion_to_task`, `bump_suggestion_relevance` | Call the retired mutation endpoints; they return 410 |
|
||||
| Dashboard **Suggestions** page | Still polls `GET /suggestions/?rank=wsjf`; useful only for residual history |
|
||||
| `GET /state/summary` → `ranked_suggestions` | Still computed from open suggestion rows; after migration the open set is typically empty |
|
||||
|
||||
Records were not deleted at retirement. Open backlog at cut-over (2026-07-21,
|
||||
CUST-WP-0061-T06) was re-authored as file-backed intakes (with
|
||||
`origin: legacy-suggestion:<uuid>`) and the hub suggestion rows were closed in
|
||||
place so history remained inspectable.
|
||||
|
||||
---
|
||||
|
||||
## Former stage model (historical)
|
||||
|
||||
While mutations were live, stages were:
|
||||
|
||||
| Stage | Meaning |
|
||||
|-------|---------|
|
||||
|
|
@ -12,38 +47,34 @@ tasks. Each unmet lookup increments `relevance`, which raises WSJF ranking.
|
|||
| `promoted` | Became a real `Task` (`promoted_task_id` set) |
|
||||
| `declined` | Rejected; terminal |
|
||||
|
||||
## WSJF projection
|
||||
WSJF ranking used `base_value`, `relevance`, `job_size`, and
|
||||
`relevance_weight`. That ranking applied only to the suggestion table; it is
|
||||
not the intake ranking model.
|
||||
|
||||
```text
|
||||
cost_of_delay = base_value + (relevance_weight × relevance)
|
||||
wsjf = cost_of_delay / job_size
|
||||
```
|
||||
---
|
||||
|
||||
`GET /suggestions?rank=wsjf` returns open suggestions/requirements ordered by
|
||||
score. Promoted and declined entries are excluded unless
|
||||
`include_terminal=true`.
|
||||
## Mapping to intake
|
||||
|
||||
## Sanctioned writes
|
||||
| Suggestion concept | Intake equivalent |
|
||||
|--------------------|-------------------|
|
||||
| Create gated need | `POST /intakes/` / `create_intake` |
|
||||
| Vet | Move toward `vetted` / notes on the intake |
|
||||
| Promote to task | `route_intake` then `statehub promote-intake … --to task` (or workplan / decision / engagement) |
|
||||
| Decline | `close_intake(outcome="declined")` |
|
||||
| Absorbed by existing work | `close_intake(outcome="absorbed")` |
|
||||
| Domain-scoped row | Intake scoped by `topic_id` and/or `workplan_id` and/or `repo_id` |
|
||||
|
||||
MCP and REST:
|
||||
Do not open new work through the suggestion API.
|
||||
|
||||
- `create_suggestion` / `POST /suggestions/`
|
||||
- `vet_suggestion` / `POST /suggestions/{id}/vet`
|
||||
- `decline_suggestion` / `POST /suggestions/{id}/decline`
|
||||
- `promote_suggestion_to_task` / `POST /suggestions/{id}/promote`
|
||||
- `bump_suggestion_relevance` / `POST /suggestions/{id}/bump-relevance`
|
||||
---
|
||||
|
||||
Relevance also bumps automatically when:
|
||||
## Related pages
|
||||
|
||||
- `GET /state/next_steps` surfaces open suggestions
|
||||
- A `CapabilityRequest` matches an open suggestion
|
||||
- [Intakes](/docs/intakes) — current entity and lifecycle
|
||||
- [Work Records](/docs/work-records) — kind registry
|
||||
- [WSJF Triage](/docs/wsjf-triage) — daily advisory triage (workplan-oriented)
|
||||
|
||||
## Daily triage
|
||||
---
|
||||
|
||||
`GET /state/summary` includes `ranked_suggestions` for the activity-core
|
||||
`daily_triage_digest` resolver. See [WSJF Triage](/docs/wsjf-triage).
|
||||
|
||||
## Origin
|
||||
|
||||
Motivated by ops-warden `WARDEN-WP-0012` gated routing scenarios. Example
|
||||
backfill: `scripts/seed_wp0012_suggestions.py`.
|
||||
*Suggestion mutations are retired by design (CUST-WP-0061). Intake is a fresh
|
||||
entity, not a rename of the suggestions table.*
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue