08 — New features (Wave 2 tail)
08 — New features (Wave 2 tail)
Section titled “08 — New features (Wave 2 tail)”Last verified: 15/05/2026 (S240 — Wave 2 tail; drafted foreground after Wave 2 split + 06-mcp-tooling landed)
Status:
[CURRENT-CANONICAL]— Wave 2 tail, drafted S240 after Wave 2 split (02 + 05) closed. Layer: L2 cross-cutting — references schemas anchored in04-workspace-types.md; references flow stages anchored in02-data-flow.md; references Q&A surfaces anchored in05-qa-flow.md; references MCP tooling anchored in06-mcp-tooling.md. Companion sub-docs:01-vision.md(positioning),02-data-flow.md(ingest + Cloud Run sidecar),03-tech-stack.md(v1 stack),04-workspace-types.md(schemas),05-qa-flow.md(Q&A domain),06-mcp-tooling.md(MCP tooling),07-collapse-list.md(retire register).
1. Mission
Section titled “1. Mission”This sub-doc covers the cross-application-type features that depend on the schemas, flows, and surfaces established in the earlier Wave 2 sub-docs. Features here either span more than one application_type (bid-feedback loop, scope_tag governance) or sit above the data-plane substrate (Knowledge Map surface, admin UI extension, governance freshness). Where a feature anchors its load-bearing schema in 04-workspace-types.md or its load-bearing flow in 02-data-flow.md, the cross-reference is by section number — this sub-doc does not duplicate schema or flow content.
Two open-question scopes carry-forward from S239 into this sub-doc explicitly: (a) Knowledge Map surface scope — STILL-OPEN per 00-synthesis-v2.md §5.2 row 4; mention-only at this layer pending a future S7 spike; (b) v1.1 admin UI — Q-OQR1-13 ratifies the v1.1 deferral, but the per-section admin scope (which client-managed vocabularies surface and in what shape) is a v1.1 PRODUCT.md deliverable, not an architecture decision.
2. Knowledge Map
Section titled “2. Knowledge Map”2.1 Substrate
Section titled “2.1 Substrate”The Knowledge Map data plane runs on cocoindex as the graph substrate per CX.32 (RATIFIED-S232 per 0.9-decision-graph.md §11.2 + 00-synthesis-v2.md §3.1). No separate graph database is added for v1 — cocoindex entity_resolution operations + the existing entity / relationship tables provide the substrate.
2.2 Surface scope — STILL-OPEN
Section titled “2.2 Surface scope — STILL-OPEN”The user-facing surface (UI naming + access points + interaction model) for the Knowledge Map is STILL-OPEN. Category per construction guide §5.2: investigation needed — the substrate is settled, but how it surfaces to users (a sidebar panel, a dedicated route, an embedded widget, a query-by-example interface) is not. Sources checked: 00-synthesis-v2.md §5.2 row 4 (canonical STILL-OPEN register entry); 0.9-decision-graph.md §11.4.2 row 6 (future S7 spike); S239-still-open-consolidation.md item 8.
Suggested prerequisite work: S7 spike (pre-launch) — investigate surface options + Liam ratification of naming + access points.
Mention-only at this layer. This sub-doc records the substrate decision and the STILL-OPEN surface flag. The surface PRODUCT.md is a separate deliverable.
2.3 What lands in v1 from the Knowledge Map work
Section titled “2.3 What lands in v1 from the Knowledge Map work”Cocoindex entity_resolution selective adoption (per phase-b-prerequisite-2-cocoindex-deep-dive.md Rec 3) lands in v1 as part of the dedup-with-temporal work in §3 below. This is the infrastructural half of the Knowledge Map. The surface half is the S7 spike deferral.
3. Dedup with temporal
Section titled “3. Dedup with temporal”3.1 UC8 — RATIFIED S229
Section titled “3.1 UC8 — RATIFIED S229”UC8 (cross-workspace dedup + merge) is RATIFIED-S229 per 0.9-edit-flow-investigation.md §6.8. The architecture-level direction is settled: dedup detection runs via cocoindex entity_resolution selective adoption (per phase-b-prerequisite-2-cocoindex-deep-dive.md Rec 3 — only on entity types where dedup is high-value); user-driven merge / supersede / proceed-anyway resolution per the cross-UC §6.0.5 downstream-impact UI pattern.
3.2 Temporal scope
Section titled “3.2 Temporal scope”Dedup runs against the q_a_pairs corpus (cross-workspace per 04-workspace-types.md §5 corpus-level shape) and the content_items corpus. Temporal binding (which version of a record is the “canonical” for the dedup pass) follows the version-on-cite pattern per 05-qa-flow.md §6.3 — citations bind to specific Q&A pair revision IDs, so dedup that produces a merge ships a new revision rather than retroactively rewriting the prior revision’s citation surface.
3.3 Cocoindex entity_resolution scope
Section titled “3.3 Cocoindex entity_resolution scope”Selective adoption — entity types in scope: organisations (Q-OQR1-S231 RESOLVED), people (companions of organisations), products / services (high-overlap categories per the bid corpus). Out of scope for v1: free-text concepts (lossy normalisation; deferred to v2 per 0.9-decision-graph.md §11.4.2).
4. change_reports rename (was digests)
Section titled “4. change_reports rename (was digests)”4.1 The rename
Section titled “4.1 The rename”digests → change_reports per 0.9-decision-graph.md §11.3 row 7. The user-facing label has been “Change Reports” already per the CLAUDE.md gotcha (“‘Change Reports’ not ‘Digest’”); the rename closes the residual divergence between user-facing labels and internal table / column / cron names. Lands as part of the Q-OQR1-16 combined PR (RATIFIED-S235, migration STILL-OPEN per 0.9-decision-graph.md §11.3).
4.2 Scope of the rename
Section titled “4.2 Scope of the rename”| Surface | Current | Renamed |
|---|---|---|
| Table | digests | change_reports |
| Cron entry / cocoindex flow | digest-generate (informal) | change-reports-generate |
| UI route / surface | already “Change Reports” | (no change) |
Internal helpers in lib/digest/ | lib/digest/* | lib/change-reports/* |
The CLAUDE.md gotcha is updated as part of the rename PR.
4.3 Lockstep with combined-PR migration
Section titled “4.3 Lockstep with combined-PR migration”[LOCKSTEP-WITH-MIGRATION] — the rename ships in the Q-OQR1-16 combined PR per 04-workspace-types.md §8 (combined-PR walkthrough). No standalone migration; the rename does not block features that consume change reports.
5. scope_tag taxonomy + UC9 governance
Section titled “5. scope_tag taxonomy + UC9 governance”5.1 UC9 — RATIFIED S229
Section titled “5.1 UC9 — RATIFIED S229”UC9 (scope_tag governance — rename / split / merge across the corpus) is RATIFIED-S229 per 0.9-edit-flow-investigation.md §6.0.6 rollback-by-operation-ID and §6.0.5 downstream-impact UI. The architecture-level direction is settled: scope_tag operations run cross-workspace, are bound by audit_log.op_id (per 02-data-flow.md §5 hybrid pattern), and present a per-record downstream-impact preview before commit.
5.2 Per-record concurrency
Section titled “5.2 Per-record concurrency”Per-record concurrency model per cross-UC 4.5.Q3 RATIFIED-S229 — when two UC9 operations target the same record concurrently, the second operation receives a stale-read error and the user is prompted to refresh + retry. Skip-and-report is the fall-back where the operation can semi-cleanly proceed for the unaffected records (the canonical pattern per UC9 implementation).
5.3 Rollback by operation ID
Section titled “5.3 Rollback by operation ID”Rollback uses the audit_log.op_id propagation pattern from 02-data-flow.md §5 — every UC9 commit assigns a single op_id at the operation root and propagates to every audit_log row in scope. Rollback iterates audit_log rows by op_id in reverse + applies the inverse of each entry. Failure-mode handling per the UC9 4.5.Q3 specification.
6. Governance + freshness
Section titled “6. Governance + freshness”6.1 KH governance freshness is the user-facing concept
Section titled “6.1 KH governance freshness is the user-facing concept”Per Theme D RESOLVED (02-data-flow.md §9 substrate separation): the user-facing freshness concept is KH governance freshness — content_items.freshness enum fresh / aging / stale / expired. Cocoindex ingest-latency freshness is operational (per-flow-run staleness; not user-visible). The two substrates do NOT merge per 02-data-flow.md §9.
6.2 Freshness CV LANDED-S236-S237
Section titled “6.2 Freshness CV LANDED-S236-S237”The freshness controlled vocabulary lives at docs/ontology/08-freshness.md (LANDED-S236-S237 per WP6 ontology MD scaffold). The CV defines the four values + the transition rules (time-based aging triggers + content-edit triggers per 02-data-flow.md §8 edit re-classification policy).
6.3 UC9 cross-workspace operations + freshness
Section titled “6.3 UC9 cross-workspace operations + freshness”UC9 operations (scope_tag rename / merge / split — §5 above) interact with freshness: an operation that mass-renames a scope_tag does NOT reset the per-record freshness, since the underlying content is unchanged. The freshness substrate tracks content freshness, not metadata freshness.
7. Bid feedback loop (3-UC composite)
Section titled “7. Bid feedback loop (3-UC composite)”7.1 The three UCs
Section titled “7.1 The three UCs”The bid feedback loop composes three already-ratified user-cases:
| UC | Action | Architecture anchor | Ratification |
|---|---|---|---|
| UC5 | Bid response → Q&A pair promotion | 05-qa-flow.md §9 | RATIFIED-S229 per 0.9-edit-flow-investigation.md §6.5 |
| UC6 | Q&A pair revise (user-direct + AI-suggest) | 05-qa-flow.md §8 | RATIFIED-S229 per 0.9-edit-flow-investigation.md §6.6 |
| UC8 | Cross-workspace dedup (this sub-doc §3) | This sub-doc §3 | RATIFIED-S229 per 0.9-edit-flow-investigation.md §6.8 |
7.2 Lost-bid promotion default skip
Section titled “7.2 Lost-bid promotion default skip”N10 RESOLVED-S234 (per 0.9-decision-graph.md §11.4.1 N10): a bid response from a lost bid defaults to skip (the response is not auto-promoted to a Q&A pair). The user can override per-response with explicit promotion. Won-bid responses default to promote (UC5 happy path). The default-skip for lost bids prevents corpus pollution with answers that the buyer rejected.
7.3 Closed-loop discipline
Section titled “7.3 Closed-loop discipline”The bid feedback loop is the v1 user-data-quality flywheel: bid responses produce Q&A pairs (UC5), Q&A pairs get refined by users / AI (UC6), and the resulting corpus is deduplicated cross-workspace (UC8). The composition is the load-bearing v1 product capability; each UC is independently ratified, and their composition is documented here at the cross-cutting layer.
8. Cloud Run sidecar topology — mention-only
Section titled “8. Cloud Run sidecar topology — mention-only”The Docling + sidecar architecture is owned by 02-data-flow.md §4. This sub-doc records that the operational build of the Cloud Run sidecar (deployment, scaling, cost projection, observability) is owned by the production-readiness track per CLAUDE.md “Parallel Tracks” — the architecture record is here; the production build is tracked in docs/tracks/production-readiness.md. Mention-only at this layer; no new architecture content.
9. Admin UI v1.1 extension
Section titled “9. Admin UI v1.1 extension”9.1 Q-OQR1-13 v1.1 deferral
Section titled “9.1 Q-OQR1-13 v1.1 deferral”Admin UI for client-managed vocabularies — application_types, form_types, scope_tags, content-type management — is deferred to v1.1 per Q-OQR1-13 RATIFIED-S235 (00-synthesis-v2.md §3.13). v1 ships the 6 baseline application_types via SQL seed (per 04-workspace-types.md §3.2); client-added types in v1 require a migration; the v1.1 admin UI removes this constraint by surfacing add / edit / deprecate operations on the underlying vocabularies.
9.2 Architectural precedent
Section titled “9.2 Architectural precedent”Per phase-b-prerequisite-1-onthology-pipeline-feedback-investigation.md §6.2: the v1.1 admin UI extends the existing settings-page pattern (taxonomy / tags / guides / layers / entities / governance sections precedent). No new framework; new sections added to the existing pattern.
9.3 Gap flag — admin UI scope PRODUCT.md
Section titled “9.3 Gap flag — admin UI scope PRODUCT.md”The per-section admin scope (which sections ship, in what order, with what behaviour) is a v1.1 PRODUCT.md deliverable per construction guide §5.2 (a) product spec needed. Sources checked: 00-synthesis-v2.md §3.13 (v1.1 deferral); phase-b-prerequisite-1-onthology-pipeline-feedback-investigation.md §6.2 (precedent pattern); readiness audit §08-new-features.md §8 verdict. Suggested prerequisite work: open docs/specs/admin-ui-v1.1/PRODUCT.md ahead of the v1.1 build cycle.
Mention-level only at this architecture layer; the PRODUCT.md owns the per-section scope.
10. Deferred / future features
Section titled “10. Deferred / future features”10.1 Deferral register
Section titled “10.1 Deferral register”| Feature | Ratification | Source | When |
|---|---|---|---|
Workspace-private q_a_pairs (private_to_workspace_id) | Q-OQR1-08 deferred v1.1 | 00-synthesis-v2.md §3.10 | v1.1 |
Data-driven form_type behaviour | Q-OQR1-14 deferred v2 | 00-synthesis-v2.md §3.14 | v2 |
| Multi-wing content semantics — operational impl | Q-OQR1-10 deferred operational | 00-synthesis-v2.md §3.12 | post-launch operational |
| Knowledge Map surface scope (§2.2) | STILL-OPEN; future S7 spike | 00-synthesis-v2.md §5.2 row 4 | pre-launch S7 spike |
| RLS auto-enable observability hook (P-5 from RLS-PATTERN) | DEFERRED-v1.1 per S240 Liam ratification | docs/specs/rls-pattern/PRODUCT.md P-5 | v1.1 if operational signal surfaces need |
| Admin UI v1.1 (§9) | Q-OQR1-13 RATIFIED-S235; v1.1 deliverable | 00-synthesis-v2.md §3.13 | v1.1 |
| Migration to wrapped MCP pattern (mempalace) | DEFERRED-POST-LAUNCH per Theme F S240 | docs/specs/core-docs-pathway-assessment/theme-f-mempalace-investigation.md | post-mempalace-v4-standalone |
| mempalace Shape B strict-extract MCP mode | DEFERRED-POST-LAUNCH per Theme F S240 (predecessor §7) | predecessor 0.9-intended-architecture-archived-s242.md §7 (Shape B); 06-mcp-tooling.md §4 direct-pattern ratification | post-mempalace-v4-standalone — gated on the same external mempalace upgrade as the wrapped-pattern migration |
User-memory MCP tools (save_user_memory / recall_user_memory / forget_user_memory) | DEFERRED-POST-LAUNCH per Theme F S240 (predecessor §9 — 3 of the 8 named tools) | predecessor 0.9-intended-architecture-archived-s242.md §9 (per-user-memory tool surface); 06-mcp-tooling.md §4 (KH MCP does not wrap these tools in v1) | post-mempalace-v4-standalone — wrapped via mempalace’s own MCP surface, not re-implemented inside KH MCP |
10.2 Why one register matters
Section titled “10.2 Why one register matters”The deferral register is the single source of truth for what is v1.1+ vs out-of-scope. Cross-application coupling makes scattered deferrals expensive to track per-sub-doc — surfaces here so any sub-doc author can confirm a deferral status in one place rather than re-reading the canonical register.
11. Cross-doc references
Section titled “11. Cross-doc references”11.1 Schemas anchored in 04-workspace-types.md
Section titled “11.1 Schemas anchored in 04-workspace-types.md”- §3 application_types instance table → cited by §3 dedup, §7 bid loop
- §4 satellite pattern + reserved seats (forward-ref to
docs/specs/reserved-workspace-seats/) → cited by §9 admin UI extension - §5 q_a_pairs corpus-level → cited by §3 dedup
- §8 combined-PR walkthrough → cited by §4 change_reports rename
11.2 Flow stages anchored in 02-data-flow.md
Section titled “11.2 Flow stages anchored in 02-data-flow.md”- §3 cocoindex flow stages → cited by §3 dedup (entity_resolution)
- §4 Cloud Run sidecar → cited by §8 (mention-only deferral to production-readiness track)
- §5 audit_log + op_id propagation → cited by §5 UC9 rollback
- §9 freshness substrate separation → cited by §6 governance freshness
11.3 Q&A surfaces anchored in 05-qa-flow.md
Section titled “11.3 Q&A surfaces anchored in 05-qa-flow.md”- §8 UC6 write-back → cited by §7 bid feedback loop
- §9 UC5 promotion → cited by §7 bid feedback loop
- §6 citations + version-on-cite → cited by §3 dedup temporal binding
11.4 MCP tooling anchored in 06-mcp-tooling.md
Section titled “11.4 MCP tooling anchored in 06-mcp-tooling.md”- §4 mempalace direct pattern → cited by §10 deferral register (migration to wrapped post-launch)
- §6 MCP-action review pass → orthogonal; surfaces tools that operate on the entities this sub-doc cross-couples
11.5 Diagrams deferred to 09-diagrams.md
Section titled “11.5 Diagrams deferred to 09-diagrams.md”- §3 dedup flow sequence diagram
- §7 bid feedback loop sequence (3-UC composite)
- §6 freshness state-transition diagram
12. Source-doc supersession
Section titled “12. Source-doc supersession”Not applicable — 08-new-features.md is a NEW Wave 2 tail sub-doc. The cross-cutting features documented here aggregate ratifications established elsewhere (decision-graph + synthesis-v2 + per-UC investigations); no single predecessor doc.
12.1 Heritage docs feeding this sub-doc
Section titled “12.1 Heritage docs feeding this sub-doc”Per architecture-sub-doc-construction-guide.md §4.1 — three-tier status taxonomy.
| Doc | Date | Status | Useful for |
|---|---|---|---|
docs/plans/phase-0-investigation/0.9-edit-flow-investigation.md §6.5 + §6.6 + §6.8 | 14/05/2026 (S229 ratifications) | [CURRENT-CANONICAL] for UC5 (§6.5) + UC6 (§6.6) + UC8 (§6.8) ratifications. | Source for §7 bid feedback loop substrate. |
docs/plans/phase-0-investigation/0.9-decision-graph.md §11.3 + §11.4.1 + §11.4.2 | 14/05/2026 | [CURRENT-CANONICAL] for combined-PR scope + N10 + Theme F + Knowledge Map deferrals. | Source for §4 + §7.2 + §10 deferral register. |
docs/plans/phase-0-investigation/10-feedback-investigation-findings/00-synthesis-v2.md §2.3 + §3.13 + §5.2 | 14/05/2026 (S236 refreshes) | [CURRENT-CANONICAL] for v1.1 admin UI deferral + STILL-OPEN register entries. | Source for §9 + §10 + §2.2 STILL-OPEN framing. |
docs/plans/phase-0-investigation/phase-b-prerequisite-2-cocoindex-deep-dive.md Rec 3 | 14/05/2026 (S232 ratifications) | [CURRENT-CANONICAL] for cocoindex entity_resolution selective adoption. | Source for §3 dedup-with-temporal substrate. |
docs/plans/phase-0-investigation/phase-b-prerequisite-1-onthology-pipeline-feedback-investigation.md §6.2 | 14/05/2026 | [CURRENT-CANONICAL] for admin UI settings-page precedent pattern. | Source for §9 architectural precedent. |
docs/specs/core-docs-pathway-assessment/theme-f-mempalace-investigation.md | 15/05/2026 (S240 — NEW) | [CURRENT-CANONICAL] for direct-pattern ratification + post-launch migration to wrapped option. | Source for §10 deferral register entry on wrapped MCP pattern. |
| CLAUDE.md “‘Change Reports’ not ‘Digest’” gotcha | (ongoing) | [CURRENT-CANONICAL] for the user-facing label discipline. | Source for §4 rename rationale. |
End of sub-doc. Mid-density Wave 2 tail — cross-cuts the application-type-spanning features that depend on the earlier sub-docs (02 / 04 / 05 / 06) without re-defining their content.