From 0ab3e359ce1e65b56585273ca03c0343d838f9f9 Mon Sep 17 00:00:00 2001 From: codex Date: Thu, 20 Aug 2026 07:28:36 +0200 Subject: [PATCH 1/2] docs: journal of retired legacy interfaces Fleet-level record of legacy interfaces retired under the State Hub retirement program. Kept here rather than in state-hub because state-hub is being archived -- once it is read-only its legacy-meter tables stop being queryable in practice, and this needs to outlive that. Records the 15 workstream->workplan aliases retired on 2026-08-20 under STATE-WP-0079-T05 slice E2, the one retired earlier, and the 4 still held with the reason each is held. Documents the retirement standard including the volume-scaled quiet ladder and why it exists. Co-Authored-By: Claude Opus 5 --- docs/retired-legacy-interfaces.md | 94 +++++++++++++++++++++++++++++++ 1 file changed, 94 insertions(+) create mode 100644 docs/retired-legacy-interfaces.md diff --git a/docs/retired-legacy-interfaces.md b/docs/retired-legacy-interfaces.md new file mode 100644 index 0000000..c1d2e3e --- /dev/null +++ b/docs/retired-legacy-interfaces.md @@ -0,0 +1,94 @@ +# Retired legacy interfaces — journal + +**Scope:** fleet-wide record of legacy interfaces retired under the State Hub +retirement program. +**Maintained here, not in `state-hub`,** because `state-hub` is being archived +and this record must outlive it. Once the hub is read-only its legacy-meter +tables stop being queryable in practice; this file is the durable reference. + +**Source of record while the hub is live:** `state-hub` legacy-meter +(`/legacy-meter/interfaces`), evidence captures in +`state-hub/docs/evidence/legacy-meter-weekly-review-*.json`. +**Programme:** `STATE-WP-0069` (terminology retirement), `STATE-WP-0079-T05` +(retire legacy surfaces), slice E2 in +`state-hub/docs/retirement-cutover-slice-plan.md`. + +## Retirement standard + +An interface is retired only when all of the following hold: + +1. A replacement exists (`replacement_ref`) and is marked verified. +2. No manual hold. +3. Zero calls in a **7-day** review window. +4. Silence since `last_seen_at` of at least a **volume-scaled quiet period** — + 7 days under 100 all-time calls, 30 days under 10 000, 60 days above. + +Rule 4 exists because a clean window only proves silence *for that window*. A +heavily-used interface can have an infrequent caller that falls outside it. This +was not hypothetical: before the rule was added, captures ran over an 8-hour +band rather than a week, and interfaces with live callers were reported as +retirement candidates. + +Implementation: `RETIREMENT_QUIET_LADDER` in +`state-hub/api/services/legacy_meter.py`. + +## Retired 2026-08-20 — workstream→workplan terminology aliases (15) + +Slice E2, `STATE-WP-0079-T05`. All replaced by the `workplan` spelling of the +same surface. + +| Interface | Kind | Replacement | Legacy since | Retired | All-time calls | Last seen | +| --- | --- | --- | --- | --- | --- | --- | +| `mcp:create_workstream` | mcp_tool | `create_workplan` | 2026-07-10 | 2026-08-20 | 2 | 2026-07-10 | +| `mcp:list_workstreams` | mcp_tool | `list_workplans` | 2026-07-10 | 2026-08-20 | 2 | 2026-07-10 | +| `mcp:update_workstream` | mcp_tool | `update_workplan` | 2026-07-10 | 2026-08-20 | 0 | — | +| `mcp:update_workstream_status` | mcp_tool | `update_workplan_status` | 2026-07-10 | 2026-08-20 | 0 | — | +| `state://workstreams/{topic_slug}` | mcp_tool | `state://workplans/{topic_slug}` | 2026-07-10 | 2026-08-20 | 1 | 2026-07-10 | +| `rest_api:DELETE /workstreams/{workstream_id}` | rest_api | `/workplans/{workplan_id}` | 2026-06-06 | 2026-08-20 | 1 | 2026-06-06 | +| `rest_api:GET /decisions/?workstream_id` | rest_api | `/decisions/?workplan_id=` | 2026-07-09 | 2026-08-20 | 1 | 2026-07-09 | +| `rest_api:GET /progress/?workstream_id` | rest_api | `/progress/?workplan_id=` | 2026-07-13 | 2026-08-20 | 2 | 2026-08-12 | +| `rest_api:GET /workstreams/workplan-index` | rest_api | `/workplans/index` | 2026-06-04 | 2026-08-20 | 30 | 2026-07-03 | +| `rest_api:PATCH /workstreams/{workstream_id}` | rest_api | `/workplans/{workplan_id}` | 2026-06-04 | 2026-08-20 | 571 | 2026-07-08 | +| `rest_api:POST /decisions/ workstream_id` | rest_api | `POST /decisions/ with workplan_id` | 2026-07-09 | 2026-08-20 | 3 | 2026-07-09 | +| `rest_api:POST /progress/ workstream_id` | rest_api | `POST /progress/ with workplan_id` | 2026-07-08 | 2026-08-20 | 14 | 2026-07-10 | +| `rest_api:POST /tasks/ workstream_id` | rest_api | `POST /tasks/ with workplan_id` | 2026-07-08 | 2026-08-20 | 5 | 2026-07-08 | +| `rest_api:POST /workstreams/` | rest_api | `/workplans/` | 2026-06-04 | 2026-08-20 | 824 | 2026-07-08 | +| `rest_api:POST /workstreams/{workstream_id}/dependencies/` | rest_api | `/workplans/{workplan_id}/dependencies/` | 2026-06-04 | 2026-08-20 | 4,971 | 2026-07-01 | + +## Retired earlier (1) + +| Interface | Kind | Replacement | Legacy since | Retired | All-time calls | Last seen | +| --- | --- | --- | --- | --- | --- | --- | +| `event_subject:org.statehub.workstream.completed` | event_subject | `org.statehub.workplan.completed` | 2026-06-04 | 2026-07-08 | 255 | 2026-07-08 | + +## Still legacy — held, not retired (4) + +These carry the `workstream` spelling but did **not** meet the standard on +2026-08-20. They are the three six-figure read paths plus one with live traffic +— the set where a premature retirement would do the most damage. + +| Interface | Replacement | All-time calls | Last seen | Held because | +| --- | --- | --- | --- | --- | +| `rest_api:GET /workstreams/{workstream_id}` | `/workplans/{workplan_id}` | 511,406 | 2026-07-31 | quiet 19d of 60d required for 511406 all-time call(s) | +| `rest_api:GET /workstreams/{workstream_id}/dependencies/` | `/workplans/{workplan_id}/dependencies/` | 255,865 | 2026-07-08 | quiet 42d of 60d required for 255865 all-time call(s) | +| `rest_api:GET /workstreams/` | `/workplans/` | 144,086 | 2026-08-10 | quiet 9d of 60d required for 144086 all-time call(s) | +| `rest_api:GET /tasks/?workstream_id` | `/tasks/?workplan_id=` | 595 | 2026-08-19 | 5 call(s) in review window | + +The quiet counters run on their own. Re-capture before deciding — the ladder is +evaluated at review time, so an old capture is not evidence for a later +retirement. + +## Updating this journal + +After each retirement round in `state-hub`: + +```bash +cd ~/state-hub +uv run python scripts/capture_legacy_meter_evidence.py --retire-keys "" +``` + +Then append a dated section here with the same columns. Keep retired rows +forever — the point of the journal is that a reader in 2027 can tell what +`GET /workstreams/` was, what replaced it, and on what evidence it was removed. + +*Last updated: 2026-08-20* From c72fd7cfa4a6faba812285938a911d723d1dcc15 Mon Sep 17 00:00:00 2001 From: codex Date: Thu, 20 Aug 2026 07:41:42 +0200 Subject: [PATCH 2/2] docs: archived record of the State Hub suggestion backlog Complete contents of the suggestion-backlog capability at retirement: 10 suggestions, 10 notes, 5 relevance bumps, raised 2026-07-06 to 2026-07-16. All closed as declined in the 2026-07-21 intake migration; none promoted. Kept here rather than in state-hub because state-hub is being archived and this record must outlive it -- same reasoning as retired-legacy-interfaces.md. Mutations already 410 since CUST-WP-0061-T06; reads were held open only to keep this history reachable. This file is what makes removing them safe (slice E1, STATE-WP-0079-T05). Co-Authored-By: Claude Opus 5 --- docs/archived-suggestion-backlog.md | 155 ++++++++++++++++++++++++++++ 1 file changed, 155 insertions(+) create mode 100644 docs/archived-suggestion-backlog.md diff --git a/docs/archived-suggestion-backlog.md b/docs/archived-suggestion-backlog.md new file mode 100644 index 0000000..06812c3 --- /dev/null +++ b/docs/archived-suggestion-backlog.md @@ -0,0 +1,155 @@ +# Suggestion backlog — archived record + +**Scope:** the complete contents of the State Hub `suggestion-backlog` capability +at retirement — **10 suggestions, 10 notes, 5 relevance bumps**, +raised 2026-07-06 to 2026-07-16. + +**Maintained here, not in `state-hub`,** for the same reason as +[`retired-legacy-interfaces.md`](retired-legacy-interfaces.md): State Hub is +being archived and this record must outlive it. + +**Programme:** slice E1 in `state-hub/docs/retirement-cutover-slice-plan.md`, +`STATE-WP-0079-T05`. Inventory: `SHR-INV-0001`, `suggestion-backlog`, +disposition `retire` → `archive`. + +## What this was, and what replaced it + +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. It was superseded by the **intake** work-record +entity, which covers the same discovery step inside the work-record framework +rather than beside it. + +Mutations were retired 2026-07-21 under `CUST-WP-0061-T06` — every write path +returns HTTP 410 pointing at `POST /intakes/`. Reads were kept live so the +historical record stayed reachable. This file is what makes removing those reads +safe. + +Migration context: [`intake-legacy-suggestions-migration.md`](../intake-legacy-suggestions-migration.md), +`canon/standards/work-record-types_v0.1.md`. + +## Disposition + +**All 10 closed as `declined`, none promoted** — every `promoted_task_id` +is null. They were declined together in the 2026-07-21 close-out and migrated to +intake records, so the backlog was drained deliberately rather than abandoned. +The per-entry notes below carry each one's migration target. + +| Origin | Suggestions | +| --- | --- | +| `WARDEN-WP-0012` | 7 | +| `STATE-WP-0069` | 1 | +| `STATE-WP-0073` | 1 | +| *(unset)* | 1 | + +## The entries + +### Issue-core ingestion API key OpenBao path + +**Domain:** `infotech` · **Origin:** `WARDEN-WP-0012` / `issue-core-ingestion-api-key` +**Stage:** `declined` · **Raised:** 2026-07-06 · **Closed:** 2026-07-20 +**Relevance:** 1 over 1 event(s), 1 bump(s) · **WSJF inputs:** value 4.0, size 3.0 + +Gated routing scenario from WARDEN-WP-0012. Owner path not yet shipped; accrues relevance when agents hit this unmet need. + +- *2026-07-20*, custodian (stage `declined`) — One-time close-out (CUST-WP-0061-T06, 2026-07-21): the suggestions table is retired to read-only legacy in favor of the fresh work-record intake entity. Migrated to CUST-IN-0001 in the-custodian/intake-legacy-suggestions-migration.md -- pick it up there. + +### Activity-core issue sink consumer key custody + +**Domain:** `infotech` · **Origin:** `WARDEN-WP-0012` / `activity-core-issue-sink` +**Stage:** `declined` · **Raised:** 2026-07-06 · **Closed:** 2026-07-20 +**Relevance:** 1 over 1 event(s), 1 bump(s) · **WSJF inputs:** value 4.0, size 3.0 + +Gated routing scenario from WARDEN-WP-0012. Owner path not yet shipped; accrues relevance when agents hit this unmet need. + +- *2026-07-20*, custodian (stage `declined`) — One-time close-out (CUST-WP-0061-T06, 2026-07-21): the suggestions table is retired to read-only legacy in favor of the fresh work-record intake entity. Migrated to CUST-IN-0002 in the-custodian/intake-legacy-suggestions-migration.md -- pick it up there. + +### OpenRouter llm-connect OpenBao → K8s Secret path + +**Domain:** `infotech` · **Origin:** `WARDEN-WP-0012` / `openrouter-llm-connect` +**Stage:** `declined` · **Raised:** 2026-07-06 · **Closed:** 2026-07-20 +**Relevance:** 0 over 0 event(s) · **WSJF inputs:** value 4.0, size 3.0 + +Gated routing scenario from WARDEN-WP-0012. Owner path not yet shipped; accrues relevance when agents hit this unmet need. + +- *2026-07-20*, custodian (stage `declined`) — One-time close-out (CUST-WP-0061-T06, 2026-07-21): the suggestions table is retired to read-only legacy in favor of the fresh work-record intake entity. Migrated to CUST-IN-0003 in the-custodian/intake-legacy-suggestions-migration.md -- pick it up there. + +### Object storage STS vending path (NK-WP-0007) + +**Domain:** `infotech` · **Origin:** `WARDEN-WP-0012` / `object-storage-sts` +**Stage:** `declined` · **Raised:** 2026-07-06 · **Closed:** 2026-07-20 +**Relevance:** 0 over 0 event(s) · **WSJF inputs:** value 4.0, size 3.0 + +Gated routing scenario from WARDEN-WP-0012. Owner path not yet shipped; accrues relevance when agents hit this unmet need. + +- *2026-07-20*, custodian (stage `declined`) — One-time close-out (CUST-WP-0061-T06, 2026-07-21): the suggestions table is retired to read-only legacy in favor of the fresh work-record intake entity. Migrated to CUST-IN-0004 in the-custodian/intake-legacy-suggestions-migration.md -- pick it up there. + +### Human OIDC login via key-cape / Keycloak + +**Domain:** `infotech` · **Origin:** `WARDEN-WP-0012` / `human-oidc-login` +**Stage:** `declined` · **Raised:** 2026-07-06 · **Closed:** 2026-07-20 +**Relevance:** 1 over 1 event(s), 1 bump(s) · **WSJF inputs:** value 4.0, size 3.0 + +Gated routing scenario from WARDEN-WP-0012. Owner path not yet shipped; accrues relevance when agents hit this unmet need. + +- *2026-07-20*, custodian (stage `declined`) — One-time close-out (CUST-WP-0061-T06, 2026-07-21): the suggestions table is retired to read-only legacy in favor of the fresh work-record intake entity. Migrated to CUST-IN-0005 in the-custodian/intake-legacy-suggestions-migration.md -- pick it up there. + +### flex-auth policy decision before sensitive action + +**Domain:** `infotech` · **Origin:** `WARDEN-WP-0012` / `flex-auth-resource-check` +**Stage:** `declined` · **Raised:** 2026-07-06 · **Closed:** 2026-07-20 +**Relevance:** 1 over 1 event(s), 1 bump(s) · **WSJF inputs:** value 4.0, size 3.0 + +Gated routing scenario from WARDEN-WP-0012. Owner path not yet shipped; accrues relevance when agents hit this unmet need. + +- *2026-07-20*, custodian (stage `declined`) — One-time close-out (CUST-WP-0061-T06, 2026-07-21): the suggestions table is retired to read-only legacy in favor of the fresh work-record intake entity. Migrated to CUST-IN-0006 in the-custodian/intake-legacy-suggestions-migration.md -- pick it up there. + +### auth_principals sync for host principal deploy + +**Domain:** `infotech` · **Origin:** `WARDEN-WP-0012` / `host-principal-deploy` +**Stage:** `declined` · **Raised:** 2026-07-06 · **Closed:** 2026-07-20 +**Relevance:** 1 over 1 event(s), 1 bump(s) · **WSJF inputs:** value 4.0, size 3.0 + +Gated routing scenario from WARDEN-WP-0012. Owner path not yet shipped; accrues relevance when agents hit this unmet need. + +- *2026-07-20*, custodian (stage `declined`) — One-time close-out (CUST-WP-0061-T06, 2026-07-21): the suggestions table is retired to read-only legacy in favor of the fresh work-record intake entity. Migrated to CUST-IN-0007 in the-custodian/intake-legacy-suggestions-migration.md -- pick it up there. + +### Roll out weekly legacy-meter review on Railiance activity-core + +**Domain:** `financials` · **Origin:** `STATE-WP-0069` / `weekly-legacy-meter-review-railiance-rollout` +**Stage:** `declined` · **Raised:** 2026-07-08 · **Closed:** 2026-07-20 +**Relevance:** 0 over 0 event(s) · **WSJF inputs:** value 4.0, size 2.0 + +**Owner repo:** `railiance-cluster` (cluster reconcile on railiance01; manifests ship from `activity-core`). Deploy the `weekly-legacy-meter-review` ActivityDefinition on railiance01 so STATE-WP-0069 retirement gating receives automated weekly evidence from production activity-core. **Why:** activity-core commit `efa3615` (STATE-WP-0069: schedule weekly legacy-meter review monitoring) adds the definition, resolver (`legacy_meter_weekly_review` → `GET /legacy-meter/weekly-review`), evidence sink (`legacy_meter_weekly_review` progress event), and K8s projection in `k8s/railiance/20-runtime.yaml`. Code is merged; cluster reconcile is pending. **Prereqs:** - activity-core checkout on railiance01 at `efa3615` or later - `actcore-state-hub-bridge` reachable at `127.0.0.1:18000` (State Hub tunnel) - `kubectl` access: `export KUBECONFIG=~/.kube/config-hosteurope` **Rollout (no worker restart):** 1. `kubectl apply -f k8s/railiance/20-runtime.yaml` — updates `actcore-external-activity-definitions` ConfigMap with `weekly-legacy-meter-review.md` 2. Wait ~60s for API pod volume propagation (see `scripts/smoke_admin_sync_no_restart.py`) 3. `kubectl -n activity-core exec deploy/actcore-api -- python3 -c 'import urllib.request; req=urllib.request.Request("http://localhost:8010/admin/sync?definitions=true&schedules=true", method="POST"); print(urllib.request.urlopen(req).read().decode())'` 4. Verify definition `weekly-legacy-meter-review` is enabled in DB and Temporal schedule `30 8 * * 1` Europe/Berlin exists 5. After first Monday 08:30 run: confirm `legacy_meter_weekly_review` progress event on State Hub linked to workplan `923bb94a-d16c-422c-b81e-16328bd7b60c` **References:** `activity-core/docs/runbook.md` (Railiance01 no-restart smoke), `activity-core/k8s/railiance/README.md`, `activity-definitions/weekly-legacy-meter-review.md`. + +- *2026-07-20*, custodian (stage `declined`) — One-time close-out (CUST-WP-0061-T06, 2026-07-21): the suggestions table is retired to read-only legacy in favor of the fresh work-record intake entity. Migrated to CUST-IN-0008 in the-custodian/intake-legacy-suggestions-migration.md -- pick it up there. + +### Rebuild activity-core:railiance01-prod for legacy-meter 8h capture + +**Domain:** `financials` · **Origin:** `STATE-WP-0073` / `legacy-meter-8h-capture-railiance-rollout` +**Stage:** `declined` · **Raised:** 2026-07-09 · **Closed:** 2026-07-20 +**Relevance:** 0 over 0 event(s) · **WSJF inputs:** value 4.0, size 2.0 + +Operator follow-up from STATE-WP-0073: the `legacy-meter-8h-capture` ActivityDefinition and runtime ConfigMap are applied on railiance01, but cluster pods still run a pre-`f41cf14` image — the `legacy_meter_weekly_review` resolver does not pass `hours=8`, so scheduled runs may report a 7-day window instead of the intended 8-hour retirement gate. **Why:** activity-core `f41cf14` adds `hours` through the State Hub resolver, `legacy-meter-8h-capture` cron (`0 */8 * * *` UTC), and progress sink `legacy_meter_8h_capture` for STATE-WP-0070 seven-window gating. WSL crontab captures git evidence correctly; production activity-core needs an image reconcile. **Target repo:** `railiance-cluster` (beachhead image reconcile pattern from RAIL-BS-WP-0010). **Prereqs:** - activity-core checkout ≥ `f41cf14` on railiance01 (`forgejo-remote` — `gitea-remote` may lag) - `export KUBECONFIG=/etc/rancher/k3s/k3s.yaml` - `actcore-state-hub-bridge` / State Hub tunnel healthy **Rollout steps:** 1. On railiance01: `cd ~/activity-core && git pull --ff-only forgejo main` (expect `f41cf14`+) 2. `docker build -t activity-core:railiance01-prod .` 3. `docker save -o /tmp/activity-core-railiance01-prod.tar activity-core:railiance01-prod` 4. `sudo k3s ctr images import /tmp/activity-core-railiance01-prod.tar` 5. Restart only if digest changed: `kubectl -n activity-core rollout restart deploy/actcore-worker deploy/actcore-api deploy/actcore-event-router` 6. Verify in worker pod: `_legacy_meter_weekly_review` source includes `hours` param 7. After next 08:00/16:00/00:00 UTC tick: confirm `legacy_meter_8h_capture` progress on State Hub with `window_label: 8h` and low/zero legacy call counts **References:** `activity-core/k8s/railiance/README.md`, `activity-definitions/legacy-meter-8h-capture.md`, `state-hub/docs/evidence/legacy-meter-delta-20260709.md`, RAIL-BS-WP-0010 image-reconcile pattern. + +- *2026-07-20*, custodian (stage `declined`) — One-time close-out (CUST-WP-0061-T06, 2026-07-21): the suggestions table is retired to read-only legacy in favor of the fresh work-record intake entity. Migrated to CUST-IN-0009 in the-custodian/intake-legacy-suggestions-migration.md -- pick it up there. + +### Reclassify repos and guidance docs to the new sector domain scheme + +**Domain:** `infotech` · **Origin:** *(unset)* +**Stage:** `declined` · **Raised:** 2026-07-16 · **Closed:** 2026-07-20 +**Relevance:** 0 over 0 event(s) · **WSJF inputs:** value 3.0, size 3.0 + +The hub now uses sector-style domains (agents, communication, infotech, financials, ...), but the-custodian's guidance still assumes the seven legacy domains (custodian, railiance, markitect, coulomb_social, personhood, foerster_capabilities, netkingdom) — e.g. Bernd's global CLAUDE.md instructs orientation calls against those slugs. Proposal for the-custodian: (1) publish a legacy→sector mapping, (2) update global/CLAUDE.md orientation guidance to the new scheme, (3) regenerate .repo-classification.yaml for registered repos — binky-control currently warns C-24 (classification missing) and sits under 'infotech' by codex's bootstrap choice; confirm or reassign under the new scheme. Origin: binky-control consistency check C-24 + domain-list mismatch observed 2026-07-16. + +- *2026-07-20*, custodian (stage `declined`) — One-time close-out (CUST-WP-0061-T06, 2026-07-21): the suggestions table is retired to read-only legacy in favor of the fresh work-record intake entity. Migrated to CUST-IN-0010 in the-custodian/intake-legacy-suggestions-migration.md -- pick it up there. + +## Note on the WSJF fields + +`base_value`, `job_size`, `relevance` and `relevance_weight` fed a +cost-of-delay / WSJF ordering computed at read time +(`state-hub/api/services/suggestion_wsjf.py`), never stored. The values above +are therefore inputs, not the ranking the dashboard showed. The ranking is not +reconstructed here — with every entry declined, it has no forward use. + +*Last updated: 2026-08-20*