feat(STATE-WP-0079): retire the suggestion-backlog surface (slice E1)
History is archived fleet-side, so the read surface has no remaining job. - api/routers/suggestions.py: whole prefix 410s with a pointer to intake and to the archive; the router drops from 176 lines to a stub - mcp_server: the 6 suggestion tools removed outright rather than stubbed -- a retired tool that still appears in the tool list costs every agent session context on every call, which is the opposite of retiring it - write_idempotency: 5 /suggestions rules dropped - dashboard: suggestions.md deleted, nav entry removed, reference.md and wsjf-triage.md updated; docs/suggestions.md rewritten as archive pointer - tests: two tests pinned the old read-live behaviour and now pin the retirement contract instead Tables stay: they are retire/archive in SHR-INV-0001 and are captured by the final dump at T06. Untouched, and worth knowing during cutover: ui-feedback.md / todo.md 'suggestions' are Shift+click dashboard feedback backed by technical_debt, a different entity that shares the word. E3 (dashboard-meta) is that page; its owner is state-hub-until-cutover so it retires at the T06 window, not now. Full suite 612 passed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
parent
98af485cd5
commit
fb363b37d3
13 changed files with 148 additions and 447 deletions
|
|
@ -1,80 +1,61 @@
|
|||
---
|
||||
title: Suggestions (legacy) — Reference
|
||||
title: Suggestions (archived) — Reference
|
||||
---
|
||||
|
||||
# Suggestions (legacy) — Reference
|
||||
# Suggestions (archived) — Reference
|
||||
|
||||
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.
|
||||
The **suggestion** entity is **retired**. It predates the fleet **work-record**
|
||||
model. Gated needs, findings, and unvetted sparks are recorded as **intake**
|
||||
work records (`kind: intake`).
|
||||
|
||||
| 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) |
|
||||
| **Archived record** | `the-custodian/docs/archived-suggestion-backlog.md` |
|
||||
|
||||
Umbrella: [Work Records](/docs/work-records).
|
||||
|
||||
---
|
||||
|
||||
## What still exists
|
||||
## What happened
|
||||
|
||||
| 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 |
|
||||
The suggestion backlog was a demand-weighted queue: agents that hit an unmet
|
||||
need raised a suggestion, repeat encounters bumped its relevance, and WSJF
|
||||
scoring ordered what to build. Intake covers the same discovery step inside the
|
||||
work-record framework rather than beside it.
|
||||
|
||||
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.
|
||||
| Date | Step |
|
||||
|------|------|
|
||||
| 2026-07-21 | Mutations retired (`CUST-WP-0061-T06`) — every write returns HTTP 410. Reads kept live so the history stayed reachable. |
|
||||
| 2026-08-20 | History archived to `the-custodian`; read routes, MCP tools, and this dashboard page retired (`STATE-WP-0079-T05`, slice E1). |
|
||||
|
||||
---
|
||||
Every route under `/suggestions` now returns **HTTP 410** with a pointer to
|
||||
intake and to the archive.
|
||||
|
||||
## Former stage model (historical)
|
||||
## The archived record
|
||||
|
||||
While mutations were live, stages were:
|
||||
All 10 suggestions, 10 notes, and 5 relevance bumps are preserved in
|
||||
`the-custodian/docs/archived-suggestion-backlog.md`, with each entry's origin,
|
||||
WSJF inputs, and migration target.
|
||||
|
||||
| Stage | Meaning |
|
||||
|-------|---------|
|
||||
| `suggestion` | Recorded need, not yet vetted |
|
||||
| `requirement` | Vetted with structured fields and notes |
|
||||
| `promoted` | Became a real `Task` (`promoted_task_id` set) |
|
||||
| `declined` | Rejected; terminal |
|
||||
Every entry was closed as `declined` during the intake migration and **none was
|
||||
promoted** — the backlog was drained deliberately, not abandoned. The per-entry
|
||||
notes name each one's successor intake (`CUST-IN-0001`, `CUST-IN-0002`, …).
|
||||
|
||||
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.
|
||||
The record lives in `the-custodian` rather than here because State Hub is being
|
||||
archived under `STATE-WP-0079`; a record kept inside the component it documents
|
||||
disappears with it.
|
||||
|
||||
---
|
||||
## What is not retired
|
||||
|
||||
## Mapping to intake
|
||||
**Dashboard UI feedback** — the Shift+click suggestions on
|
||||
[Todo](/docs/todo) and the UI Feedback page — is a *different* entity backed by
|
||||
`technical_debt`, and is unaffected. The shared word is a coincidence of naming.
|
||||
|
||||
| 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` |
|
||||
## Data
|
||||
|
||||
Do not open new work through the suggestion API.
|
||||
|
||||
---
|
||||
|
||||
## Related pages
|
||||
|
||||
- [Intakes](/docs/intakes) — current entity and lifecycle
|
||||
- [Work Records](/docs/work-records) — kind registry
|
||||
- [WSJF Triage](/docs/wsjf-triage) — daily advisory triage (workplan-oriented)
|
||||
|
||||
---
|
||||
|
||||
*Suggestion mutations are retired by design (CUST-WP-0061). Intake is a fresh
|
||||
entity, not a rename of the suggestions table.*
|
||||
The `suggestions`, `suggestion_notes`, and `suggestion_relevance_bumps` tables
|
||||
are intentionally still present. They are `retire`/`archive` in `SHR-INV-0001`
|
||||
and are captured by the final dump at `STATE-WP-0079-T06`; dropping them ahead
|
||||
of that dump would remove data for no gain.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue