S10 Wave 0-B — Intelligence cluster fate confirmation

S10 Wave 0-B — Intelligence cluster fate confirmation

Date: 18/05/2026 (kh-ast-S10) Status: Wave 0 research output Branch: ast-dataflow-tooling (research baselined against main @ 0c7197e1) Scope: Determine whether the 20 app/api/intelligence/**/route.ts files persist under the canonical-pipeline rewrite, so we can decide whether to invest 4-6h on R-WP21 Wave-A return-type annotations targeting the 54% type-drift in this cluster.

---

§1 Methodology

Cross-referenced seven primary sources in the main-track repo (/Users/liamj/Documents/development/knowledge-hub/):

1. docs/specs/reserved-workspace-seats/PRODUCT.md (NEW-S240) — does an intelligence_workspaces seat exist post-Phase 1?
2. docs/specs/reserved-workspace-seats/TECH.md (NEW-S240) — what columns land at v1 apply time?
3. docs/plans/phase-0-investigation/architecture/07-collapse-list.md (S239 Wave 1 canonical) — what’s tagged [RATIFIED-RETIRE] or [RATIFIED-RENAME] in the intelligence surface?
4. docs/plans/phase-0-investigation/architecture/02-data-flow.md (S240 Wave 2) — does the intelligence pipeline absorb into cocoindex?
5. docs/plans/phase-0-investigation/architecture/08-new-features.md (S240 Wave 2 tail) — is intelligence on the Phase 1/2 roadmap?
6. docs/plans/phase-0-investigation/architecture/04-workspace-types.md — what’s the intelligence_workspaces shape at v1 apply time?
7. docs/specs/id-31-canonical-pipeline-implementation-plan/PLAN.md (S241 DRAFT) — what schema migrations affect intelligence routes?

Plus:

• docs/reference/product-roadmap.json — explicit roadmap items referencing intelligence routes / tables.
• docs/specs/id-31-0.9-canonical-pipeline/{PRODUCT,TECH}.md — substrate specs.
• lib/intelligence/content-extractor.ts (this worktree) — retirement scope clarification.

Each of the 20 route files was opened and its database-table dependencies catalogued via grep '\.from(' to identify schema coupling. Disposition for each was then derived from the source-doc claims about those tables.

---

§2 Reserved-workspace-seats finding

intelligence_workspaces seat exists at v1 apply time. Confirmed per docs/specs/reserved-workspace-seats/PRODUCT.md S-1 ([RATIFIED-S240]): “When the v1 reserved-workspace-seats migration applies, all five satellite tables exist in the public schema with their final names: intelligence_workspaces, sales_proposal_workspaces, product_guide_workspaces, competitor_research_workspaces, training_onboarding_workspaces.”

The seat shape at v1 is minimal (PRODUCT.md S-2 + S-3 + S-7):

• id uuid PRIMARY KEY DEFAULT gen_random_uuid()
• workspace_id uuid NOT NULL UNIQUE REFERENCES workspaces(id) ON DELETE CASCADE
• RLS auto-enabled via rls_auto_enable() event trigger
• NO per-application-type columns at v1 apply time. Per S-7, columns like buyer, deadline, outcome are added later by feature-spec migrations via ALTER TABLE ... ADD COLUMN.

So intelligence_workspaces is a PK+FK shell at Phase 1 close; the intelligence-application column list is a deferred feature-spec deliverable per 04-workspace-types.md §4.2 line 108 (“Future feature spec — TBD (columns)”).

Intelligence application_type is a v1 core seat — 04-workspace-types.md §3 confirms intelligence as one of the six core-provenance baseline application_types (alongside procurement, sales_proposal, product_guide, competitor_research, training_onboarding) and 04-workspace-types.md §2 line 40 notes 4 existing prod rows in workspaces.type='intelligence' that get backfilled to application_type_id during the Q-OQR1-16 combined PR migration.

