Architecture sub-doc readiness audit (per-section, S238 wrap → S239 dispatch)

Architecture sub-doc readiness audit (per-section, S238 wrap → S239 dispatch)

Audit date: 14/05/2026 (S238 wrap-up sub-agent — pre-S239 Wave 1 dispatch) Scope: Per-section readiness audit for the remaining 7 WP4 architecture sub-docs (02-data-flow.md, 03-tech-stack.md, 04-workspace-types.md, 05-qa-flow.md, 07-collapse-list.md, 08-new-features.md, 09-diagrams.md) plus the 1 gated sub-doc (06-mcp-tooling.md). 01-vision.md already landed S238 as pilot (commit 4b9dccd3 + content-fix passes) — out of audit scope. Author: Sub-agent for S238 wrap — readiness audit per documentation-and-adrs + code-review-and-quality (per-section adversarial categorisation). Method: For each sub-doc, propose a section structure (based on 01-vision.md pilot pattern + INV §3 source material), then category each section as one of:

• (a) product spec needed first — user-facing behaviour undecided
• (b) tech spec needed first — engineering detail undecided
• (c) investigation spike needed first — empirical question without an answer
• (d) ratification needed — Liam pre-decision on framing required (not investigation, not spec; a decision)
• (e) READY-TO-DRAFT-FROM-EXISTING — sources + ratifications all exist; section can be drafted

The aim is to separate “going through the motions of writing the sub-doc” from “armed with documentation + next steps for moving to implementation”. A sub-doc may have some sections READY-TO-DRAFT and others blocked — the audit is per-section, not per-sub-doc.

---

Reading list (the docs consulted)

