S10 Wave 0-A — Route retirement inventory
S10 Wave 0-A — Route retirement inventory
Section titled “S10 Wave 0-A — Route retirement inventory”Status: S10 Wave 0 research output (kh-ast-S10 — read-only research, no behavioural impact). Question: Of the 193 routes under
app/api/, how many survive the canonical-pipeline retirement / rename wave (Phase 1 / Phase 2) before R-WP21 OPS-T1 commits 16-24h to a wrapper migration? Headline: 186 survive (96.4 %). 0 retire outright. 4 rename. 3 are conditionally deferred to v1.1. Intelligence cluster verdict: All 20 routes survive unchanged — R-WP21 Wave-A scope (per-route annotations) holds at 20. OPS-T1 scope reduction recommendation: No meaningful reduction available from retirements. The 16-24h estimate stands for the structural rollout; the recommendation indecision-OPS-T1.md(defer (a), ship hybrid (b)+(c)) is reinforced rather than overturned.
§1 Methodology
Section titled “§1 Methodology”1.1 Sources read
Section titled “1.1 Sources read”Main-track repo: /Users/liamj/Documents/development/knowledge-hub (commit 0c7197e1).
| Source doc | Sections covered | Role in this inventory |
|---|---|---|
docs/plans/phase-0-investigation/architecture/07-collapse-list.md | Full doc, §§1-14 | Canonical retire / rename register — six-tag vocabulary [RATIFIED-RETIRE] / [RATIFIED-RENAME] / [RATIFIED-DO-NOT-BUILD] / [DEFERRED-v1.1] / [CONDITIONAL-RETIRE] / [LOCKSTEP-WITH-MIGRATION]. |
docs/specs/id-31-canonical-pipeline-implementation-plan/PLAN.md | §1 methodology, §2 task list, §3 dependency graph, §4.4 T4 procurement, §4.5 T5 digest rename, §6 drift items disposition, §7 STILL-OPEN items NOT in plan | Implementation-phase decomposition; identifies the renames that land in T2 (combined-PR) + T4 (procurement code rename) + T5 (digest code rename). |
docs/reference/project-plan.md | §3 phase overview, §4 Phase 0, §5 Phase 1, §6 Phase 2, §8 Phase 4 v1.1 deferred | Cross-phase context — confirms Phase 1 implementation lives in PLAN.md; Phase 2 = procurement application; Phase 4 = v1.1 deferred. |
docs/plans/phase-0-investigation/0.9-decision-graph.md | §11.1-§11.5 ratification register + grep for “app/api”, “route” | Provides ratification IDs for the rename direction (Q5.3, Q5.4 for digest; Q-OQR1-02 for procurement umbrella). No additional route-level retirements found beyond what 07-collapse-list.md carries. |
docs/plans/phase-0-investigation/architecture/02-data-flow.md | Lines 42, 165, 251-265 (P7 upload + diff-UI scope) | Confirms /api/upload/route.ts retained per N5 Option α; confirms diff-UI scope RATIFIED-S243 — RETAINED for v1, markdown-first (re-pointed to markdown sidecar; was interim [DEFERRED-v1.1]) per PLAN.md §7 item 2. The route still SURVIVES in v1 (1 of 4 diff-UI surface files is an API route). |
docs/plans/phase-0-investigation/architecture/04-workspace-types.md | Lines 165, 213 (kb_section code cleanup) | Confirms /api/workspaces/route.ts retained — code-only touch (remove kb_section CHECK value, no path change). |
docs/plans/phase-0-investigation/architecture/06-mcp-tooling.md | Line 30 (MCP transport) | Confirms /api/mcp/[transport]/route.ts retained — KH MCP server endpoint. |
docs/specs/id-16-ast-dataflow-tool/type-safety-pipeline/decision-OPS-T1.md | Full doc | Provides the 37 fetcher-only interfaces / 47 call sites / 20-route intelligence concentration that R-WP21 hinges on. |
docs/generated/type-drift-baseline.json | Full (37 entries) | Per-interface backing for the OPS-T1 decision input. |
1.2 How the 193 routes were enumerated
Section titled “1.2 How the 193 routes were enumerated”Command in the ast-dataflow worktree at commit 0c7197e1:
find app/api -name 'route.ts' | sortReturns 193 paths. Cluster grouping uses the first path segment under app/api/ (e.g. app/api/intelligence/workspaces/[id]/route.ts → cluster intelligence). 44 clusters in total. The per-cluster counts sum to 193 (verified wc -l).
1.3 Categorisation rules
Section titled “1.3 Categorisation rules”Each route is assigned exactly one of:
| Tag | Definition |
|---|---|
| RETIRE | Route deletes from the codebase. Maps to [RATIFIED-RETIRE] in 07-collapse-list.md. |
| RENAME | Route path changes. File moves under a different cluster directory. Maps to [RATIFIED-RENAME]. Code-only renames inside the route file (no path change) are SURVIVE-UNCHANGED. |
| SURVIVE-UNCHANGED | Route path stays. The file may receive code edits during the migration (e.g. kb_section value drop, project_id → workspace_id parameter rename) but the public URL is unchanged. |
| DEFERRED-v1.1 | Route retains in v1; retire scope deferred per [DEFERRED-v1.1] per Liam S240 ratification. Counted separately because for R-WP21 scoping purposes these routes WILL receive defineRoute() wrapping in v1. |
| UNCERTAIN | Source docs reference the route but disposition is unclear. |
Important nuance. “Route survives” in this inventory means the file at app/api/<path>/route.ts continues to exist with that path post-migration. Routes whose handler bodies are heavily refactored (e.g. switching from custom extraction to cocoindex source binding) but whose URLs persist count as SURVIVE-UNCHANGED — the path-shape is what matters for the defineRoute() wrapper migration. R-WP21 OPS-T1 cares about routes as compile-time surfaces, not handler implementations.
1.4 Reference: ratification-source map
Section titled “1.4 Reference: ratification-source map”| Citation key | Source | Ratification |
|---|---|---|
07-collapse-list §6 row 1 | 07-collapse-list.md lines 186 | /api/digest/** → /api/change-reports/** [RATIFIED-RENAME] — Q5.4 + Q-OQR1-16 combined-PR component 7 |
07-collapse-list §8 row 2 | 07-collapse-list.md line 216 | /api/upload/route.ts [CONDITIONAL-RETIRE] pending 02-data-flow.md binding |
02-data-flow.md §2.1 N5 RESOLVED | 02-data-flow.md line 42 | Upload route RESOLVED-RETAIN per N5 Option α (slim-and-keep) |
02-data-flow.md §10.2 | 02-data-flow.md lines 251-265 | Diff-UI 4 routes [DEFERRED-v1.1] per Liam S240 ratification |
0.9-decision-graph.md §11.3 component 7 | Decision graph line 486 | digests → change_reports is component 7 of Q-OQR1-16 combined PR |
PLAN.md §4.5 T5 | PLAN.md lines 214-234 | Digest code rename effort 1 task unit; routes scope explicit |
PLAN.md §4.4 T4 | PLAN.md lines 188-213 | Procurement code rename touches lib/bid/ + components/bid/ + state machine — NOT the /api/bids/** route paths |
§2 Per-cluster survival table
Section titled “§2 Per-cluster survival table”Reading guide: R = RETIRE, N = RENAME, S = SURVIVE-UNCHANGED, D = DEFERRED-v1.1, U = UNCERTAIN. Each row totals across all five buckets to the cluster total.
| Cluster | Total | R | N | S | D | U | Survival % (S + D) |
|---|---|---|---|---|---|---|---|
activity | 1 | 0 | 0 | 1 | 0 | 0 | 100 % |
admin | 21 | 0 | 0 | 21 | 0 | 0 | 100 % |
analytics | 1 | 0 | 0 | 1 | 0 | 0 | 100 % |
bids | 29 | 0 | 0 | 29 | 0 | 0 | 100 % |
certifications | 1 | 0 | 0 | 1 | 0 | 0 | 100 % |
content-owners | 2 | 0 | 0 | 2 | 0 | 0 | 100 % |
content-suggestions | 1 | 0 | 0 | 1 | 0 | 0 | 100 % |
coverage | 6 | 0 | 0 | 6 | 0 | 0 | 100 % |
cron | 9 | 0 | 0 | 9 | 0 | 0 | 100 % |
dashboard | 1 | 0 | 0 | 1 | 0 | 0 | 100 % |
dedup | 1 | 0 | 0 | 1 | 0 | 0 | 100 % |
digest | 4 | 0 | 4 | 0 | 0 | 0 | 100 % |
embed | 1 | 0 | 0 | 1 | 0 | 0 | 100 % |
entities | 7 | 0 | 0 | 7 | 0 | 0 | 100 % |
extract | 1 | 0 | 0 | 1 | 0 | 0 | 100 % |
feeds | 2 | 0 | 0 | 2 | 0 | 0 | 100 % |
freshness | 2 | 0 | 0 | 2 | 0 | 0 | 100 % |
governance | 2 | 0 | 0 | 2 | 0 | 0 | 100 % |
guides | 4 | 0 | 0 | 4 | 0 | 0 | 100 % |
health | 1 | 0 | 0 | 1 | 0 | 0 | 100 % |
ingest | 2 | 0 | 0 | 2 | 0 | 0 | 100 % |
insights | 1 | 0 | 0 | 1 | 0 | 0 | 100 % |
intelligence | 20 | 0 | 0 | 20 | 0 | 0 | 100 % |
items | 19 | 0 | 0 | 19 | 0 | 0 | 100 % |
jobs | 2 | 0 | 0 | 2 | 0 | 0 | 100 % |
layers | 3 | 0 | 0 | 3 | 0 | 0 | 100 % |
mcp | 1 | 0 | 0 | 1 | 0 | 0 | 100 % |
notifications | 3 | 0 | 0 | 3 | 0 | 0 | 100 % |
oauth | 3 | 0 | 0 | 3 | 0 | 0 | 100 % |
organisation | 1 | 0 | 0 | 1 | 0 | 0 | 100 % |
pipeline-runs | 2 | 0 | 0 | 2 | 0 | 0 | 100 % |
plugin | 1 | 0 | 0 | 1 | 0 | 0 | 100 % |
provenance | 1 | 0 | 0 | 1 | 0 | 0 | 100 % |
quality | 2 | 0 | 0 | 2 | 0 | 0 | 100 % |
read-marks | 1 | 0 | 0 | 1 | 0 | 0 | 100 % |
reorient | 1 | 0 | 0 | 1 | 0 | 0 | 100 % |
review | 7 | 0 | 0 | 7 | 0 | 0 | 100 % |
search | 3 | 0 | 0 | 3 | 0 | 0 | 100 % |
source-documents | 4 | 0 | 0 | 3 | 1 | 0 | 100 % (1 D) |
summaries | 1 | 0 | 0 | 1 | 0 | 0 | 100 % |
tags | 8 | 0 | 0 | 8 | 0 | 0 | 100 % |
taxonomy | 5 | 0 | 0 | 5 | 0 | 0 | 100 % |
upload | 1 | 0 | 0 | 1 | 0 | 0 | 100 % |
users | 1 | 0 | 0 | 1 | 0 | 0 | 100 % |
workspaces | 3 | 0 | 0 | 3 | 0 | 0 | 100 % |
| Total | 193 | 0 | 4 | 186 | 1 | 0 | 100 % (incl. v1.1 deferral) |
| Total — survive in v1 path-stable | 193 | 0 | 4 | 186 | — | — | 96.4 % path-unchanged |
2.1 Headline counts
Section titled “2.1 Headline counts”- Routes that retire outright (delete from codebase): 0 (0 %).
- Routes that rename (path change): 4 (
/api/digest/**→/api/change-reports/**) — 2.1 %. - Routes that survive path-unchanged: 186 (96.4 %).
- Routes once flagged for a v1.1 retire decision but present in v1 codebase: 1 (source-documents
[id]/diff/route.ts); the other 3 diff-UI routes referenced in02-data-flow.md§10.2 are page routes / components / lib files, NOT API routes. Onlyapp/api/source-documents/[id]/diff/route.ts(1 of 4) is an API route. Its disposition is now RATIFIED-S243 — RETAINED for v1, markdown-first (was interim[DEFERRED-v1.1]); either way it survives in v1, not retired (see §2.3). - Routes with uncertain disposition: 0.
Survival rate for R-WP21 OPS-T1 scope: 192 of 193 (99.5 %) if we include the v1.1-deferred diff route; 186 of 193 (96.4 %) if we only count routes whose path is path-stable in v1. Either way R-WP21’s 193-route migration scope is essentially unchanged.
2.2 The 4 RENAME routes (digest cluster)
Section titled “2.2 The 4 RENAME routes (digest cluster)”Per 07-collapse-list.md §6 + Q-OQR1-16 combined-PR component 7:
| From | To | Citation |
|---|---|---|
app/api/digest/[id]/route.ts | app/api/change-reports/[id]/route.ts | Q5.4 + PLAN.md §4.5 |
app/api/digest/generate/route.ts | app/api/change-reports/generate/route.ts | Q5.4 + PLAN.md §4.5 |
app/api/digest/latest/route.ts | app/api/change-reports/latest/route.ts | Q5.4 + PLAN.md §4.5 |
app/api/digest/list/route.ts | app/api/change-reports/list/route.ts | Q5.4 + PLAN.md §4.5 |
These 4 routes survive the migration as files but at a new path. R-WP21 OPS-T1 sweeping over all routes covers both pre-rename and post-rename forms (the same handler logic survives). The rename is [LOCKSTEP-WITH-MIGRATION] with the DB digests → change_reports table rename, landing in T2 combined PR + T5 code sweep per PLAN.md §4.5.
2.3 The diff-UI route (RETAINED-S243, markdown-first)
Section titled “2.3 The diff-UI route (RETAINED-S243, markdown-first)”app/api/source-documents/[id]/diff/route.ts — per 02-data-flow.md §10.2 the diff-UI scope is RATIFIED-S243 — RETAINED for v1, markdown-first (superseding the interim S240 [DEFERRED-v1.1] framing). The route persists in v1 (no removal); it is re-pointed from the source_document_diffs substrate to markdown sidecar revision comparison, landing as the Diff-UI sidecar re-point sub-task in PLAN.md T9 (§7 item 2). It is not retired and not deferred.
For R-WP21 scoping purposes this is SURVIVE in v1 either way — the route file remains and would receive defineRoute() if the wrapper migration ran (so the 192/193 and 186/193 survival counts above are unaffected by the status correction).
2.4 What about the /api/bids/** cluster?
Section titled “2.4 What about the /api/bids/** cluster?”The procurement umbrella per [RATIFIED-RENAME] per Q-OQR1-02 renames the backend code (lib/bid/ → lib/procurement/, BID_STATES → PROCUREMENT_WORKFLOW_STATES, bid_workspaces table → procurement_workspaces, BidState TS type, MCP tool names like list_active_bids → list_active_procurement).
Searched 07-collapse-list.md (full doc) and PLAN.md §4.4 T4 (full subsection) for “/api/bids” or “app/api/bids” — zero matches. PLAN.md §4.4 acceptance criteria target lib/bid/, BID_STATES, bid_workspaces, project_id, and components/bid/ — never the public route paths.
The 29 /api/bids/** routes therefore SURVIVE-UNCHANGED in path. Their handler implementations will be refactored heavily (e.g. importing from @/lib/procurement instead of @/lib/bid, calling procurementWorkflow instead of bidStateMachine) but the URL contract is preserved. Per CLAUDE.md “‘Change Reports’ not ‘Digest’” gotcha pattern: backend names migrate; public URLs are preserved unless a Liam ratification explicitly says otherwise.
This is a load-bearing observation. If R-WP21 OPS-T1 assumed /api/bids/** would rename to /api/procurement/**, that assumption is unsupported by 07-collapse-list.md or PLAN.md. The path-rename, if it happens, would need a separate Liam ratification (the precedent is the digest rename per Q5.4).
2.5 What about /api/intelligence/**?
Section titled “2.5 What about /api/intelligence/**?”The intelligence application_type is RATIFIED-S235 (per 07-collapse-list.md §3.1 row 1 — intelligence is one of the three workspaces.type values being migrated to application_type_id FK; intelligence_workspaces is a reserved satellite seat per docs/specs/reserved-workspace-seats/). The intelligence workspace concept is part of v1.
Searched 07-collapse-list.md for “intelligence” — 2 hits, both for lib/intelligence/content-extractor.ts (TS extractor file [RATIFIED-RETIRE] per CX.6) and the workspaces.type CHECK value migration. Zero hits on /api/intelligence/** routes.
The 20 intelligence routes therefore SURVIVE-UNCHANGED. This is the cluster R-WP21 Wave-A targets (per decision-OPS-T1.md subsystem density table — 20 fetcher-only interfaces, 54 % of the 37-row baseline).
2.6 What about /api/upload?
Section titled “2.6 What about /api/upload?”The route is flagged [CONDITIONAL-RETIRE] in 07-collapse-list.md §8 row 2 pending 02-data-flow.md resolution. That resolution is now landed: per 02-data-flow.md §2.1 (line 42) the upload route is retained under Option α (slim-and-keep) as the HITL manual-upload entry point. The cocoindex source-binding architecture writes a source_documents row after upload; the route does not duplicate ingest logic.
Final disposition: SURVIVE-UNCHANGED. Codified in PLAN.md §7 row 3: “P7 file-upload route disposition — RESOLVED per N5 per 02-data-flow.md §2.3 (Option α slim-and-keep). CLOSED.”
The route handler will be refactored to fix a silent-fail regression at lines 444-447 (per 02-data-flow.md §6.3) — but the path and verb survive.
§3 Implications for R-WP21 Wave-A’ (defineRoute() 193-route migration)
Section titled “§3 Implications for R-WP21 Wave-A’ (defineRoute() 193-route migration)”3.1 Headline
Section titled “3.1 Headline”Survival rate for the R-WP21 OPS-T1 sweep is 96.4 % path-unchanged + 2.1 % renamed = 98.5 % surviving-in-some-form. The 4 digest renames are not a scope reduction (the wrapper still wraps both pre-rename and post-rename forms — same handler, different filename). The 1 v1.1-deferred diff route is a SURVIVE in v1.
Therefore: R-WP21 OPS-T1 cannot be meaningfully scope-reduced via retirement filtering. The 16-24h estimate stands for whatever fraction of the 193 routes the wrapper migration scope covers. The retirement axis is not a meaningful lever.
3.2 The 16-24h estimate is for what, exactly?
Section titled “3.2 The 16-24h estimate is for what, exactly?”Per decision-OPS-T1.md line 41: “Migrate all ~193 KH routes to consume it. Effort: ~16-24h (2-3 days per the brief).” Coverage at line 42: “Closes Gap 1 at the root for the entire codebase, including the 156 routes that are currently enforced=0 / route-only=2 / fetcher-only=37 / unused=21 (out of ~60 named-interface routes; the other ~133 routes use anonymous payloads or have no client-side type).”
The 16-24h is therefore the cost of migrating all 193 routes to defineRoute(), including the 133 anonymous-payload routes. Retirement-based scope reduction would only shave hours proportional to retired routes — and we have 0 retirements.
3.3 Wave-A’ (193-route migration) — verdict
Section titled “3.3 Wave-A’ (193-route migration) — verdict”No scope reduction available from retirements. The recommendation in decision-OPS-T1.md (defer (a) OPS-T1, ship hybrid (b)+(c)) is reinforced:
- The retirement / rename axis offers ≤ 4 routes of scope reduction (the 4 digest renames are arguably a non-reduction since the file still exists post-rename). That is ~30 min of saved effort on a 16-24h scope — noise.
- The rationale for deferring (a) per
decision-OPS-T1.md§“Why defer (a) OPS-T1” stands: 37 fetcher-only interfaces is not large enough to justify a 3-day diff blast radius when (b) at 8-11h + (c) at 1h closes the existing-debt + regression axes for far less risk.
3.4 Procurement rename interaction
Section titled “3.4 Procurement rename interaction”If Liam ratifies a /api/bids/** → /api/procurement/** rename (currently NOT in any ratified source), it would touch 29 routes — a non-trivial scope change. But since this is not ratified, it does not affect R-WP21 scoping today. R-WP21 should NOT pre-emptively rename or scope-reduce on the assumption that the procurement umbrella will cascade to public routes. The conservative scope is “all 193 routes including all 29 /api/bids/**.”
§4 Implications for R-WP21 Wave-A (intelligence per-route annotations, 20 routes)
Section titled “§4 Implications for R-WP21 Wave-A (intelligence per-route annotations, 20 routes)”4.1 Intelligence cluster verdict
Section titled “4.1 Intelligence cluster verdict”Confirmed survival of all 20 intelligence routes.
The 20 routes under app/api/intelligence/** are not listed in 07-collapse-list.md retire / rename / DO-NOT-BUILD / DEFERRED registers. The intelligence application_type is a v1 capability (per 04-workspace-types.md and reserved-workspace-seats). The intelligence_workspaces satellite is one of the 5 reserved seats landing in T2 combined PR per PLAN.md §4.2. None of the route paths are touched by the procurement umbrella or digest rename.
Per PLAN.md §4.2 T2 acceptance criteria: backfill from existing workspaces.type values must verify cleanly (4 intelligence prod rows per 04-workspace-types.md §2.2). The intelligence application is live data; the routes survive.
4.2 R-WP21 Wave-A scope holds at 20
Section titled “4.2 R-WP21 Wave-A scope holds at 20”The proposed S10 Wave A in decision-OPS-T1.md — “incremental annotations on the intelligence cluster, 20 fetcher-only interfaces under app/api/intelligence/**/route.ts, effort ~4-6h” — is directly executable. No route in this scope retires or renames; every route file targeted by Wave A will exist with the same path post-Phase-1.
The hook pattern uniformity claim (decision-OPS-T1.md line 50: “20 routes share the same hook pattern”) is unchanged. No route in this scope has a handler that gets absorbed into cocoindex or relocated to a different cluster.
4.3 One caveat — handler refactor in T8 / T9 may invalidate annotation work
Section titled “4.3 One caveat — handler refactor in T8 / T9 may invalidate annotation work”PLAN.md §4.8 T8 (cocoindex flow scaffolding) and §4.9 T9 (per-UC write-back) refactor pipeline ingest handlers. Some intelligence routes touch ingestion paths (/api/intelligence/trigger-poll/route.ts, /api/intelligence/workspaces/[id]/sources/[sourceId]/test/route.ts). If T8 changes the response shape of those handlers, the annotations added in Wave A would need to be re-validated.
Mitigation: Wave A targets fetcher-only INTERFACES (the type sites), not handler implementations. The interfaces declared in lib/query/fetchers.ts or types/*.ts are the source of truth; annotating the route handler with Promise<NextResponse<X>> for that interface remains correct even if the handler body is refactored later, provided the response shape stays compatible. If T8 changes the response shape, both the interface and the annotation update together — and that is the point of the annotation (drift becomes a compile error).
So Wave A is safe to ship at S10 with the expectation that T8 / T9 work in later sessions may legitimately update both interface and annotation in lockstep.
§5 Implications for R-WP17 baseline ledger (37 fetcher-only)
Section titled “§5 Implications for R-WP17 baseline ledger (37 fetcher-only)”5.1 Per-interface declaration-site survival
Section titled “5.1 Per-interface declaration-site survival”The 37 fetcher-only entries in docs/generated/type-drift-baseline.json are declared in:
types/*.ts(e.g.types/digest.ts,types/intelligence-refinement.ts,types/review.ts) — not retired per07-collapse-list.md§9.lib/query/fetchers.ts— not retired (TanStack Query exclusively per CLAUDE.md data-fetching rule).hooks/use-*.tsandcomponents/**/*.tsx— not retired.app/api/admin/pipeline-runs/recent/route.ts(PipelineRunsRecentResponsedeclared inline) — this is the ONE entry where the declaration site is itself a route file. The route isadmin/pipeline-runs/recent— SURVIVE-UNCHANGED.
Zero baseline entries are declared in routes that retire. All 37 type declarations survive Phase 1.
5.2 Per-call-site URL prefix survival
Section titled “5.2 Per-call-site URL prefix survival”Per decision-OPS-T1.md §“Empirical picture”, the 47 fetcher call sites map to URL prefixes:
| URL prefix | fetcher-only count | Survival verdict |
|---|---|---|
intelligence | 20 | All survive (§4.1) |
admin | 8 | All survive (no admin routes retire / rename per 07-collapse-list.md) |
review | 5 | All survive |
tags | 3 | All survive |
items | 2 | All survive |
coverage | 2 | All survive |
bids | 2 | All survive in path (handlers refactor in T4) |
source-documents | 1 | Survives in v1 (1 of 4 source-document routes is [DEFERRED-v1.1] per §2.3; the fetcher-only entry is unlikely to be the diff route — to be verified at Wave A dispatch) |
pipeline-runs | 1 | Survives |
notifications | 1 | Survives |
entities | 1 | Survives |
digest | 1 | Renames to change-reports per §2.2. The fetcher in lib/query/fetchers.ts will need to update its URL after T5 lands. |
Net: 36 of 37 baseline rows hit routes with unchanged URLs in v1; 1 row hits a URL that renames (digest → change-reports). The rename is [LOCKSTEP-WITH-MIGRATION] with T5 (PLAN.md §4.5) — when T5 lands, the fetcher URL string updates AND the baseline JSON row’s implicit URL reference updates with it. The interface declaration site (types/digest.ts) is path-stable until T5 also renames it to types/change-reports.ts (per PLAN.md §4.5 subtask 2 implies — though types/digest.ts is not explicitly listed in subtasks; safe to assume it migrates with the rest).
5.3 R-WP17 baseline ledger — verdict
Section titled “5.3 R-WP17 baseline ledger — verdict”The baseline does NOT need to be re-baselined before R-WP21 Wave A. The 20 intelligence call sites are exactly the Wave A scope; the 17 non-intelligence sites are stable.
The 1 digest entry (DigestGenerateResponse per types/digest.ts line 1 of the baseline) WILL need a baseline update post-T5 — either as a path-rename rewrite or as a baseline drop + new baseline entry. This should be tracked as a known T5 follow-up; suggest a ratchet-style update at T5 merge time (analogous to how mcp-fixture-sync.test.ts is updated when MCP tools change per CLAUDE.md testing gotcha).
§6 Recommended OPS-T1 scope reduction
Section titled “§6 Recommended OPS-T1 scope reduction”6.1 Direct answer
Section titled “6.1 Direct answer”No meaningful scope reduction is available from the canonical-pipeline retirement / rename wave. The 193-route OPS-T1 sweep faces 0 retirements, 4 renames (a wash for migration effort), and 1 v1.1 deferral (treated as SURVIVE in v1). The 16-24h estimate in decision-OPS-T1.md stands.
6.2 Recommended OPS-T1 path forward
Section titled “6.2 Recommended OPS-T1 path forward”The recommendation in decision-OPS-T1.md is unchanged and now more confidently supported:
- Wave A (S10): Per-route annotations on the 20 intelligence routes (~4-6h). All routes confirmed surviving — target list is exactly the 20 routes listed in §4 of this report. Reproduce from
find app/api/intelligence -name 'route.ts' | sortif needed; the list is in §2.5. - Wave B (S10 or S11): R-WP17 type-drift CI gate ratchet at 17 (post-Wave-A baseline) or 37 (pre-Wave-A) — ~1h. Pattern:
.github/workflows/schema-parity.yml. - Defer Wave-A’ (OPS-T1 193-route migration) until either (a) the drift surface grows ≥10 interfaces above baseline within two sessions per
decision-OPS-T1.md§“Re-evaluation trigger”, OR (b) Liam ratifies a separate procurement-umbrella public-route rename (which would touch 29 routes simultaneously, potentially creating a critical mass that justifies the structural fix landing in the same PR window).
6.3 If Liam selects (a) OPS-T1 anyway
Section titled “6.3 If Liam selects (a) OPS-T1 anyway”If Liam ratifies (a) at S10 close-out, the scope is all 193 routes with the following sequencing notes:
- Land before T2 combined-PR migration. T2 touches
app/api/workspaces/route.ts(kb_section CHECK cleanup) and may touch others. Pre-T2 migration todefineRoute()reduces merge contention; post-T2 means re-resolving conflicts. - Coordinate with T5 digest rename. The 4 digest routes rename to
/api/change-reports/**as part of T5. OPS-T1 should target the post-rename paths to avoid an interim state where 4 routes exist at both old + new paths. - Coordinate with T4 procurement code rename. The 29
/api/bids/**routes don’t rename in path but their handlers all change imports (lib/bid→lib/procurement). OPS-T1 wrapping these routes should land after T4 to avoid wrapping handlers whose internal call patterns are about to change. - Sequence after T8 cocoindex flow lands. T8 changes ingest handler implementations (e.g.
/api/intelligence/trigger-poll,/api/intelligence/workspaces/[id]/sources/[sourceId]/test). OPS-T1 wrappers added before T8 lands will need updating; wrappers added after T8 are stable.
Combined sequencing constraint: OPS-T1 in (a) form is best scheduled after T4 + T5 + T8 land — i.e. mid-to-late Phase 1. This pushes any Wave-A’ commitment from S10 to S11+ at earliest. The conservative timeline is “S10 ships Wave A (b+c hybrid), reassess (a) at Phase 1 mid-point per the re-evaluation trigger.”
6.4 Target route list for S10 Wave A
Section titled “6.4 Target route list for S10 Wave A”20 routes, all confirmed SURVIVE-UNCHANGED, listed in path order from find app/api/intelligence -name 'route.ts' | sort:
app/api/intelligence/profiles/[id]/route.tsapp/api/intelligence/profiles/route.tsapp/api/intelligence/trigger-poll/route.tsapp/api/intelligence/workspaces/[id]/articles/[articleId]/flag/route.tsapp/api/intelligence/workspaces/[id]/articles/route.tsapp/api/intelligence/workspaces/[id]/flags/analyse/route.tsapp/api/intelligence/workspaces/[id]/flags/resolve/route.tsapp/api/intelligence/workspaces/[id]/flags/route.tsapp/api/intelligence/workspaces/[id]/health/route.tsapp/api/intelligence/workspaces/[id]/metrics/prompt-performance/route.tsapp/api/intelligence/workspaces/[id]/metrics/route.tsapp/api/intelligence/workspaces/[id]/metrics/trend/route.tsapp/api/intelligence/workspaces/[id]/prompts/preview/route.tsapp/api/intelligence/workspaces/[id]/prompts/route.tsapp/api/intelligence/workspaces/[id]/route.tsapp/api/intelligence/workspaces/[id]/seed-starter-pack/route.tsapp/api/intelligence/workspaces/[id]/sources/[sourceId]/route.tsapp/api/intelligence/workspaces/[id]/sources/[sourceId]/test/route.tsapp/api/intelligence/workspaces/[id]/sources/route.tsapp/api/intelligence/workspaces/route.tsThis is the executable target for R-WP21 Wave A.
§7 Limitations + open questions
Section titled “§7 Limitations + open questions”7.1 Limitations
Section titled “7.1 Limitations”- Source-doc coverage: This inventory cross-references the 4 primary docs in §1.1. It does NOT do a comprehensive grep across all
.planning/.archive/historical specs. PerCLAUDE.mdHistorical planning convention, archived docs are point-in-time snapshots and not load-bearing for current ratification scope. The 4 primary docs are the authoritative current state. - Heuristic for
/api/bids/**: §2.4 concludes the 29 bids routes SURVIVE-UNCHANGED based on the absence of any explicit rename in07-collapse-list.md§6 orPLAN.md§4.4. If a future Liam ratification adds a/api/bids/**→/api/procurement/**rename, the survival count for the bids cluster drops from 29 to 0 (RENAME) and the inventory total to 156 SURVIVE + 33 RENAME + 4 (digest) RENAME = 156 / 193 path-unchanged (80.8 %). The recommendation in §6 would still stand because RENAME ≠ retire from R-WP21’s perspective. - Handler-implementation churn ignored: This inventory tracks route paths, not handler bodies. Many surviving routes will receive substantial handler refactors during T4 / T5 / T7 / T8 / T9 / T10. R-WP21 OPS-T1 cares about compile-time interface enforcement, which is orthogonal to handler implementation — so this is intentional, but it means a downstream consumer of this report should not interpret “SURVIVE-UNCHANGED” as “no work needed.”
7.2 Open questions
Section titled “7.2 Open questions”PipelineRunsRecentResponsedeclaration site: declared inline atapp/api/admin/pipeline-runs/recent/route.ts(per baseline JSON line 60). Wave A annotation work may want to migrate this totypes/pipeline-runs.tsfor symmetry with the other 36 entries. Not a retirement-inventory question, but flagged here so Wave A scoping picks it up.source-documentscluster fetcher: Of the 4 source-documents routes, 1 is[DEFERRED-v1.1]([id]/diff/route.ts). The single source-documents entry in the OPS-T1 fetcher-only baseline (SendToReviewResultdeclared athooks/use-diff-review.tsline 15 of baseline JSON) hits/api/source-documents/[id]/send-to-review/route.ts(SURVIVE-UNCHANGED), not the diff route. Confirmed by name match — no scope adjustment needed.- Digest rename timing for R-WP17 baseline: Should the type-drift baseline JSON entry for
DigestGenerateResponse(currently declared attypes/digest.ts) be path-updated at the same commit that T5 renames the directory, or kept as a hash-driven baseline that re-baselines automatically on diff? Decision deferred to T5 dispatch; suggest reviewing at that time.
7.3 Suggested follow-ups (not blocking R-WP21 Wave A)
Section titled “7.3 Suggested follow-ups (not blocking R-WP21 Wave A)”- After T5 lands (digest → change-reports rename), re-baseline
docs/generated/type-drift-baseline.jsonto reflect path moves. - After T4 lands (procurement code rename), confirm
/api/bids/**route survival assumption holds. If a public-route rename was inadvertently included in T4 scope, treat the 29 routes as RENAME and re-run R-WP17 detection. - Add a periodic re-run of this retirement inventory (annual or per-phase-close) — the canonical-pipeline retirement landscape is fluid until Phase 1 fully ships.
§8 Provenance
Section titled “§8 Provenance”| Source | Used for | Date |
|---|---|---|
docs/plans/phase-0-investigation/architecture/07-collapse-list.md | Canonical retirement / rename register; six-tag vocabulary | 14/05/2026 (S239 Wave 1) |
docs/specs/id-31-canonical-pipeline-implementation-plan/PLAN.md | Phase 1 decomposition; T4 / T5 / T8 / T9 scope details | 18/05/2026 (S241 draft) |
docs/reference/project-plan.md | Phase model; v1.1 deferred items | 18/05/2026 (S241) |
docs/plans/phase-0-investigation/0.9-decision-graph.md | §11 ratification register | 14/05/2026 (S237 close) |
docs/plans/phase-0-investigation/architecture/02-data-flow.md | P7 upload route N5 resolution; diff-UI deferral | 16/05/2026 (S240 Wave 2) |
docs/plans/phase-0-investigation/architecture/04-workspace-types.md | kb_section code cleanup scope | 16/05/2026 (S240) |
docs/plans/phase-0-investigation/architecture/06-mcp-tooling.md | KH MCP transport route | 16/05/2026 (S240 Theme F) |
docs/specs/id-16-ast-dataflow-tool/type-safety-pipeline/decision-OPS-T1.md | OPS-T1 options; intelligence-cluster subsystem density | 18/05/2026 (kh-ast-S9) |
docs/generated/type-drift-baseline.json | 37 fetcher-only interfaces baseline | 18/05/2026 (kh-ast-S9) |
find app/api -name 'route.ts' (commit 0c7197e1) | 193-route enumeration | 18/05/2026 (this session) |
End of inventory. This is a read-only research output. No source files are modified by this report. R-WP21 ratification path is unchanged: the recommendation in decision-OPS-T1.md (hybrid (b)+(c), defer (a)) is reinforced. S10 Wave A executable target = the 20 intelligence routes listed in §6.4.