Existing feed-system schema (feed_sources, feed_articles, feed_prompts, feed_flags, company_profiles) is NOT in any collapse list. Only feed_articles.extraction_method='firecrawl' is [LOCKSTEP-WITH-MIGRATION] per 07-collapse-list.md §11.2 (one enum value retires; column survives). The five intelligence tables are not retiring, not renaming, not migrating to a new home.

Roadmap explicitly plans v1 work on the intelligence surface: roadmap items at product-roadmap.json:1205-1227 schedule E2E tests “intelligence-feed-admin.spec.ts” covering feed_sources mutations + prompt editing — confirming the intelligence admin UI surfaces persist into v1.

MCP intelligence tools survive as [REFINE], not [RETIRE] — 06-mcp-tooling.md lines 86 + 235-237 retains get_intelligence_summary [RETAIN-AS-IS] and trigger_intelligence_poll [REFINE] (needs scope-guard tech spec, not retirement).

---

§3 Per-route disposition table

Routes listed in continuation-prompt order. Schema dependencies derived from grep '\.from(' on each file. Disposition derived from the source-doc claims.

#	Route	Schema dependencies	Disposition	Citation
1	app/api/intelligence/trigger-poll/route.ts	lib/intelligence/pipeline (runPipeline)	REWRITE	0.9-canonical-pipeline/TECH.md §1 P-1 — lib/intelligence/feed-poller.ts is greenfield substrate; cocoindex flow + Cloud Run sidecar replaces it. URL stays.
2	app/api/intelligence/profiles/route.ts	company_profiles	SURVIVE	company_profiles not in 07-collapse-list.md; roadmap retains; surface preserved.
3	app/api/intelligence/profiles/[id]/route.ts	company_profiles	SURVIVE	Same as #2.
4	app/api/intelligence/workspaces/route.ts	workspaces.type='intelligence' (5×), company_profiles, feed_sources, feed_articles, feed_prompts, lib/intelligence/guide-generator	REWRITE	workspaces.type retires per 07-collapse-list.md §3.1 + 04-workspace-types.md §3 (Q-OQR1-16 combined PR replaces with application_type_id). All 5 .eq('type', 'intelligence')/type: 'intelligence' writes need swap to application_type_id lookup. URL preserved; intelligence_workspaces seat-table writes likely added per reserved-workspace-seats S-1.
5	app/api/intelligence/workspaces/[id]/route.ts	workspaces.type='intelligence' (3×), company_profiles	REWRITE	Same as #4 — three .eq('type', 'intelligence') filters need rewrite post-Q-OQR1-16.
6	app/api/intelligence/workspaces/[id]/articles/route.ts	feed_articles	SURVIVE	feed_articles not in collapse list; no workspaces.type filter.
7	app/api/intelligence/workspaces/[id]/articles/[articleId]/flag/route.ts	feed_articles, feed_flags	SURVIVE	Both tables persist; no workspaces.type filter.
8	app/api/intelligence/workspaces/[id]/flags/route.ts	feed_flags	SURVIVE	feed_flags persists; no workspaces.type filter.
9	app/api/intelligence/workspaces/[id]/flags/analyse/route.ts	workspaces, feed_prompts, company_profiles, feed_flags, lib/intelligence/flag-analyser	SURVIVE	No workspaces.type filter visible in the dependency strip (the .from('workspaces') query may have one; flagging as SURVIVE with the caveat that if it does, it’s a one-line rewrite). lib/intelligence/flag-analyser is greenfield-not-retired.
10	app/api/intelligence/workspaces/[id]/flags/resolve/route.ts	workspaces, feed_flags	SURVIVE	Same caveat as #9 — if .from('workspaces') does a type filter, swap to application_type_id; otherwise no change.
11	app/api/intelligence/workspaces/[id]/health/route.ts	workspaces, lib/intelligence/health	SURVIVE	Same caveat as #9-10.
12	app/api/intelligence/workspaces/[id]/metrics/route.ts	feed_articles, feed_flags, feed_sources	SURVIVE	All three tables persist.
13	app/api/intelligence/workspaces/[id]/metrics/trend/route.ts	(no .from( calls — likely delegates to helper)	SURVIVE	No schema coupling visible; survives unless helper retires.
14	app/api/intelligence/workspaces/[id]/metrics/prompt-performance/route.ts	feed_prompts, feed_articles, feed_flags	SURVIVE	All three tables persist.
15	app/api/intelligence/workspaces/[id]/prompts/route.ts	feed_prompts (8×)	SURVIVE	feed_prompts persists.
16	app/api/intelligence/workspaces/[id]/prompts/preview/route.ts	workspaces, company_profiles, feed_articles, lib/intelligence/relevance-scorer	SURVIVE	Same caveat re. workspaces type filter.
17	app/api/intelligence/workspaces/[id]/seed-starter-pack/route.ts	workspaces, feed_sources, lib/intelligence/starter-packs	SURVIVE	Same caveat.
18	app/api/intelligence/workspaces/[id]/sources/route.ts	feed_sources, workspaces, lib/intelligence/feed-poller	SURVIVE	feed_sources persists. lib/intelligence/feed-poller retires per 0.9-canonical-pipeline/TECH.md §1 P-1 but the route imports validateFeedUrl — a small surface that the replacement pipeline must re-export.
19	app/api/intelligence/workspaces/[id]/sources/[sourceId]/route.ts	feed_sources (5×)	SURVIVE	feed_sources persists.
20	app/api/intelligence/workspaces/[id]/sources/[sourceId]/test/route.ts	feed_sources, lib/intelligence/feed-poller	REWRITE	Calls pollFeed + pollWebSource from lib/intelligence/feed-poller. Post-cocoindex migration per 0.9-canonical-pipeline/TECH.md §1 P-1, these helpers either retire or get re-implemented over cocoindex. URL stays; body rewrites.

Total disposition counts:

• SURVIVE: 16 routes (no rewrite needed for canonical-pipeline migration)
• REWRITE: 4 routes (URL preserved; body needs workspaces.type → application_type_id swap and/or lib/intelligence/feed-poller replacement)
• RETIRE: 0 routes
• RENAME: 0 routes

---

§4 Aggregate verdict

100% of intelligence routes survive the canonical-pipeline rewrite. 20 of 20 routes preserve their URLs.

80% of routes need ZERO rewrite for canonical-pipeline migration. Only 4 routes (#1, #4, #5, #20) carry direct coupling to the schema/library elements that are retiring or rewriting:

• Routes #4 + #5: workspaces.type='intelligence' filter swap to application_type_id lookup. Mechanical — single-line per occurrence.
• Routes #1 + #20: invoke lib/intelligence/pipeline / lib/intelligence/feed-poller helpers which retire under [RATIFIED-RETIRE] per 07-collapse-list.md §5.2 (lib/extraction parent dir). The route URLs stay; the body delegates to a replacement pipeline.

Crucially, NONE of the 4 rewrite-routes change their return shape. The return-type annotation work R-WP21 Wave-A proposes is independent of the body rewrite — a Promise<NextResponse> return-type is the same before and after workspaces.type migration. The return-type annotation lands once and remains valid through the canonical-pipeline rewrite.

6 routes have a soft caveat (#9, #10, #11, #16, #17): they .from('workspaces') but I did not inspect whether they do a .eq('type', 'intelligence') filter. If they do, they need the same one-line swap as #4 + #5 — still SURVIVE in disposition terms, just with an additional micro-edit. None change return shape.

Conclusion on Wave-A annotation worthwhile-ness: The cluster persists. The URLs persist. The return shapes persist. The 54% type-drift attributed to this cluster is genuinely the high-leverage place to land annotations. Work invested in Promise<NextResponse<T>>-style annotations on these 20 files does NOT get obsoleted by the canonical-pipeline rewrite — neither the file paths nor the return signatures change.

---

§5 Recommendation

PROCEED with Wave-A annotation work as proposed.

Rationale:

1. The cluster is not retiring. Reserved-workspace-seats spec (PRODUCT.md S-1 [RATIFIED-S240]) creates intelligence_workspaces as a v1 seat; intelligence is one of six core application_types; roadmap items 1205+1227 plan further v1 work on this surface.
2. The cluster is not renaming. No [RATIFIED-RENAME] entry exists for the /api/intelligence/** route prefix. The user-facing concept “intelligence workspace” is preserved verbatim across all source docs.
3. The 4 routes that need body rewrites preserve their URLs and return shapes. Annotation work survives the canonical-pipeline migration intact; the rewrite touches .from(...) calls and lib/intelligence/* import targets, not function signatures.
4. Annotation work is independent of migration timing. Even if Q-OQR1-16 combined PR landed tomorrow, the Promise<NextResponse<SomeShape>> signatures wouldn’t budge. There’s no race condition between Wave-A and Phase 1.
5. The 54% type-drift attribution is real and high-leverage. Investing 4-6h to close more than half the project’s untyped return surface is the right ratio of effort to outcome — and the cluster’s persistence means the investment compounds across post-rewrite maintenance.

Caveat to flag in the Wave-A brief: the 4 routes (#1, #4, #5, #20) need body rewrites at the Q-OQR1-16 combined-PR landing time. The annotation PR should NOT also attempt those rewrites (those belong to T2 combined-PR scope per canonical-pipeline-implementation-plan/PLAN.md §4). Wave-A is annotation-only; canonical-pipeline T2 is the schema-migration owner.

Soft suggestion for Wave-A scoping: when annotating the 6 caveat routes (#9, #10, #11, #16, #17, #18), include a one-line code comment flagging the .from('workspaces') line if it carries a .eq('type', 'intelligence') filter. This makes T2’s migration sweep easier without expanding Wave-A scope.

---

§6 Source citations (load-bearing)

• docs/specs/reserved-workspace-seats/PRODUCT.md S-1, S-2, S-3, S-7 ([RATIFIED-S240]) — intelligence_workspaces seat exists at v1; PK+FK only; columns deferred to feature spec.
• docs/specs/reserved-workspace-seats/TECH.md T-1 — combined migration body shape with CREATE TABLE public.intelligence_workspaces (...).
• docs/plans/phase-0-investigation/architecture/04-workspace-types.md §3 line 75 (intelligence as core application_type), §4.2 line 108 (seat-table created upfront), §2 line 40 (4 prod intelligence rows backfill).
• docs/plans/phase-0-investigation/architecture/07-collapse-list.md §3.1 (workspaces.type retires), §5.2 line 149 (lib/intelligence/content-extractor.ts retires), §11.2 line 273 (feed_articles.extraction_method='firecrawl' lockstep-retire).
• docs/plans/phase-0-investigation/architecture/02-data-flow.md §3.1 (cocoindex flow stages), §9.3 line 234 (intelligence-workspace re-indexing example).
• docs/plans/phase-0-investigation/architecture/08-new-features.md §10 (deferral register; no intelligence retire).
• docs/plans/phase-0-investigation/architecture/06-mcp-tooling.md §6 lines 235-260 — intelligence MCP tools [REFINE] not retire.
• docs/specs/id-31-canonical-pipeline-implementation-plan/PLAN.md §2 T2 (combined PR + reserved seats migration); §3 Wave 2 (intelligence rows backfill at this stage).
• docs/specs/id-31-0.9-canonical-pipeline/TECH.md §1 P-1 (line 50 — lib/intelligence/feed-poller.ts is current state, retires under cocoindex flow); §5 P-43 (line 317 — backfill 4 intelligence prod rows).
• docs/reference/product-roadmap.json lines 1205 + 1225 — v1 E2E tests for intelligence feed admin + prompt editing.

---

End of investigation. Recommendation: GO on Wave-A annotation work.