• docs/specs/core-docs-pathway-assessment/INV-architecture-split-readiness.md §2 (10 superseded items), §3 (per-sub-doc inventory + readiness), §4 (dependency layers), §5 (gates remaining), §6 (wave structure proposal).
• docs/plans/phase-0-investigation/10-feedback-investigation-findings/00-synthesis-v2.md §2 (B/I/N rollup), §3 (new items — application_types, procurement rename, q_a_pairs corpus, kb_section retire, Cloud Run sidecar, Docling, auto-RLS, grants, OAuth), §3.7 (S237 CV refinements), §4 (readiness map), §5 (still-open + scheduling).
• docs/plans/phase-0-investigation/architecture/01-vision.md — pilot sub-doc; sets the section-structure pattern (mission / vision / user model / framing / first applications / anti-patterns / status of source doc / pilot review notes); cites heritage docs with staleness markers.
• docs/plans/phase-0-investigation/0.9-decision-graph.md §11.1 (ONT.1-17), §11.2 (COCO.1-12), §11.3 (combined-PR 10 items), §11.4 (post-S237 STILL-OPEN + DEFERRED + RESOLVED-S237).
• docs/plans/phase-0-investigation/0.9-collapse-candidates.md §12 (S235 retires + DEFERRED-v1.1 + DO-NOT-BUILD), §13 (S235 still-open), §14 (S237 CV-driven retires).
• docs/plans/phase-0-investigation/feedback-findings-review.md §5.1 (Theme A-G resolutions), §5.2 (per-finding refresh), §5.4 (still-open + scheduling), §6 (S237 closures).
• docs/plans/phase-0-investigation/phase-b-prerequisite-1-onthology-pipeline-feedback-investigation.md §8 (Q-OQR1-01..17), §9 (recommendations one-liners).
• docs/plans/phase-0-investigation/phase-b-prerequisite-2-cocoindex-deep-dive.md (cocoindex affordance synthesis — ExtractByLlm, entity_resolution, files_transform, memo, sidecar).
• docs/plans/phase-0-investigation/phase-b-prerequisite-2d-docling-bakeoff.md §6 (PDF), §9 (XLSX full-corpus verification).
• docs/plans/phase-0-investigation/0.9-spike-S9-cocoindex-idempotency.md — Q&A markdown sidecar v1 substrate (RESOLVED-PARTIAL).
• docs/plans/phase-0-investigation/0.9-spike-S16-qa-schema-design.md §6 (two-tier q_a_pairs + q_a_extractions model).
• docs/plans/phase-0-investigation/0.9-edit-flow-investigation.md §6 (cross-UC consolidated decisions + per-UC Candidate A/B/C ratifications — RATIFIED S229 with §6.0.1..§6.0.7).
• docs/plans/phase-0-investigation/supabase-db-action-items.md (Items 1 + 2 + 3 — May 30 grants, auto-RLS event trigger SQL, May 26 OAuth 200/201). S238 survey confirmed no KH code changes needed for Item 3.
• docs/reference/SCHEMA-QUICK-REFERENCE.md (current 37-section schema reference).
• docs/ontology/*.md — 29 CV files (WP6 markdown ontology scaffold — LANDED-S236-S237).
• Heritage docs (treated as positioning context, NOT current state for ratified items): docs/client-documentation/Knowledge Hub — Platform Overview.md, Claude Integration Guide.md, docs/reference/ai-integration-strategy.md, docs/reference/product-differentiation-audit.md.

---

Cross-reference table — ratification anchors per sub-doc

Quick-reference: which ratification anchors each sub-doc must cite, and the canonical source in current docs. Sub-doc authors should treat these as load-bearing — if the anchor below cannot be cited verbatim, the section is likely (d) ratification needed.

Sub-doc	Primary ratification anchors	Canonical source
02-data-flow	B2 RESOLVED-α; Q-OQR1-09 source_documents.workspace_id nullable; COCO.1-COCO.6 (cocoindex + Docling + Cloud Run + pullmd + Anthropic skills); N5/N6/N7 (upload-route fix, pipeline_runs retain, op_id hybrid); Theme C edit-intent; Theme D freshness substrates; Item 1 + Item 2 (May 30 grants + auto-RLS event trigger)	Decision-graph §11.1 ONT.7; §11.2 COCO rows; §11.4.1 N7 + audit_log RLS; synthesis-v2 §3.1 + §3.2 + §3.3 + §3.16 + §3.17; supabase-db-action-items.md Items 1 + 2
03-tech-stack	COCO.2-COCO.6 + COCO.11 (Docling adoption + Cloud Run sidecar + pullmd retain + Anthropic doc skills); ONT.17 typed columns over JSONB; UC1 Candidate A (Tiptap + Yjs); CV 16 extraction-method retire timing	Decision-graph §11.2 COCO rows; synthesis-v2 §3.1 + §3.2 + §3.7 + §3.9; 0.9-edit-flow-investigation.md §6.1; collapse-candidates §14.3
04-workspace-types	Q-OQR1-01 (Option c hybrid); Q-OQR1-02 (procurement umbrella); Q-OQR1-03 (6 baseline application_types); Q-OQR1-05 (state-machine home); Q-OQR1-06 (q_a_pairs corpus-level); Q-OQR1-07 (source_workspace_id provenance); Q-OQR1-09 (source_documents nullable); Q-OQR1-11 (provenance pattern); Q-OQR1-13 (admin UI v1.1); Q-OQR1-16 (combined PR scope); Q-OQR1-S235 (kb_section retire); ONT.1-ONT.17	Decision-graph §11.1 ONT rows; §11.3 combined-PR 10 items; synthesis-v2 §3.4-§3.9 + §3.15; WP-ONTO-R1 §8 (all Q-OQR1 questions); §9 (recommendations)
05-qa-flow	Q-OQR1-06 + Q-OQR1-07 + Q-OQR1-08 (q_a_pairs cardinality); B1 + N1 (Pattern A/B retire); N8 (citations polymorphic); N9 (separate scoring columns); N11 (q_a_pair provenance); COCO.9 + COCO.10 (S9 idempotency partial); OQ-Q35-A/B (cataloguer); UC5 + UC6 + UC8 RATIFIED-S229 (write-back ratifications)	Decision-graph §11.1 ONT.5/ONT.6/ONT.11/ONT.13; §11.2 COCO.9/COCO.10; §11.4.1 N9; synthesis-v2 §3.6 + §5.1; 0.9-spike-S9-cocoindex-idempotency.md; 0.9-spike-S16-qa-schema-design.md §6; 0.9-edit-flow-investigation.md §6.5 + §6.6 + §6.7
06-mcp-tooling	Theme F MCP-action review pass (STILL-OPEN per 00-synthesis-v2.md §5.2 row 1)	Decision-graph §11.4.2 row 1; feedback-findings-review §5.1 row F; synthesis-v2 §4 row 6 + §5.2 row 1
07-collapse-list	All retire tier markers (RATIFIED-RETIRE-S235 / DEFERRED-v1.1-S235 / RATIFIED-DO-NOT-BUILD-S235 / RATIFIED-RETIRE-S237 / RATIFIED-RENAME-S235 / RATIFIED-RENAME-S237); §11 carry-forward note	0.9-collapse-candidates.md §0 + §12 + §13 + §14
08-new-features	CX.32 (Knowledge Map cocoindex substrate); UC8 RATIFIED-S229 (dedup); UC9 RATIFIED-S229 (scope-tag taxonomy); N10 (lost-bid skip); Q-OQR1-13 (admin UI v1.1); Q-OQR1-14 (form_type behaviour v2); Q-OQR1-10 (multi-wing operational); rename digests → change_reports	Decision-graph §11.4.4 deferred items; synthesis-v2 §3.13 + §5.2 row 4; 0.9-edit-flow-investigation.md §6.7 + §6.8; CX.32 cocoindex substrate
09-diagrams	All schemas finalised in 02 + 04 + 05; auto-RLS event trigger sequence per Item 2; Cloud Run sidecar topology per §3.1 of synthesis-v2; bid-feedback 3-UC per UC5/UC6/UC8	Cross-doc — needs 02 + 04 + 05 + 08 finalised first

---

Aggregate verdict table

Sections counted at the proposed-structure level; total sections per sub-doc reflect the structure proposed in §“Per-sub-doc deep-dive” below (varies per sub-doc — 04-workspace-types.md is the heaviest at 13 sections; 07-collapse-list.md is the lightest at 4 sections).

Sub-doc	Total sections	(e) READY	(a) product spec	(b) tech spec	(c) investigation	(d) ratification
02-data-flow	10	8	0	1	0	1
03-tech-stack	9	9	0	0	0	0
04-workspace-types	13	10	0	2	0	1
05-qa-flow	11	9	1	1	0	0
06-mcp-tooling	8	0	0	0	0	8
07-collapse-list	4	4	0	0	0	0
08-new-features	9	7	1	0	0	1
09-diagrams	7	7	0	0	0	0
Aggregate	71	54	2	4	0	11

Headline: 54 of 71 sections (76%) READY-TO-DRAFT from existing sources. 8 of 11 ratification blockers concentrate on 06-mcp-tooling.md (Theme F MCP-action review pass). Excluding 06-mcp-tooling.md, the rate climbs to 54 of 63 (86%). No investigation spikes block any of the 7 active sub-docs — the Phase 0.9 investigation arc is closed for WP4 entry per 00-synthesis-v2.md §4.

---

Heritage-doc disposition per sub-doc

Per pilot §7.1 discipline — cite heritage docs sparingly and only where heritage framing is uniquely load-bearing. Below: which heritage docs each sub-doc should reference, and the scope of the reference.

Sub-doc	Heritage doc	Use scope (per pilot §7.1 discipline)
02-data-flow	None directly	Inherits framing from 01-vision.md; new content is data-flow architecture not positioning.
03-tech-stack	AI Integration Strategy (docs/reference/ai-integration-strategy.md)	§1.4 design principles parallel to 01-vision.md §2.2 — reference for stack-composition principle adherence; do NOT re-litigate the 4-layer AI integration framing.
04-workspace-types	Platform Overview (docs/client-documentation/Knowledge Hub — Platform Overview.md)	Procurement-as-application framing comes from Platform Overview’s “Bid Library” framing — but with Q-OQR1-02 procurement rename, the heritage doc carries stale bid_workspaces framing. Discipline: cite Platform Overview only for client-facing procurement positioning, NOT for table names or workspace schema (which are stale).
05-qa-flow	Claude Integration Guide (docs/client-documentation/Knowledge Hub — Claude Integration Guide.md)	Claude-via-MCP Q&A retrieval flow framing — reference for how Q&A consumption shape works end-to-end; do NOT re-litigate the MCP integration shape (which lives in 06-mcp-tooling.md).
06-mcp-tooling	Claude Integration Guide + AI Integration Strategy §1	Both heritage docs frame MCP integration. Discipline: cite for end-user-facing positioning; the architecture-level integration pattern is what this sub-doc itself establishes (gated on Theme F).
07-collapse-list	None	Pure transformation/extraction of 0.9-collapse-candidates.md; no positioning content.
08-new-features	Product Differentiation Audit (docs/reference/product-differentiation-audit.md)	Knowledge Map + Change Reports + bid-feedback loop framings appear in Product Differentiation Audit’s “5 differentiators” framing. Discipline: cite for competitive context; technical specifics come from CX.32 + decision-graph rows.
09-diagrams	None	Diagrams render verbatim from 02 + 04 + 05 + 08 prose; no positioning content.

Cross-cutting flag: Heritage doc staleness is explicit in pilot §7.1 — Platform Overview carries pre-procurement-rename framing; AI Integration Strategy §1.4 has effort estimates outdated post-Phase 0.9; Product Differentiation Audit has “AI features” framing shifts. Sub-doc writers must cite with explicit staleness markers per pilot §7.1 convention. The contradiction-priority rule (Phase 0.9 ratifications > heritage docs) is established in pilot §8 (“any framing drift between the heritage docs and Phase 0.9 ratifications should defer to the latter”).

---

Per-sub-doc deep-dive

02-data-flow.md

Purpose (from INV §3): Source-binding model; cocoindex flow stages; binary path; Cloud Run sidecar; audit_log + op_id propagation; auto-RLS event trigger; grants pattern; ingest write paths.

Suggested section structure (10 sections):

1. §1. Source-binding model — external-folder canonical; LocalFS / SharePoint / Notion; cocoindex source-key + content-hash + KH source_documents.workspace_id nullable per Q-OQR1-09.
2. §2. Cocoindex flow stages — files_transform → format converter (Docling) → content_text → ExtractByLlm classifier → embedding + entity extraction. Adapter affordances (@coco.fn, memo, retry/back-off/DLQ).
3. §3. Binary path + Cloud Run sidecar — Docling 1.8 GB → Cloud Run sidecar architecture (kh-prod-494815); per-MIME viewer composition (PDF / DOCX / XLSX); sidecar-v1 markdown → Tiptap ContentEditor; pullmd retention for HTML.
4. §4. audit_log + op_id propagation pattern — hybrid pattern per N7 ratification (cocoindex per-flow op_id for pipeline correlation + trigger-driven for platform-wide audit cohesion). Lands per 00-synthesis-v2.md §5.1 + decision-graph §11.4.1.
5. §5. RLS pattern — auto-enable event trigger + grants — adopt Supabase rls_auto_enable() event trigger per supabase-db-action-items.md Item 2; pair with May 30 grants compliance per Item 1; CLAUDE.md Gotcha update; migration template update.
6. §6. Ingest write paths — upload-route HITL fix (N5 RESOLVED); pipeline_runs retained as KH-side rollup (N6); pipeline_failures DO-NOT-BUILD (COCO.7); silent-fail prevention pattern (sb() / tryQuery() / warningsEnvelope()).
7. §7. Edit re-classification trigger policy (Theme C) — edit_intent Layer-1 CV; cosmetic skips re-classification; data / structural triggers; concurrent-edit handling defers to operational design.
8. §8. Cocoindex freshness vs governance freshness — separate substrates per Theme D resolution (cocoindex = ingest-latency operational; KH content_items.freshness = governance fresh/aging/stale/expired).
9. §9. Anti-patterns + retired patterns — Pattern A/B Q&A parser retire (B1 RESOLVED, retire post-Phew-migration); diff-UI retire under Option α; custom URL-freshness cron retire (12.3 collapse).
10. §10. Cross-doc references — schemas referenced from 04-workspace-types.md; ERDs deferred to 09-diagrams.md.

Per-section readiness verdict:

Section title	Category	Rationale	Prereq if blocked
§1. Source-binding model	(e) READY	B2 RESOLVED-α + Q-OQR1-09 nullable workspace_id ratified; cocoindex source-key pattern per Prereq 2 §1.1; current source_documents schema in SCHEMA-QUICK-REFERENCE §22.	—
§2. Cocoindex flow stages	(e) READY	Prereq 2 §1.1 + §1.2 + Rec 1-5 (S234); ExtractByLlm for B1/N1/COCO.12; files_transform for binary scale; memo per COCO.9 layered-fn-shape requirement (S9 spike RESOLVED-PARTIAL).	—
§3. Binary path + Cloud Run sidecar	(e) READY	COCO.6 ratified; Docling bake-off §6 PDF + §9 XLSX full-corpus verification; pullmd retention COCO.5; KH already runs Cloud Run for Python pipeline per CLAUDE.md.	—
§4. audit_log + op_id propagation	(e) READY	N7 RESOLVED-S236 (cocoindex per-flow op_id + trigger-driven hybrid); cited in decision-graph §11.4.1 + synthesis-v2 §5.1.	—
§5. RLS pattern — auto-enable + grants	(d) ratification needed	00-synthesis-v2.md §3.16 says “path TBD with 04-workspace-types or new RLS-PATTERN.md”. Auto-RLS SQL ratified per Item 2; grants pattern ratified per Item 1; OAuth Item 3 has NO code changes needed per S238 survey. What needs disambiguation: destination doc — inline in 02-data-flow.md §5 vs separate docs/specs/rls-pattern/{PRODUCT.md,TECH.md}. INV §7.4 working recommendation: separate docs/specs/rls-pattern/. Liam 1-line ratification needed.	Liam pre-decision: “inline §5 here” OR “separate docs/specs/rls-pattern/ track” (INV §7.4 recommends the latter).
§6. Ingest write paths	(e) READY	N5 RESOLVED (upload-route fix proceeds under Option α); N6 RESOLVED (pipeline_runs retain); COCO.7 RESOLVED (no pipeline_failures); silent-failure spec already exists at docs/specs/silent-failure-prevention-spec.md.	—
§7. Edit re-classification trigger policy	(e) READY	Theme C RESOLVED-DIRECTIONAL per feedback §5.1; edit_intent Layer-1 CV ratified S234 (ONT.14); concurrent-edit-handling explicitly deferred to operational design.	—
§8. Cocoindex freshness vs governance freshness	(e) READY	Theme D RESOLVED — separate substrates per Prereq 2 §1.1 + §1.2; no merge.	—
§9. Anti-patterns + retired patterns	(b) tech spec needed	Combined-PR scope (10 items per decision-graph §11.3) is RATIFIED — but the actual SQL for the migration is not yet written. This section can describe the retired patterns (Pattern A/B, diff-UI, URL-freshness cron) at vision level; the migration write-up itself is a TECH spec deliverable for the docs/specs/<combined-PR>/TECH.md track. Inline the directional listing; cite the TECH-spec-to-come for actual SQL. Borderline READY-TO-DRAFT — section can be drafted with the caveat that detailed retirement SQL belongs in a separate combined-PR tech spec.	Tech spec for combined PR — the 10-item Q-OQR1-16 migration. INV §6 Wave 2 schedules this as part of 04-workspace-types.md main draft. If 04-workspace-types.md lands the migration scope narrative, 02-data-flow.md §9 cross-links and stays directional. Borderline (e) READY contingent on 04-workspace-types.md §10 landing first. Re-categorising as (b) to flag the dependency.
§10. Cross-doc references	(e) READY	Sequencing-only — references finalised in 04-workspace-types.md (Wave 2 main).	Sequencing-only; depends on 04-workspace-types.md landing first.

Critical-path prerequisites:

1. §5 RLS-PATTERN destination decision — Liam 1-line pre-decision (inline vs separate doc). Recommendation: separate docs/specs/rls-pattern/ per INV §7.4 — keeps RLS pattern reusable across sub-docs.
2. §9 + §10 depend on 04-workspace-types.md landing first — combined-PR scope narrative anchors here; 02-data-flow.md cross-links.

Dependency on other sub-docs: Per INV §4 ordering — 02-data-flow.md is Wave 2 split (parallel with 05-qa-flow.md), AFTER 04-workspace-types.md main draft lands. Its references to schemas (workspaces.application_type_id, procurement_workspaces, q_a_pairs corpus shape, source_documents.workspace_id nullable) all anchor in 04-workspace-types.md.

---

03-tech-stack.md

Purpose (from INV §3): v1 stack composition; Docling + Cloud Run sidecar; pullmd retention; cocoindex; Tiptap+Yjs; mempalace; Anthropic doc skills.

Suggested section structure (9 sections):

1. §1. Stack overview — Next.js 16 + Vercel + Cloud Run + Supabase (Postgres + pgvector) + cocoindex + Tiptap + Yjs + mempalace + Anthropic doc skills.
2. §2. Cocoindex — Rust engine; per-flow op_id; LMDB ops-DB; ExtractByLlm + entity_resolution + files_transform; CocoInsight (separate from audit_log per Prereq 2 §3.3); pending TS-facing ledger API (STILL-OPEN).
3. §3. Docling adoption + Cloud Run sidecar — Docling primary for PDF / DOCX / XLSX; ~1.8 GB footprint > Vercel 250 MB; Cloud Run sidecar; MIT license; layout-heron + docling-models.
4. §4. pullmd retention for HTML — Playwright sidecar + Cloudflare short-circuit + share-id identity contract not replaceable; AGPL v3 already-tracked per PM-Q2.
5. §5. Anthropic doc skills (docx/xlsx/pdf) — Theme B step 1 evaluate-form; step 3 markdown convert (Docling); step 4 classify-form-data (ExtractByLlm); steps 2 + 5 HITL.
6. §6. Tiptap + Yjs — existing Q&A ContentEditor; per-MIME viewer composition (Tiptap + sidecar markdown); Yjs collab (no DB persistence in v1; defer y-supabase to v1.1 per UC1 4.1.Q4).
7. §7. Mempalace — direct MCP server (canonical memory system replacing auto-memory file system 2026-05-10); v3.3.5 plugin; one wing per worktree; AAAK format. NB: integration pattern (direct vs wrapped) is operational-side; lands in 06-mcp-tooling.md not here.
8. §8. Standards + conventions — typed columns over JSONB platform-wide (S235 ratification); silent-failure prevention pattern; UK English; pgvector 0.8.0; vector(1024) text-embedding-3-large.
9. §9. Retired alternatives + rationale — unpdf retired (Docling replaces); markitdown for XLSX retired (Docling tied + cleaner output); CopilotKit removed (S109); GitBook auto-update plan retired (Astro+Starlight ratified S237).

Per-section readiness verdict:

Section title	Category	Rationale	Prereq if blocked
§1. Stack overview	(e) READY	Current state per CLAUDE.md + 0.9-intended-architecture.md §10 (with Docling + Cloud Run sidecar added per 00-synthesis-v2.md §3.1 + §3.2).	—
§2. Cocoindex	(e) READY	All 12 COCO rows RESOLVED-S234/S235 per decision-graph §11.2; CocoInsight separation per Prereq 2 §3.3; TS-facing ledger STILL-OPEN flagged.	—
§3. Docling adoption + Cloud Run sidecar	(e) READY	§3.2 + COCO.2-COCO.4 RESOLVED; XLSX RESOLVED-S235 per WP-DOCLING-XLSX §9; license verdict MIT; full bake-off table at phase-b-prerequisite-2d-docling-bakeoff.md.	—
§4. pullmd retention for HTML	(e) READY	COCO.5 + §3.3 RESOLVED; pullmd PM-Q2 license already tracked.	—
§5. Anthropic doc skills	(e) READY	Theme G RESOLVED; Theme B steps 1 + 3 + 4 RESOLVED per feedback §5.1.	—
§6. Tiptap + Yjs	(e) READY	UC1 Candidate A ratified per 0.9-edit-flow-investigation.md §6.1; Yjs persistence v1.1 per UC1 4.1.Q4; sidecar-v1 architecture per Finding 06 disposition.	—
§7. Mempalace	(e) READY	Memory file system phase-out + plugin live per CLAUDE.md; integration pattern flagged for 06-mcp-tooling.md (correct cross-reference, not a block here).	—
§8. Standards + conventions	(e) READY	Typed columns over JSONB ratified S235 per ONT.17; silent-failure prevention spec landed; CLAUDE.md current.	—
§9. Retired alternatives + rationale	(e) READY	All retire items ratified: unpdf (collapse §12.4), markitdown XLSX caveat retracted (12.4), CopilotKit (S109), GitBook (§14.5 retire S237).	—

Critical-path prerequisites: None. All 9 sections READY-TO-DRAFT.

Dependency on other sub-docs: Per INV §4 Layer 1 — 03-tech-stack.md is in Wave 1 parallel with 07-collapse-list.md; no upstream deps. (Note: 01-vision.md was originally also Wave 1 but already landed S238 pilot.)

---

04-workspace-types.md

Purpose (from INV §3): Shape B retention; application_types instance table; per-application_type satellites; procurement rename; kb_section retirement; q_a_pairs corpus-level + scope_tag pattern; combined-PR scope.

This is the biggest sub-doc by scope per 00-synthesis-v2.md §4 row 4 and INV §4 ordering. Downstream consumers (02 / 05 / 08) all reference its schemas.

Suggested section structure (13 sections):

1. §1. Workspaces + application_types instance table — Shape B retention; Option (c) hybrid ratified per Q-OQR1-01; workspaces.application_type_id FK replacing workspaces.type text column; 6 baseline core-provenance types.
2. §2. Baseline application_types (6 rows) — procurement, intelligence, sales_proposal, product_guide, competitor_research, training_onboarding per Q-OQR1-03; provenance enum (core / client / recommended).
3. §3. Procurement umbrella rename (was bid) — application_type='bid' → 'procurement' per Q-OQR1-02; BID_STATES → PROCUREMENT_WORKFLOW_STATES; lib/bid/ → lib/procurement/; bid_workspaces → procurement_workspaces; form_type discriminators (bid/rfp/pqq/itt/framework/dps/gcloud).
4. §4. Per-application-type satellites pattern — procurement_workspaces columns from former domain_metadata JSONB (6 columns per OQ-Q38-E RESOLVED: buyer / deadline / submission_date / outcome / outcome_recorded_at / outcome_recorded_by); future satellites sales_proposal_workspaces, etc.; Shape B typed-cols pattern.
5. §5. kb_section retirement — added in error; 0 prod rows; retires entirely per Q-OQR1-S235 + WP-ONTO-R1 §7; code cleanup files cited per decision-graph §11.3 row 3.
6. §6. form_templates rename inventory — templates → form_templates; template_fields → form_template_fields; template_requirements → form_template_requirements; provenance enum added (96 prod SSQ + Charnwood rows seeded core) per Q-OQR1-11.
7. §7. q_a_pairs corpus-level shape — NO direct workspace FK; nullable source_workspace_id for provenance audit; workspace relevance via scope_tag overlap; supersedes both 0.9-intended-architecture.md §4.3 N:1 framing AND prior onto-doc §4.4 M:N junction framing per Q-OQR1-06. (Note: full Q&A flow detail lives in 05-qa-flow.md; this section establishes the cardinality + table shape.)
8. §8. q_a_extractions derived cache — two-tier model per S16 §6 (golden q_a_pairs + derived q_a_extractions); extractor_kind='prior_bid_response' for bid-response promotion lineage.
9. §9. source_documents.workspace_id nullable — admin-shared binaries serve multiple workspaces per Q-OQR1-09; one Phew bid library DOCX can serve all bid workspaces; RLS adjustment narrative.
10. §10. Combined-PR scope (10 items) — per decision-graph §11.3 (S235 ratified): application_types instance + workspaces FK swap + kb_section retire + procurement rename + project_id→workspace_id (44-file sweep) + form_templates rename + digests→change_reports rename + provenance enum + source_documents.workspace_id nullable + q_a_pairs schema sketch update.
11. §11. provenance pattern across hybrid vocabularies — entity_aliases.category → provenance rename; application_types / form_types / form_template_requirements / guides / coverage_targets all carry provenance per Q-OQR1-11.
12. §12. RLS adjustments per application_type — per-tenant RLS; auto-enable trigger applies (cross-link 02-data-flow.md §5 OR separate docs/specs/rls-pattern/); per-application-type RLS pattern.
13. §13. Anti-patterns + retire — workspaces.type text column with CHECK; bid_workspaces satellite name; application_type='bid'; kb_section workspace type; q_a_pairs.workspace_id NOT NULL; JSONB-over-typed-cols.

Per-section readiness verdict:

Section title	Category	Rationale	Prereq if blocked
§1. Workspaces + application_types instance	(e) READY	Q-OQR1-01 (Option c) + Q-OQR1-03 RESOLVED; FK + provenance enum shape per 00-synthesis-v2.md §3.4; WP-ONTO-R1 §2.	—
§2. Baseline application_types (6 rows)	(e) READY	Q-OQR1-03 ratified; 6 rows enumerated in WP-ONTO-R1 §2 + 00-synthesis-v2.md §3.4.	—
§3. Procurement umbrella rename	(e) READY	Q-OQR1-02 + Q-OQR1-05 RESOLVED; rename inventory enumerated in synthesis-v2 §3.5 + decision-graph §11.3 row 4; form_type values closed-list per Q-OQR1-02.	—
§4. Per-application-type satellites pattern	(b) tech spec needed	OQ-Q113-A RESOLVED (satellite per app-type) + OQ-Q38-E RESOLVED (6 cols cutline for procurement_workspaces) — BUT detailed column shapes for the OTHER satellites (sales_proposal_workspaces, competitor_research_workspaces, product_guide_workspaces, training_onboarding_workspaces) are NOT specced. Sub-section can describe the PATTERN with confidence; per-application-type column lists for the non-procurement 4 satellites need a tech spec (likely v1.1 admin-UI bound per Q-OQR1-13).	Tech spec for non-procurement satellite columns. Or: scope this section to procurement-only + flag the 4 other satellites as “schema seats only in v1; detailed columns specced per-application-type when that application reaches build”. Borderline (e) READY-TO-DRAFT-WITH-CAVEAT if we scope to procurement-only and flag the others; (b) if we want all 5 satellites schema-defined here. Recommendation: scope to procurement-only + flag the others. Adversarial honest verdict: (b) tech spec needed for the 4 non-procurement satellites if those are in v1 scope.
§5. kb_section retirement	(e) READY	Q-OQR1-S235 RATIFIED; WP-ONTO-R1 §7 migration plan with all touched files listed in decision-graph §11.3 row 3.	—
§6. form_templates rename inventory	(e) READY	I2 RESOLVED-S234 (3 tables) + Q-OQR1-11 provenance retrofit (96 prod rows) per synthesis-v2 §2.2 I2 + §3.7; decision-graph §11.3 row 6.	—
§7. q_a_pairs corpus-level shape	(e) READY	Q-OQR1-06 ratified per synthesis-v2 §3.6 + WP-ONTO-R1 §4; corpus-level + scope_tag relevance + nullable source_workspace_id; supersedes prior framings explicitly.	—
§8. q_a_extractions derived cache	(e) READY	S16 §6 two-tier model laid out; extractor_kind='prior_bid_response' lineage path per Q-OQR1-07; corpus-level pattern from §7 may simplify per 0.9-collapse-candidates.md §13.	—
§9. source_documents.workspace_id nullable	(e) READY	Q-OQR1-09 ratified per synthesis-v2 §3.15.	—
§10. Combined-PR scope (10 items)	(e) READY	All 10 items enumerated in decision-graph §11.3; Q-OQR1-16 ratified; budget/day-count terminology not used. Section can describe scope + landing order; detailed SQL belongs in docs/specs/<combined-PR>/TECH.md (a separate deliverable). NB: the section describes the migration’s scope, not the actual SQL.	—
§11. provenance pattern across hybrid vocabs	(e) READY	Q-OQR1-11 ratified per synthesis-v2 §3.7; precedent is taxonomy_domains.provenance; rename entity_aliases.category → provenance ratified.	—
§12. RLS adjustments per application_type	(d) ratification needed	This section overlaps with 02-data-flow.md §5 RLS-PATTERN destination decision. Disambiguation needed: does per-application-type RLS pattern live here, in 02-data-flow.md §5, or in a separate docs/specs/rls-pattern/? Recommendation per INV §7.4: separate doc + cross-link.	Liam pre-decision on RLS-PATTERN destination — same pre-decision as 02-data-flow.md §5 (one decision serves both).
§13. Anti-patterns + retire	(e) READY	Already enumerated in 01-vision.md §6 anti-patterns table; section reaffirms with schema specifics.	—

Critical-path prerequisites:

1. §4 per-application-type satellites scope decision — either scope to procurement-only-with-schema-seats-for-others (then section is READY); OR commission tech spec for the 4 non-procurement satellite column lists (then section is BLOCKED on the tech spec).
2. §12 RLS-PATTERN destination — same disambiguation as 02-data-flow.md §5. Decide ONCE for both.

Dependency on other sub-docs: Per INV §4 Layer 2 — 04-workspace-types.md is the FIRST Wave 2 sub-doc (foreground sequential). Downstream consumers (02-data-flow.md schemas, 05-qa-flow.md q_a_pairs shape, 08-new-features.md admin-UI extension) all anchor here. Must land BEFORE the Wave 2 split (02 + 05 parallel).

---

05-qa-flow.md

Purpose (from INV §3): Q&A as separate domain; corpus-level q_a_pairs + scope_tag; markdown sidecar v1 pattern; citations polymorphic; question_matches with question_kind discriminator; separate embedding_score + fulltext_score columns.

Suggested section structure (11 sections):

1. §1. Q&A as a separate domain — corpus-level q_a_pairs; scope_tag-driven workspace relevance; 0/395 prod rows workspace-assigned empirically per Q-OQR1-06.
2. §2. q_a_pairs schema sketch — corpus-level + nullable source_workspace_id per Q-OQR1-07; scope_tag + anti_scope_tag GIN indexes; cross-link 04-workspace-types.md §7 for the full schema.
3. §3. q_a_extractions derived cache — two-tier model per S16 §6; extractor_kind='prior_bid_response' lineage; q_a_pair_history mirror of content_history.
4. §4. Markdown sidecar v1 pattern — per Finding 02 §3.3; v1 promotion gate CLOSED-CONDITIONAL per COCO.10 (subject to layered fn-shape per COCO.9); sidecar markdown → Tiptap ContentEditor.
5. §5. Cocoindex idempotency for Q&A flow — S9 spike RESOLVED-PARTIAL-S235 (95%); layered fn-shape (inner-tier fns consume content_text: str, not FileLike); memo scoping is per-component-path, NOT global content-hash dedup.
6. §6. citations polymorphic shape — citing_entity enum: bid_response / sales_proposal_response / competitor_research_finding / training_unit / mcp_search_response per N8 RESOLVED-S234.
7. §7. question_matches with question_kind discriminator — generalised question_matches (renamed from bid_question_matches per Q-OQR1-02); question_kind aligned with form_types vocab; separate embedding_score + fulltext_score columns per N9 RESOLVED-S236.
8. §8. Q&A write-back flow + UC6 ratifications — UC6 RATIFIED S229 per 0.9-edit-flow-investigation.md §6.6 (split: user-direct + AI-suggest); version-on-cite at ship time per §6.0.3; closed per-UC intent vocabulary per §6.0.1.
9. §9. Promotion flow (UC5 — bid response → Q&A pair) — KH-DB-only operation per §6.5; lineage to source bid response + bid question; publish_status lifecycle; markdown sidecar on promotion DEFERRED-v1.1 per UC5 4.6.Q7.
10. §10. Pattern A/B parser retire (B1) — extractQaPairs retires post-Phew-migration per Q3.5 RESOLVED-MIGRATION-HELPER-ONLY + GitNexus zero-caller confirmation.
11. §11. Anti-patterns + retired patterns — q_a_pairs.workspace_id NOT NULL retire; q_a_pair_workspaces M:N junction DO-NOT-BUILD; workspace-private private_to_workspace_id DEFERRED-v1.1; idx_q_a_pairs_workspace DO-NOT-BUILD.

Per-section readiness verdict:

Section title	Category	Rationale	Prereq if blocked
§1. Q&A as a separate domain	(e) READY	Q-OQR1-06 ratified; corpus-level + scope_tag pattern; empirical 0/395 prod rows.	—
§2. q_a_pairs schema sketch	(e) READY	Cross-link to 04-workspace-types.md §7 (which lands first per INV §4); schema sketch already in 0.9-intended-architecture.md §4.3 S235 rewrite + 00-synthesis-v2.md §3.6.	Sequencing-only — 04-workspace-types.md §7 lands first (INV §4 Wave 2 order).
§3. q_a_extractions derived cache	(e) READY	S16 §6 lays out two-tier model; extractor_kind enum per Q-OQR1-07 + Finding 05 disposition.	—
§4. Markdown sidecar v1 pattern	(e) READY	I3 RESOLVED-PARTIAL + COCO.10 CLOSED-CONDITIONAL; sub-doc can describe the architecture with the layered-fn-shape note from S9 spike.	—
§5. Cocoindex idempotency for Q&A flow	(e) READY	S9 spike RESOLVED-PARTIAL with 95% confidence per 0.9-spike-S9-cocoindex-idempotency.md; layered fn-shape requirement documented.	—
§6. citations polymorphic shape	(e) READY	N8 RESOLVED-S234; citing_entity enum closed-list ratified; supersedes prior citations.bid_response_id NOT NULL framing.	—
§7. question_matches with question_kind	(e) READY	Q1.12 RESOLVED-S235; Q-OQR1-02 rename bid_question_matches → question_matches; N9 RESOLVED-S236 (separate embedding_score + fulltext_score columns); operational verification deferred to feature spec.	—
§8. Q&A write-back flow + UC6 ratifications	(e) READY	UC6 RATIFIED S229 per 0.9-edit-flow-investigation.md §6.6; cross-UC decisions §6.0.1..§6.0.7 RATIFIED; intent vocabulary closed + free-text escape; citation re-anchor hybrid; downstream-impact UI count+paginated.	—
§9. Promotion flow (UC5)	(a) product spec needed	UC5 RATIFIED S229 at architecture level per §6.5; BUT per-question quality-gate checklist + duplicate-detection threshold + scope-tag picker UI shape are product-level decisions deferred per 4.6.Q5 + 4.6.Q9 + 4.6.Q6 “soft checklist + reviewer judgement” + tunable thresholds. Adversarial verdict: architecture-level direction READY; full PRODUCT.md needed before promotion UI builds.	PRODUCT.md for promotion UI (4.6.Q5 quality checklist content, 4.6.Q6 scope-tag picker behaviour, 4.6.Q9 duplicate-detection threshold UX). Section can be drafted at architecture-level direction (referencing UC5 RATIFIED-S229) with a TBD on UI-shape; flagging (a) so the dependency is explicit. Recommendation: write at architecture-level direction (this is an arch sub-doc, not a feature spec); flag UI-shape as PRODUCT.md scope.
§10. Pattern A/B parser retire (B1)	(e) READY	B1 RESOLVED-S234 + Q3.5 RESOLVED-MIGRATION-HELPER-ONLY; GitNexus zero-callers confirmed; retire post-Phew-migration.	—
§11. Anti-patterns + retired patterns	(b) tech spec needed	Cross-section duplication — also covered in 04-workspace-types.md §13. Either consolidate to one home + cross-link, or duplicate explicitly. Adversarial verdict (b) tech spec needed for de-duplication policy across sub-docs.	Policy decision: where do anti-pattern lists live? Recommendation: each sub-doc carries its own scoped anti-patterns; cross-references are explicit. Borderline (e) if we accept the cross-doc duplication; (b) if a content-de-duplication tech spec is wanted.

Critical-path prerequisites:

1. §9 promotion-UI scope decision — Liam ratification: does this sub-doc carry architecture-level UC5 direction (then READY) or wait on a UC5 PRODUCT.md (then BLOCKED)? Recommendation: architecture-level direction is enough; PRODUCT.md is a feature-spec deliverable.
2. §11 anti-pattern duplication policy — minor; recommend per-sub-doc local lists with cross-refs.
3. §2 sequencing — 04-workspace-types.md §7 lands first.

Dependency on other sub-docs: Per INV §4 — Wave 2 split (parallel with 02-data-flow.md) AFTER 04-workspace-types.md main draft. Needs 04-workspace-types.md §7 (q_a_pairs schema) + §8 (q_a_extractions) + §11 (provenance pattern) landed first.

---

06-mcp-tooling.md — GATED

Purpose (from INV §3): KH MCP tool inventory; mempalace direct vs wrapped pattern decision; wing wire-up; MCP-action refine/remove/extend pass.

Status: BLOCKED on Theme F MCP-action review pre-decision per 00-synthesis-v2.md §5.2 row 1 + decision-graph §11.4.2 row 1 + INV §5 + INV §7.2. Lone STILL-OPEN gate as of S238.

Suggested section structure (8 sections — all blocked on Theme F):

1. §1. MCP server architecture — Vercel-deployed MCP server; WebStandardStreamableHTTPServerTransport per CLAUDE.md (NOT createMcpHandler); fresh server + transport per request.
2. §2. KH MCP tool inventory — current tool count + categorisation (current inventory regen via bun run generate:mcp-inventory).
3. §3. Mempalace direct vs wrapped — Theme F pre-decision: integrate mempalace MCP direct (Liam has mempalace plugin enabled at ~/.claude/settings.json) vs wrap mempalace tools within KH MCP server.
4. §4. Wing wire-up — Q4.5 RESOLVED in Theme F (mempalace wing ↔ KH workspace_id semantic mapping).
5. §5. MCP-action review pass — refine / remove / extend pass on existing KH MCP tools (Theme F orthogonal to WP6 ontology work per 00-synthesis-v2.md §5.2 row 1).
6. §6. MCP Apps (Vite single-file builds) — Claude Desktop/Claude.ai client UIs per CLAUDE.md mcp-apps/.
7. §7. Plugin distribution + marketplace — bun run build:plugin workflow; plugin bundle commit pattern.
8. §8. MCP eval layers — L1 protocol (42 checks), L3 response quality (17 checks), L4 functional correctness (37 checks); per CLAUDE.md commands.

Per-section readiness verdict:

Section title	Category	Rationale	Prereq if blocked
§1. MCP server architecture	(d) ratification needed	Architecture itself is RATIFIED-S228 (Vercel + WebStandardStreamableHTTPServerTransport); BUT Theme F pre-decision may add wrapping layer that changes this. Blocked on Theme F until Liam pre-decides.	Theme F MCP-action review pre-decision.
§2. KH MCP tool inventory	(d) ratification needed	Current inventory enumerable from docs/generated/mcp-inventory.md; BUT the inventory MAY CHANGE per Theme F review pass (refine/remove/extend). Blocked on Theme F outcome.	Theme F MCP-action review pre-decision.
§3. Mempalace direct vs wrapped	(d) ratification needed	The core Theme F question. No defensible default direction in current docs — pure Liam pre-decision per feedback §5.1 + finding doc 03 (1B-5 Q4.5).	Theme F MCP-action review pre-decision — THE blocking item.
§4. Wing wire-up	(d) ratification needed	Q4.5 mempalace wing ↔ KH workspace_id semantic mapping is part of Theme F. Blocked.	Theme F MCP-action review pre-decision.
§5. MCP-action review pass	(d) ratification needed	The REFINE / REMOVE / EXTEND outcome itself — directly Theme F.	Theme F MCP-action review pre-decision.
§6. MCP Apps	(d) ratification needed	Architecture mostly clear (Vite, single-file builds); BUT app inventory MAY CHANGE per Theme F.	Theme F MCP-action review pre-decision.
§7. Plugin distribution + marketplace	(d) ratification needed	Distribution workflow clear (build:plugin); BUT plugin shape may shift per Theme F.	Theme F MCP-action review pre-decision.
§8. MCP eval layers	(d) ratification needed	L1/L3/L4 eval architecture is RATIFIED-S231 + S234; BUT eval coverage may shift per Theme F refine/remove (e.g. if tools are removed, eval check count drops).	Theme F MCP-action review pre-decision.

Critical-path prerequisites: Theme F MCP-action review pre-decision is the SINGLE BLOCKER for all 8 sections. This is the lone STILL-OPEN gate as of S238 close.

Dependency on other sub-docs: Per INV §4 — independent track; can land at any wave once Theme F pre-decision is delivered. Suggested: parallel sub-agent at whichever wave Theme F closes.

Honest assessment: §1 + §6 + §8 are likely (e) READY-with-Theme-F-disclaimer, since the architecture-level patterns are stable; only the tool/app inventory contents would shift. If Liam prefers to land 06-mcp-tooling.md Wave 1 with a “Theme F MCP-action review reflects in §2 + §5 + §3 + §4 only” caveat, sections §1 + §6 + §7 + §8 could be drafted now. The audit categorises conservatively (all 8 = d) because the prompt says the sub-doc is gated on Theme F.

---

07-collapse-list.md

Purpose (from INV §3): Concise retire-list per item with tier marker; sourced from 0.9-collapse-candidates.md per the S232 Liam reframe (“list ONLY items collapsing, no duplication”).

Suggested section structure (4 sections):

1. §1. Purpose + tier markers — list ONLY items collapsing; tier markers: RATIFIED-RETIRE-S235 / DEFERRED-v1.1-S235 / RATIFIED-DO-NOT-BUILD-S235 / RATIFIED-RETIRE-S237 / RATIFIED-RENAME-S235 / RATIFIED-RENAME-S237. Carry-forward note on 0.9-collapse-candidates.md §11 “explicitly NOT collapsing” items.
2. §2. Database schema retires — per 0.9-collapse-candidates.md §2 + §12.1-§12.2: source_documents.{version, parent_id, original_filename} + source_document_diffs (Option α); bid_questions.matched_content_ids inline; bid_responses.source_content_ids inline; workspaces.domain_metadata.{buyer, deadline, submission_date, outcome, outcome_recorded_at, outcome_recorded_by} (promote to procurement_workspaces); kb_section workspace type; content_items.content_type='q_a_pair' post-cutover; content_items.{answer_standard, answer_advanced} (migrate to q_a_pairs).
3. §3. Pipeline + cocoindex absorption confirmations — Pattern A/B parser retire post-Phew-migration; pipeline_failures DO-NOT-BUILD; Q4.12 cost-tracking retire; custom URL-freshness cron retire; Q-OQR1-06 q_a_pairs DO-NOT-BUILD (workspace_id NOT NULL, M:N junction, workspace partition index).
4. §4. Renames + lockstep retires — templates → form_templates + template_fields → form_template_fields + template_requirements → form_template_requirements; bid_question_matches → question_matches; bid_workspaces → procurement_workspaces; S237 CV-driven retires (CV 04 capability, CV 16 firecrawl + trafilatura + pdfplumber); CV 13 bid_library parameter literal rename.

Per-section readiness verdict:

Section title	Category	Rationale	Prereq if blocked
§1. Purpose + tier markers	(e) READY	All tier markers ratified per 0.9-collapse-candidates.md §0 + §14; carry-forward note simple.	—
§2. Database schema retires	(e) READY	All retire decisions ratified per collapse-candidates §2 + §12.1 + §12.2; nothing new to ratify.	—
§3. Pipeline + cocoindex absorption confirmations	(e) READY	All retire decisions ratified per collapse-candidates §12.3 + §12.4.	—
§4. Renames + lockstep retires	(e) READY	All renames + lockstep-with-migration retire patterns ratified per collapse-candidates §12.5 + §14.	—

Critical-path prerequisites: None. All 4 sections READY-TO-DRAFT.

Dependency on other sub-docs: Per INV §4 Layer 1 — Wave 1 parallel with 03-tech-stack.md. No upstream deps.

Liam in-session decision suggested (carried forward from INV §6): “Confirm whether 07-collapse-list.md should be a thin pointer doc (just tier markers + pointer back to 0.9-collapse-candidates.md §12-§14) or a fully self-contained collapse-list duplicating the content. The S232 Liam reframe direction suggests thin pointer.” — Recommendation: thin pointer doc.

---

08-new-features.md

Purpose (from INV §3): Knowledge Map (cocoindex substrate per CX.32); dedup-with-temporal; change-reports rename; scope_tag taxonomy; governance + freshness; bid-feedback loop; Cloud Run sidecar topology mention.

Suggested section structure (9 sections):

1. §1. Knowledge Map — cocoindex substrate per CX.32 RESOLVED-S232; surface scope STILL-OPEN per 00-synthesis-v2.md §5.2 row 4 (future S7 spike); mention-only at this stage.
2. §2. Dedup with temporal — UC8 RATIFIED S229 per 0.9-edit-flow-investigation.md §6.7 (next subsection to confirm), cocoindex entity_resolution selective adoption per Prereq 2 Rec 3.
3. §3. change_reports rename (was digests) — user-facing label is “Change Reports”; internal code still uses “digest” per CLAUDE.md Gotcha; rename digests → change_reports per decision-graph §11.3 row 7.
4. §4. scope_tag taxonomy + UC9 governance — UC9 RATIFIED S229 per §6.0.6 rollback-by-operation-ID; scope_tag rename surface; per-record concurrency + skip-and-report.
5. §5. Governance + freshness — KH governance freshness (fresh/aging/stale/expired) is the user-facing concept per Theme D; UC9 cross-workspace operations.
6. §6. Bid feedback loop (3-UC) — UC5 promotion (bid response → Q&A) + UC6 revision (Q&A pair revise) + UC8 dedup (cross-workspace merge); lost-bid promotion default skip per N10 RESOLVED-S234.
7. §7. Cloud Run sidecar topology — mention-only (full architecture in 02-data-flow.md §3); production-readiness track owns the build.
8. §8. Admin UI v1.1 extension — admin UI for client-managed vocabularies per Q-OQR1-13; extends existing settings-page pattern.
9. §9. Deferred / future features — workspace-private q_a_pairs (Q-OQR1-08 v1.1); data-driven form_type behaviour (Q-OQR1-14 v2); multi-wing content semantics (Q-OQR1-10 operational impl); Knowledge Map graph substrate (S7 spike).

Per-section readiness verdict:

Section title	Category	Rationale	Prereq if blocked
§1. Knowledge Map	(d) ratification needed	CX.32 cocoindex-substrate ratified; surface scope STILL-OPEN per synthesis-v2 §5.2 row 4 (S7 spike future); mention-only is the right level for this sub-doc, BUT what to call the surface (UI naming + access points) is undecided. Adversarial verdict (d): mention-only-with-name-TBD is honest; mention-only-with-full-naming is over-reach. Recommendation: write mention-only-with-TBD-naming; cross-reference S7 spike target as the disambiguation source.	Liam ratification: surface naming + access points for Knowledge Map. Or: explicit “TBD per S7 spike” framing.
§2. Dedup with temporal	(e) READY	UC8 ratifications per 0.9-edit-flow-investigation.md §6.7 (assumed — section structure confirms RATIFIED-S229); cocoindex entity_resolution per Prereq 2 Rec 3.	—
§3. change_reports rename	(e) READY	Decision-graph §11.3 row 7; cron + UI text updates listed; CLAUDE.md Gotcha already flags user-facing label.	—
§4. scope_tag taxonomy + UC9	(e) READY	UC9 RATIFIED S229 per §6.0.6 + §6.0.5 (downstream-impact UI); per-record concurrency model per 4.5.Q3.	—
§5. Governance + freshness	(e) READY	Theme D RESOLVED; CV 08 freshness CV per docs/ontology/08-freshness.md (LANDED-S236-S237).	—
§6. Bid feedback loop (3-UC)	(e) READY	UC5 + UC6 + UC8 ratifications per 0.9-edit-flow-investigation.md §6.5 + §6.6 + §6.7; lost-bid skip per N10 RESOLVED-S234.	—
§7. Cloud Run sidecar topology	(e) READY	§3.1 of synthesis-v2 establishes architecture; production-readiness track owns build; mention-only here.	—
§8. Admin UI v1.1 extension	(a) product spec needed	Q-OQR1-13 ratified the v1.1 deferral; existing settings-page pattern is the precedent; BUT the full set of admin sections (application_types, form_types, scope_tags, additional content-type management) for v1.1 is not yet specced. Adversarial verdict (a): PRODUCT.md needed for v1.1 admin UI scope and shape. Mention here as deferred + cross-link is fine; full spec belongs in a PRODUCT.md. Section can be drafted at mention-level with explicit “PRODUCT.md TBD for v1.1” flag.	PRODUCT.md for v1.1 admin UI (3-5 sub-sections per Q-OQR1-13). Section can land at mention-level; PRODUCT.md is a v1.1 feature-spec deliverable. Recommendation: write mention-level here; PRODUCT.md scope is a separate deliverable. Borderline (e) READY-with-PRODUCT.md-TBD if we accept mention-level scope. Adversarial verdict (a) flags the PRODUCT.md dependency explicitly.
§9. Deferred / future features	(e) READY	All deferrals ratified: Q-OQR1-08 workspace-private (v1.1); Q-OQR1-14 form_type behaviour (v2); Q-OQR1-10 multi-wing (operational); Knowledge Map S7 spike.	—

Critical-path prerequisites:

1. §1 Knowledge Map naming — Liam pre-decision OR explicit “TBD per S7 spike” framing. Minor.
2. §8 admin UI v1.1 scope — Liam pre-decision on whether mention-level is enough here OR if a PRODUCT.md is needed before this section can be drafted. Recommendation: mention-level + PRODUCT.md as v1.1 deliverable.

Dependency on other sub-docs: Per INV §4 — Wave 2 tail (AFTER 02 + 04 + 05 land). §1 mentions Knowledge Map data plane; §2/§4 reference q_a_pairs schema (anchors in 04-workspace-types.md); §6 references bid feedback loop (anchors in 05-qa-flow.md Q&A flow + UC ratifications). Cannot land before Wave 2 split (02 + 05) closes.

---

09-diagrams.md

Purpose (from INV §3): ERDs (workspaces + application_types + procurement_workspaces + content_items + q_a_pairs + citations + question_matches + source_documents); ingest flow with Cloud Run sidecar topology; Q&A round-trip; bid feedback 3-UC; auto-RLS event trigger sequence.

Suggested section structure (7 sections):

1. §1. ERD — workspaces + application_types + per-app satellites — workspaces.application_type_id FK to application_types instance table; procurement_workspaces satellite; future sales_proposal_workspaces etc. (placeholder); kb_section retired (NOT in ERD).
2. §2. ERD — content_items + q_a_pairs + q_a_extractions + citations + question_matches — corpus-level q_a_pairs (NO workspace FK); nullable source_workspace_id; citations.citing_entity polymorphic enum; question_matches.question_kind discriminator; separate embedding_score + fulltext_score columns.
3. §3. ERD — source_documents + cocoindex source-key + content_history + audit_log — source_documents.workspace_id nullable; cocoindex source-key relationship; audit_log separate from cocoindex ops-DB ledger; op_id propagation pattern (trigger-driven + cocoindex per-flow hybrid).
4. §4. Sequence — ingest flow with Cloud Run sidecar topology — Vercel API → Cloud Run sidecar (Docling) → cocoindex flow → content_text → ExtractByLlm → embedding + entity extraction → audit_log; per-MIME branching (PDF / DOCX / XLSX / HTML / markdown).
5. §5. Sequence — Q&A round-trip (write-back + re-extraction) — UC1 typo fix Candidate A + UC4 paragraph rewrite + UC6 revision (user-direct + AI-suggest); citation re-anchor hybrid; version-on-cite at ship time.
6. §6. Sequence — bid feedback 3-UC — UC5 bid response → Q&A promotion + UC6 revision + UC8 dedup merge; per-record rollback by op-ID.
7. §7. Sequence — auto-RLS event trigger — DDL CREATE TABLE public.* → rls_auto_enable() event trigger → enable row level security + grants block per Item 1 + Item 2; flagged interaction with combined-PR migration.

Per-section readiness verdict:

Section title	Category	Rationale	Prereq if blocked
§1. ERD — workspaces + application_types + satellites	(e) READY	All schemas final per 04-workspace-types.md §1 + §2 + §4 + §5; ERD renders prose schemas verbatim.	Sequencing-only — 04-workspace-types.md lands first.
§2. ERD — content_items + q_a_pairs + q_a_extractions + …	(e) READY	All schemas final per 04-workspace-types.md §7 + §8 + 05-qa-flow.md §6 + §7; supersedes 0.9-intended-architecture.md §15 illustrative ERD.	Sequencing-only — 04-workspace-types.md + 05-qa-flow.md land first.
§3. ERD — source_documents + cocoindex source-key + …	(e) READY	All schemas final per 04-workspace-types.md §9 + 02-data-flow.md §1 + §4; supersedes 0.9-intended-architecture.md §15 illustrative ERD.	Sequencing-only — 04-workspace-types.md + 02-data-flow.md land first.
§4. Sequence — ingest flow with Cloud Run sidecar	(e) READY	All architecture final per 02-data-flow.md §2 + §3 + 03-tech-stack.md §3.	Sequencing-only — 02-data-flow.md + 03-tech-stack.md land first.
§5. Sequence — Q&A round-trip	(e) READY	UC1 + UC4 + UC6 ratifications per 0.9-edit-flow-investigation.md §6.1 + §6.4 + §6.6; cross-UC §6.0.2 + §6.0.3.	Sequencing-only — 05-qa-flow.md §8 + §9 lands first.
§6. Sequence — bid feedback 3-UC	(e) READY	UC5 + UC6 + UC8 ratifications per 0.9-edit-flow-investigation.md §6.5 + §6.6 + §6.7.	Sequencing-only — 05-qa-flow.md §9 + 08-new-features.md §6 land first.
§7. Sequence — auto-RLS event trigger	(e) READY	Item 2 SQL ratified verbatim in supabase-db-action-items.md; pair with Item 1 grants block.	Sequencing-only — 02-data-flow.md §5 (RLS pattern) lands first; OR if separate docs/specs/rls-pattern/ track, that lands first.

Critical-path prerequisites: All 7 sections (e) READY-TO-DRAFT pending sequencing. No new ratifications needed. The risk is fidelity drift — 09-diagrams.md must render exactly what 02/04/05/08 prose says, no schema changes “in the diagram” that aren’t in the prose. INV §7.3 flags this risk.

Dependency on other sub-docs: Per INV §4 Layer 3 — 09-diagrams.md is downstream of every other sub-doc by definition. Must land AFTER 02 + 04 + 05 + 08 close.

---

Critical-path prerequisites for S239 Wave 1

Per INV §6, S239 Wave 1 = 03-tech-stack + 07-collapse-list parallel (with 01-vision-mission already landed S238 pilot). What MUST land BEFORE the Wave 1 dispatch:

1. Liam pre-decision: RLS-PATTERN destination — separate docs/specs/rls-pattern/{PRODUCT.md,TECH.md} vs inline-in-02-data-flow.md §5. Affects 02-data-flow.md §5 + 04-workspace-types.md §12 only — does NOT block Wave 1 (03 + 07). Recommendation: separate doc per INV §7.4. Time-cost: ~1-line ratification. Suggested at S239 kickoff; no blocking for Wave 1.

2. Liam in-session decision: 07-collapse-list.md shape — thin pointer doc (per INV §6 S238 in-session decision recommendation) vs fully self-contained. Affects 07-collapse-list.md directly. Recommendation per S232 reframe: thin pointer. Time-cost: ~1-line ratification. Suggested at S239 kickoff before Wave 1 dispatch.

3. Liam pre-decision: Theme F MCP-action review pass — blocks 06-mcp-tooling.md entirely. Does NOT block Wave 1 (03 + 07). Recommendation: surface as a standing pre-decision item; whichever wave Theme F lands at, dispatch 06-mcp-tooling.md as a parallel worktree sub-agent at that wave.

4. (Wave 2 prereq, not Wave 1): Liam disambiguation on 04-workspace-types.md §4 per-application-type satellites scope — procurement-only-with-schema-seats-for-others (recommended) vs full 5-satellite spec. Suggested at S239 Wave 2 kickoff, not Wave 1. Borderline-(b) → (e) READY hinges on this.

5. (Wave 2 prereq, not Wave 1): Liam ratification on 08-new-features.md §1 Knowledge Map naming + §8 admin UI v1.1 mention-vs-PRODUCT.md scope. Suggested at S239 Wave 2 tail kickoff (when 08-new-features.md dispatches), not Wave 1.

Bottom line: Wave 1 (03-tech-stack + 07-collapse-list) has no Liam-blocking prereqs. Only the 07-collapse-list.md shape ratification (thin pointer vs self-contained) is worth a 1-line confirmation at S239 kickoff before dispatch. All five items above are 1-line ratifications, not investigations or specs.

---

Sequencing recommendation (refines INV §6 wave plan)

Refinement of the INV §6 wave structure based on the per-section audit findings:

Wave 1 (S239 kickoff) — Layer 1 sub-docs

Targets: 03-tech-stack.md, 07-collapse-list.md (parallel; 01-vision-mission.md already landed S238 pilot).

Refinement: Confirmed INV §6 Wave 1 — both targets are 9 + 4 = 13 sections, all (e) READY-TO-DRAFT. No prereqs.

Pre-dispatch ratifications: 07-collapse-list.md thin-pointer-vs-self-contained shape (1 line).

Dispatch shape: Two parallel worktree sub-agents.

Wave 2 main (S239 mid) — 04-workspace-types.md foreground

Refinement: Confirmed INV §6 Wave 2 main — biggest sub-doc; 13 sections; 10 (e) READY + 2 (b) borderline + 1 (d) RLS-PATTERN cross-decision.

Pre-dispatch ratifications: §4 per-application-type satellites scope (procurement-only-with-seats vs full 5-satellite); §12 RLS-PATTERN destination (shared with 02-data-flow.md §5).

Dispatch shape: Foreground main session (sequential; high cross-coupling, downstream-blocking).

Wave 2 split (S239 tail) — 02-data-flow.md + 05-qa-flow.md parallel

Refinement: Confirmed INV §6 Wave 2 split. 02-data-flow.md has 8 (e) + 1 (b) + 1 (d); 05-qa-flow.md has 9 (e) + 1 (a) + 1 (b).

Pre-dispatch ratifications: None (consumed at Wave 2 main).

Dispatch shape: Two parallel worktree sub-agents AFTER 04-workspace-types.md lands.

Wave 2 tail (S239 close / S240 start) — 08-new-features.md

Refinement: Confirmed INV §6 Wave 2 tail. 7 (e) + 1 (a) + 1 (d).

Pre-dispatch ratifications: §1 Knowledge Map naming; §8 admin UI v1.1 mention-vs-PRODUCT.md (both 1-line).

Dispatch shape: Foreground main (cross-references 02 / 04 / 05; main-context coherence valuable).

Wave 3 (S240) — 09-diagrams.md

Refinement: Confirmed INV §6 Wave 3. All 7 sections (e) READY pending sequencing.

Pre-dispatch ratifications: None.

Dispatch shape: Foreground main (high coherence cost; ERDs need cross-doc consistency check).

Independent track (any wave when Theme F lands) — 06-mcp-tooling.md

Refinement: Confirmed INV §6 independent track. 8 (d) ratification needed.

Pre-dispatch ratifications: Theme F MCP-action review pass — THE blocker.

Dispatch shape: Parallel worktree sub-agent at whichever wave Theme F closes.

Honest sequencing flag

The wave plan is sound. The main risk surface is 04-workspace-types.md §4 (per-application-type satellites scope) — if Liam wants all 5 satellites schema-defined, that becomes a tech-spec-needed-first dependency that ripples to Wave 2 split (02 + 05 reference satellites). Recommendation: procurement-only-with-schema-seats-for-others scope keeps Wave 2 split clean.

The secondary risk is 09-diagrams.md fidelity drift — INV §7.3 flagged this. Mitigation: explicit verification gate at Wave 3 that every schema in a diagram appears in the corresponding prose sub-doc.

---

Risks + flags for Liam

Risk 1 — Forward-references in 04-workspace-types.md §4 (per-application-type satellites)

If the sub-doc tries to fully specify all 5 application-type satellites (procurement / sales_proposal / competitor_research / training_onboarding / product_guide), it pulls in tech-spec scope per (b) verdict. Mitigation: scope to procurement-only-with-schema-seats-for-others. Future-application satellite columns specced at that application’s build time. Confirms Q-OQR1-13 admin-UI v1.1 deferral.

Risk 2 — RLS-PATTERN destination decision affects 2 sub-docs

02-data-flow.md §5 and 04-workspace-types.md §12 both touch RLS pattern. Without a destination decision, two parallel sub-agents may write contradictory framings. Mitigation: Liam 1-line pre-decision before Wave 2 dispatch. INV §7.4 recommends separate docs/specs/rls-pattern/{PRODUCT.md,TECH.md} — same convention as other Phase 0.9 specs.

Risk 3 — Theme F MCP-action review is the lone STILL-OPEN gate

06-mcp-tooling.md is 8 sections all (d) ratification needed per audit. The audit categorises conservatively per the prompt’s “gated on Theme F” framing. If Liam wants 06-mcp-tooling.md to land Wave 1 in parallel with 03 + 07, sections §1 + §6 + §7 + §8 are likely (e) READY-with-Theme-F-disclaimer (architecture-level stable, tool/app inventory contents would shift). Sections §2 + §3 + §4 + §5 remain genuinely blocked on Theme F. Mitigation: Liam ratifies Theme F at S239 kickoff (1-line: “direct mempalace MCP” vs “wrap mempalace tools within KH MCP server”).

Risk 4 — 01-vision.md pilot heritage-doc framings

The S238 pilot of 01-vision.md cites four heritage docs (Platform Overview / Claude Integration Guide / AI Integration Strategy / Product Differentiation Audit) with explicit staleness markers per pilot §7.1. Flag for Liam: subsequent sub-docs should follow the pilot’s discipline — cite heritage docs sparingly + only where heritage framing is uniquely load-bearing. Re-litigating positioning in every sub-doc creates drift. The pilot §1.3 and §7.1 are the model.

Risk 5 — Diagram drift in 09-diagrams.md

INV §7.3 flagged that 0.9-intended-architecture.md §15 has 3 illustrative diagrams predating S235/S236 ratifications. The sub-doc writer for 09-diagrams.md must treat §15 as “predecessor sketch only — redraw from 02/04/05 schemas verbatim”. Mitigation: verification gate at Wave 3 — no schema appears in a diagram that doesn’t appear in the corresponding prose sub-doc.

Risk 6 — 0.9-intended-architecture.md archival timing

INV §1 + §7.1 flag that the source doc predates the S233-S237 ratifications. Pilot §7 notes the archival convention. Confirm at S239 kickoff: source doc archives to .planning/.archive/.specs/0.9-intended-architecture.md AFTER 09-diagrams.md (Wave 3) closes. Not before.

Flag 1 — UK English + no budget/day-count terminology

CLAUDE.md “Key Product Design Principles” + S231+ ban on budget/day-count framing apply to all 7 sub-docs. The S229 source doc’s “DO during architecture-impl phase (~3-5d)” framings (per INV §2 row 7) and the Q-OQR1-13 v1 admin-UI “~5-10d for the admin surfaces” framing in WP-ONTO-R1 §8.4 are explicitly out of scope. Sub-doc writers must enforce.

Flag 2 — Heritage-doc citation discipline

Pilot §7.1 lists 4 heritage docs as canonical for their own scope but stale for Phase 0.9 ratifications. Subsequent sub-docs should adopt the same explicit-staleness convention. Recommend: verifier gate per sub-doc: “if heritage doc is cited, is the cite scoped to where heritage doc is uniquely load-bearing, OR does it duplicate a Phase 0.9 ratification?”

Flag 3 — Cross-sub-doc duplication policy

Anti-pattern lists appear in 01-vision.md §6, 02-data-flow.md §9, 04-workspace-types.md §13, 05-qa-flow.md §11. Recommend: each sub-doc carries its own scoped anti-patterns; cross-references are explicit. Avoids drift from synchronised duplication.

---

End of per-sub-doc readiness audit. 71 sections covered across 7 active + 1 gated sub-doc; 54 (e) READY + 2 (a) product spec + 4 (b) tech spec + 0 (c) investigation + 11 (d) ratification needed. Theme F MCP-action review pass is the lone STILL-OPEN-as-of-S238 gate blocking 8 of 11 (d) items. All other (d) items are 1-line Liam pre-decisions surfaceable at S239 kickoff or Wave 2 kickoff. No investigation spikes block any of the 7 active sub-docs — Phase 0.9 investigation arc is closed for WP4 entry per 00-synthesis-v2.md §4.