Phase 0.9 — Edit-Flow Investigation (OQ1 implementation)

Status: RATIFIED — §1-§6 + §9-§10 populated. §6 cross-UC consolidated decisions + per-UC Candidate A/B/C choices ratified S229 via sequential AskUserQuestion rounds (Liam). Hand-off to sub-agent B (architecture rewrite) + spike phase. Audit date: 2026-05-10 (S228 start; §5/§6 populated S229) Branch: content-items-investigation Predecessor: 0.9-decision-graph.md Q2.9 (PRINCIPLE-RATIFIED + IMPLEMENTATION-PENDING → now RESOLVED via §6) + 0.9-context.md §4 Successor: populates 0.9-intended-architecture.md §2.3 / §5.1 / §5.2 (sub-agent B); refines 0.9-spike-plan.md S9 + S10 + adds optional S14 Anthropic citations re-anchor study.

0. Why this doc exists

Liam ratified the principle: one golden record, two-way semantics. Implementation is OPEN. Liam’s S228 directive: identify use cases FIRST so tooling evaluation is grounded in real flows, not the other way round.

Sequence:

Use-case identification (this doc, §1-§3)
Data flow mapping per use case (§4 — populated after §1-§3 ratified)
Tooling-fit evaluation per data flow (§5 — populated after §4)
Architectural decision (§6 — output: chosen implementation)
Feed back into 0.9-intended-architecture.md rewrite

Do not skip ahead. Each step’s output grounds the next.

1. Edit taxonomy — the axes

Every edit can be characterised across these axes. Each use case below picks a value on each.

1.1 Edit complexity

Level	Example
Atomic	Single word fix; date change; number/version bump; person/role name correction
Bounded	Single paragraph rewrite; fact correction within a section; clarification add
Sweeping	Apply one change everywhere it appears (brand rename; policy reference update; recurring boilerplate fix)
Structural	Doc reorganisation; section split/merge; reorder; section deletion
Compositional	Synthesise new content from multiple existing sources (curated Q&A pair from corpus chunks; new policy from bid responses)

1.2 Trigger

Per Liam S228: “upload” in two-way-pure + external-folder-canonical world is upload TO the external folder, not to the platform. Platform-as-upload-destination is a legacy flow being retired.

Trigger	Description
User-direct (in-platform)	User edits in platform UI; write-back propagates to external folder file
User-upload (to external folder)	User adds/replaces a file in the connected folder (LocalFS / SharePoint / Notion); cocoindex source binding detects + ingests
User-promote	User approves promotion of a bid response → curated Q&A pair (KH-DB derivative; no folder file)
AI-suggest	Dedup / conflict-detection agent surfaces change for user approval
Scheduled	Expiry/freshness rule triggers maintenance prompt
External-edit	User edits the source file in the external folder outside the platform; cocoindex detects on next scan / webhook

1.3 Canonical-update target (where does the change land?)

Target	Description
External-folder-file	Change written back to source file (.md / .docx / .pdf) in the connected folder
KH-DB-only	Change in platform DB only; folder file unchanged (e.g. derived data, scope tags, metadata)
Both-sidecar	Change lands in DB + propagates to a sibling sidecar `.md` file in the folder (binary stays RO)
Both-regenerate	Change lands in DB + binary regenerated (markdown → docx via pandoc, etc.)

1.4 Propagation scope

Scope	Description
Single-record	One content item only
Multi-doc	Multiple content items (cross-doc references, e.g. shared Q&A)
Workspace-wide	Affects all content in workspace (scope-tag taxonomy update)
Cross-workspace	Affects multiple clients (rare; e.g. KH-platform-level taxonomy)

1.5 Conflict potential + resolution-strategy candidates

Per Liam S228: investigate third-party packages + git-branching-style approaches before designing bespoke.

Conflict	Description
Concurrent-user	Two users / two sessions editing same content
External-vs-platform	Folder file changes while platform editing in flight
Re-ingest-collision	New binary upload conflicts with prior in-platform edit (largely dissolved under two-way pure write-back; only transactional-window remnants)
Dedup-collision	Dedup agent finds duplicates after recent edit creates near-duplicate
Citation-immutability	Cited content edited; citers must be notified or constrained

Resolution-strategy candidates:

Strategy	Tooling	Fit	Notes
CRDT (Conflict-free Replicated Data Types)	Yjs + Tiptap collab plugin (KH already uses Tiptap for Q&A ContentEditor per S198)	Strong for concurrent-user; weak for external-vs-platform	Yjs is mature; Notion / Figma / Linear all use CRDTs. Direct path: enable Tiptap collab plugin on Q&A editor → automatic concurrent-user conflict resolution.
Operational Transform (OT)	ProseMirror collab (Tiptap inherits)	REJECTED for v1	OT is older paradigm; CRDTs preferred for offline-first. Listed for completeness; not invoked by any UC.
Git-style branching	Bespoke OR git LFS for binaries OR shadow folder per branch	Strong for sweeping (UC3) + AI-suggest (UC8); medium for concurrent-user	Each in-flight edit = branch; merge with conflict-detect on commit. Maps cleanly to “review and approve” flow. Could use git as actual store (especially for markdown) — folder IS a git repo.
Cocoindex source-key + content-hash	`0.8.2-cocoindex-evaluation.md §9.1` trace	Strong for re-ingest-collision + external-vs-platform	Hash mismatch = conflict signal. Engine UPSERTs target keyed by logical-doc-id, not filename. Resolves the “different filename, same logical doc” case architecturally.
Mempalace temporal KG	Shape A `entity_relationships` extension (Q4.1 RESOLVED)	Strong for citation-immutability + UC6 Q&A versioning	`valid_from`/`valid_to` columns enable version-on-cite + “what was true at date X”.
Anthropic citations feature	API native	Strong for UC4 cited paragraph + UC6 Q&A revision	When AI generates content, citations are first-class artefacts that survive edits as immutable references.
`automerge` (CRDT)	Library	REJECTED for v1	Yjs preferred (already in ecosystem; tighter Tiptap integration). Listed for completeness.
`source_document_diffs` (KH built-not-wired)	Existing infrastructure	RETIRED — see §9.3	Built for old re-upload model; cocoindex’s ops-DB ledger supersedes. Listed for traceability.

1.6 Audit / compliance dimension

Requirement	Description
Lineage	Full version history, user attribution, timestamp
Rollback	User/admin can restore prior version
Temporal-query	”What did this say at date X?” supportable
Citation-stability	Once cited, content cannot silently mutate (lock-on-cite)
Change-report	Material changes surfaced as “Change Report” item

2. Use cases — initial draft (Liam to refine)

10 starting use cases populating the axes above. Each is one row — expand into full data-flow per UC in §4 once approved.

UC	Name	Complexity	Trigger	Target	Scope	Conflict	Audit	S228 Liam ratification
UC1	Typo fix	Atomic	User-direct (in-platform)	External-folder-file (or both-sidecar if binary)	Single-record	Concurrent-user	Lineage	Confirmed
UC2	Date / version-number bump	Atomic	User-direct	External-folder-file	Single-record (mostly)	Concurrent-user	Lineage	DE-SCOPED — sweeping date update is rare edge case (Liam: “are there examples where a date changes and a user needs to identify the 30+ documents…”); expiry-dates handled separately by extractDates flow (Q1.8) — NOT this UC. UC2 reduces to “edit a date in one doc” which is UC1-flavoured. Possibly merge UC2 into UC1.
UC3	Sweeping rename (e.g. brand/policy ref change)	Sweeping	User-direct (find-replace UI) AND AI-suggest (smart agent)	External-folder-file (every match)	Multi-doc	External-vs-platform	Lineage + Change-report	BOTH triggers ratified (Liam: “Both”). Find-replace UI handles known-string sweep; smart agent finds semantically-equivalent variations.
UC4	Paragraph rewrite (esp. cited content)	Bounded	User-direct	External-folder-file or both-sidecar	Single-record	Concurrent-user + Citation-immutability	Lineage + Citation-stability	Refined per Liam: sequence is (i) classify SOURCE of bid response — approved Q&A pair / draft Q&A pair / MCP-derived new response; (ii) classify CONFIDENCE — citable (use Anthropic citations feature) / inferred / generated. Edit-policy depends on classification. Confidence taxonomy intersects Q4.7 KG-provenance enum + Q4.14 graphify-confidence-label adopt.
UC5	Bid response → curated Q&A promotion	Compositional	User-promote	KH-DB-only (Q&A is derivative; no folder file)	Single-record (new Q&A pair)	None expected	Lineage + Citation-stability	Confirmed; provenance critical (carry source-bid-response-id + version).
UC6	Q&A pair revision	Bounded	User-direct or AI-suggest	KH-DB-only (or both-sidecar if Q&A backed by markdown)	Multi-doc (citers affected)	Citation-immutability	Lineage + Citation-stability + Change-report	Refined per Liam: Q&A pairs need provenance + lineage (when, why, formed-from-which-source-docs). When source docs change, surface affected Q&A pairs for review (depends on what changed). Policy: version-on-cite, NOT freeze-on-cite — every shipped bid response captures the Q&A version it used; Q&A pair can continue evolving. Maps to mempalace Shape A temporal columns (`valid_from`/`valid_to`) + Shape B verbatim-first chunks.
UC7	Binary upload replaces existing (revised .docx)	Structural	User-upload (to external folder)	External-folder-file + cocoindex re-ingest	Multi-doc (chunks of doc)	Transactional-window only (NOT re-ingest-collision, see notes)	Lineage + Change-report	MOSTLY COLLAPSES INTO UC10 per Liam insight: “if the underlying file is always updated (two-way edits), what type of in-platform edits could there have been which wouldn’t propagate to the stored document?” Answer: under two-way pure, almost none. Remaining UC7 concern = transactional-window concurrency (in-flight save vs upload) + content-NEVER-in-platform (= UC10).
UC8	AI-suggested dedup merge	Compositional	AI-suggest → User-approve	External-folder-file (golden record) + KH-DB cleanup	Multi-doc (collapses N → 1)	Dedup-collision	Lineage + Change-report	Confirmed; key question: where does dedup detection live? cocoindex post-ingest hash + chunk-similarity? mempalace KG entity-resolution? skill-seekers metadata? Spike S2 / S3 / S5 probe.
UC9	Scope-tag taxonomy update	Structural	User-direct (admin)	KH-DB-only (metadata)	Workspace-wide	None expected	Lineage	Confirmed; per Q1.7 RESOLVED + skill-seekers-eval §2.4 verdict, KH-native typed-column implementation needed (NOT skill-seekers `categories` keyword pattern). New `OPS-X-SCOPE-TAGS` work-package ~1-2 weeks.
UC10	External-folder edit detected	Atomic / Bounded / Structural	External-edit	KH-DB sync (re-ingest from folder)	Single-record (or multi if doc was chunked)	External-vs-platform (mostly absorbs former UC7 conflicts)	Lineage	Confirmed; polling frequency TBD by architecture proposal (Liam). cocoindex source-binding native.

3. S228 ratifications — opens closed by Liam

#	Original question	S228 answer
3.1	Missed UCs? Compliance bulk / onboarding bulk-import / bid-template population / branding enforcement	Coverage adequate to start. Onboarding bulk-import = file-system configuration under canonical-pipeline (NOT an “edit” UC; out of scope here). Compliance bulk + branding enforcement = UC3-flavoured. Bid-template population = UC5-flavoured. No new UCs added; UC1-UC10 stand.
3.2	UC2 sweeping date update — realistic?	Mostly NO. Expiry-dates handled separately by Q1.8 extractDates flow. Day-to-day business rarely needs to find-30-docs-with-this-date and sweep-update. UC2 de-scoped to atomic single-doc; merge into UC1 if no distinct flow. Need to enumerate “what types of dates could be ingested” before deciding if any sweep cases survive.
3.3	UC3 sweep trigger — UI / smart agent / both?	Both. Find-replace UI for known-string sweep; smart agent for semantically-equivalent variations.
3.4	UC4 cited-paragraph edit policy	Classification-driven. First identify SOURCE of bid response (approved Q&A / draft Q&A / MCP-derived). Then classify confidence (citable via Anthropic citations / inferred / generated). Edit-policy depends on classification. Cited content (citable bucket) uses Anthropic citations feature as immutable references.
3.5	UC6 Q&A citation policy — freeze-on-cite vs version-on-cite?	Version-on-cite. Q&A pairs evolve; bid responses capture Q&A version-used at ship time. Underlying doc changes → surface affected Q&A pairs for review. Provenance + lineage required (when/why formed; from which source docs).
3.6	UC7 binary re-upload conflict-resolution	MOSTLY DISSOLVED by two-way pure write-back. Liam: “what type of in-platform edits could there have been which wouldn’t propagate?” — under two-way pure, almost none. Remaining = transactional-window concurrency only. UC7 effectively collapses into UC10 for diff detection.
3.7	UC10 polling frequency	TBD — architecture proposal will determine. Webhook (SharePoint native) vs scheduled scan vs hybrid.
3.8	Permissions per UC	Reference doc-lifecycle work — `.planning/.archive/.specs/publication-{approval-gate, lifecycle-state-machine}-spec.md`, `.planning/.archive/.specs/p0-document-control-lifecycle-spec.md`, `.planning/.archive/.specs/content-lifecycle-spec.md`. Existing infrastructure: `publish_status` enum (draft / in_review / published / archived) + role matrix (editor / admin) + state-machine transitions. UC3 + UC8 + UC9 likely admin-only; UC1 + UC4 + UC5 + UC6 editor-and-up; UC7 + UC10 system-driven (no user role gate). Detail TBD per spec re-read in §4 data-flow phase.

3.9 Cross-UC consolidated decisions (S228 V3 finding)

V3 pattern-gap review surfaced 7 decisions duplicated across multiple UCs. Consolidated here so per-UC §x.6 questions reference back instead of re-litigating.

Cross-UC decision	UCs touched	Status	Note
Intent-taxonomy policy	UC4, UC5, UC6, UC8, UC9	`[DECISION-PENDING-§6.0]`	Default position: closed per-UC taxonomy + free-text “other” escape valve. Governance uniform across all UCs. Per-UC vocabularies differ (UC6 typo/factual/regulatory/etc.; UC8 confidence-tier; etc.) but enforcement style is one decision.
Anthropic citations re-anchor policy	UC4, UC6, UC7+10, UC8	`[DECISION-PENDING-§6.0]`	One decision: re-anchor on edit / mark-as-paraphrased / invalidate. Applies to all citation-touching UCs. Needs API behaviour study.
Citation immutability binding	UC4, UC5, UC6, UC8	RESOLVED by UC6 §3.5 — version-on-cite at ship time	Carry-forward to UC4 / UC5 / UC8 (do not re-ask).
Permission gating per UC	UC1, UC3, UC5, UC8, UC9 (plus UC4, UC6)	RESOLVED by §3.8 — publication-lifecycle role matrix	Per-UC §x.6 permission questions are duplicate of §3.8; do not re-litigate.
Downstream-impact UI (multi-record pre-commit summary)	UC4, UC6, UC8	`[DECISION-PENDING-§6.0]`	Same UX problem (N affected records — list / count / interactive preview). One decision; apply to all three.
Rollback-by-operation-ID	UC3, UC8, UC9	`[DECISION-PENDING-§6.0]`	Single-operation rollback affordance — same shape across all three. One decision.
AI-suggest fatigue mitigation	UC4, UC5, UC6, UC8	`[DECISION-PENDING-§6.0]`	False-positive prevention + threshold tuning + dismissal-behaviour. One mitigation strategy applies to all.

§6.0 (cross-cutting decisions) resolves these uniformly; §6.1-§6.9 (per-UC decisions) handle residuals only.

4. Data flows per use case

Sequential population per Liam S228 directive. Foundational UCs first (1 / 4 / 6 / 7+10), then mechanical UCs (3 / 5 / 8 / 9) following the template.

Framing reset (Liam S228): UC4 onwards leads with user/business outcome, not technical detail. We need to understand WHAT outcome users need, then HOW we achieve it technically. Schema-agnostic — avoid concrete column / table / endpoint references in the data flow itself; current schema (e.g. content_items 70 columns) may not survive the new architecture, and embedding it in flows would cause confusion. Tech mapping is referenced by §10 + resolved in §6.

UC1 (§4.1) was written technical-first as a structural template before this reframe. Stays as-is for reference; subsequent UCs (UC4+) follow outcome-first format.

Outcome-first format per UC:

User outcome — what the user needs to achieve
Required outputs — what the platform must produce / preserve / surface
Business sequence — ordered steps from user perspective (no tech specifics)
Success criteria — what “good” looks like from the user view
What could go wrong — failure modes from user view
Open questions for §6 — business-level decisions needed
Tooling implications — referenced from §10 matrix (NO commitment; informs §6)

4.1 UC1 — Typo fix (foundational template)

User opens content_item in platform; corrects single character / word; saves; change propagates to external folder file + cocoindex reconciles.

Axes: Atomic / User-direct (in-platform) / External-folder-file or both-sidecar / Single-record / Concurrent-user / Lineage.

Tooling per §10: Tiptap+Yjs PRIMARY for concurrent-user; cocoindex SUPPORTING (sees resulting file change); Claude API SUPPORTING for write-back-to-folder; mempalace SUPPORTING (Shape A KG event).

4.1.1 Pre-conditions

User: authenticated; role per publish_status matrix (editor permitted on draft / in_review; admin on published per .planning/.archive/.specs/publication-lifecycle-state-machine-spec.md — exact mapping needs confirmation, see §4.1.6).
Workspace: has connected external folder (Q2.1 RESOLVED — folder canonical); first-run onboarding complete (OQ2 RATIFIED).
Target content_item: exists; source_document_id populated; source_documents.original_path (NEW column per Q2.3 PENDING-ARCH) points at the folder file.
Infrastructure: Tiptap+Yjs collab plugin enabled on components/qa/qa-answer-display.tsx ContentEditor + any non-Q&A content editor (S228 NEW work, ~1 day per §9.8); cocoindex source-binding active on workspace folder.

4.1.2 Sequence

Open editor. User navigates to content_item; Tiptap ContentEditor mounts; Yjs awareness client joins shared editing session keyed by content_item.id.
Capture edit. User types fix. Yjs CRDT propagates change immediately to any other live sessions on the same content_item (e.g. another user reviewing).
Save trigger. User clicks Save (explicit) OR auto-save threshold fires (debounced, e.g. 2s after last edit).
[DECISION-PENDING-§6] — write-back path. Three candidates per §10:
- Candidate A — In-platform editor + filesystem write. KH API receives PATCH /api/items/[id]/content → updates DB row → writes file at source_documents.original_path → cocoindex source-binding observes file change on next scan; content-hash matches KH’s in-flight expectation → engine skips flow re-run (idempotency).
- Candidate B — Claude API text-editor-tool write-back. KH API receives PATCH → invokes Anthropic API with text-editor-tool (file path + diff or full new content) → tool writes file → cocoindex source-binding picks up → flow runs → UPSERTs DB row. KH API does NOT write DB directly; DB is materialised view.
- Candidate C — Managed Agent task. KH API queues task for “documentation agent” → agent reads file + edit intent + writes file with structured audit log → cocoindex picks up → flow updates DB.
Permission gate. Per app/api/items/[id]/route.ts:244-260 publish_status state-machine: role-target check; reject 403 if disallowed transition. UI surfaces 403 via toast (per AC (j) of publication-lifecycle-state-machine-spec.md).
DB write (Candidate A only; Candidates B+C let cocoindex flow handle this). content_items.content updated; auto-version trigger writes content_history row (change_type='edit', actor=user_id).
External folder write.
- Markdown source: write markdown to source_documents.original_path.
- Binary source: write sidecar .md per OQ1 ratification scope-clarification needed (see §4.1.6); binary stays RO.
Cocoindex reconciliation. On next scan/webhook (UC10 polling cadence per [DECISION-PENDING-architecture]): engine recomputes content-hash on the file. If equal to KH’s just-written hash → no-op. If mismatch (race or concurrent external edit) → engine runs flow → UPSERTs content_items → conflict-detect per §1.5 strategies.
Audit + notify. content_history row (DB); cocoindex ops-DB ledger row (engine); sendSourceDocumentUpdateNotifications for subscribed workspace members (REUSE per §9.4); future mempalace Shape A KG event (Q4.1).

4.1.3 State transitions

Subject	From → To
`content_items.content`	v_n → v_n+1
`content_items.content_text_hash` (GENERATED)	auto-recomputed
`content_history`	new row appended (change_type=`edit`, actor, ts, content_diff)
`source_documents.updated_at`	bumped (no `version` increment for typo per Q5.1 / S228 retire-decision)
External folder file mtime	bumped to write time
Cocoindex ops-DB	new row (input-content-hash, code-hash, output-content-hash, ts)
Mempalace KG (Q4.1 RESOLVED)	new edge `(content_item_id, edited, valid_from=ts, actor=user_id, confidence=1.0)`

4.1.4 Failure modes

Failure	Behaviour	Mitigation
Permission denied at step 5	403; UI surfaces via toast; no DB write; no file write	Per state-machine spec AC (j) — already specified
DB write succeeds, file write fails (Candidate A)	DB ahead of file → cocoindex sees old hash on next scan → re-runs flow → potentially overwrites DB	`[DECISION-PENDING-§6]` — atomic two-phase commit OR `content_items.dirty=true` + retry queue OR Candidate B/C (which makes file write primary)
File write succeeds, DB write fails (Candidate A)	File ahead of DB → cocoindex picks up new hash → flow runs → UPSERTs DB → consistent	Eventual consistency; user sees stale UI for one scan cycle
Concurrent in-platform edit (Yjs)	CRDT resolves at editor layer; on save, single merged content goes to file	Yjs guarantees no data loss; last-write-wins at file layer is post-CRDT-merge
Concurrent external-folder edit (user edits file outside platform during in-platform edit)	Tiptap doesn’t see external change; on save, file mtime newer than read time → conflict	Detect via content-hash mismatch at step 7; surface conflict UI per §1.5 (CRDT cannot reconcile cross-source — likely git-style merge prompt)
Sidecar write fails (binary source)	Binary content unchanged in folder; DB ahead	Warn user “sidecar required for binary edit; OK?” pre-write OR mark binary RO and reject in-platform edit
Cocoindex flow run fails post-write	Ops-DB ledger captures error; KH stays consistent (DB + file already aligned)	Engine retries on next scan; alert if persistent

4.1.5 Audit trail

Layer	Entry
DB	`content_history` row: `{change_type='edit', content_diff, actor_id, ts, parent_history_id}`
Engine	Cocoindex ops-DB: `{run_id, source_key, input_hash, code_hash, output_hash, status, ts}`
Notification	`sendSourceDocumentUpdateNotifications` (REUSE) — admin fallback per `0.1-ts-file-upload-addendum.md` L92-100
KG (post-Q4.1 ship)	mempalace temporal edge `(content_item, edited, valid_from, actor, confidence=1.0)`

4.1.6 Open questions for §6 architectural decision

#	Question	Why open
4.1.Q1	Candidate A vs B vs C for primary write-back path?	Foundational decision for this UC class. Candidate A simplest + cheapest; Candidate B leverages Claude API but expensive per atomic edit; Candidate C overkill for typos. Recommendation: Candidate A for atomic edits (UC1, UC2, atomic UC4); Candidate B/C reserved for sweeping (UC3) or AI-driven (UC8).
4.1.Q2	Transactional guarantee between DB write and file write?	Two-phase commit / dirty-flag retry / single-source-of-truth (file → cocoindex → DB only). Single-source-of-truth is cleanest but introduces save-to-display latency.
4.1.Q3	Cocoindex idempotency — does engine skip flow when content-hash unchanged from prior run?	Spike S2 confirms. If yes → Candidate A clean. If no → need explicit marker / flow-pause window.
4.1.Q4	Yjs persistence — store CRDT document in DB for crash recovery?	`y-supabase` adapter exists. Persistence enables offline-first + recovery. Adds DB schema burden.
4.1.Q5	Permission mapping — does `editor` role permit edit of `published` content_items, or restricted to `draft` / `in_review`?	Re-read `publication-lifecycle-state-machine-spec.md` §3.4 role matrix in §4 Q1 follow-up; resolves UC1 + UC2 + UC4 + UC6 permission gates uniformly.
4.1.Q6	Binary source — sidecar policy — automatic sidecar creation on first binary edit, or require explicit user opt-in?	Per OQ1 ratification, binary stays RO; sidecar pattern adopted. UX: silent vs prompted.

4.1.7 Mapping to existing infrastructure

Step	New / Reuse / Retire
1-3 (Tiptap+Yjs editor)	NEW — Yjs collab plugin enable (~1 day); Tiptap-mount on non-Q&A content editors (existing for Q&A per S198)
4 (write-back)	NEW — design + implement chosen Candidate
5 (permission gate)	REUSE — `publication-lifecycle-state-machine-spec.md` infrastructure shipped per S199-S202
6 (DB write + content_history)	REUSE — auto-version trigger exists (`auto_version_content_items`)
7 (folder write)	NEW — depends on Candidate
8 (cocoindex reconcile)	NEW — cocoindex source-binding (Q2.1 + spike S2)
9 (audit + notify)	REUSE notifications (§9.4); NEW KG event (post-Q4.1 ship)

4.2 UC4 — Paragraph rewrite (cited content)

User has identified a paragraph in a bid response (or other downstream artefact) that needs to change. The complication: the paragraph may be sourced from an approved Q&A pair, a draft Q&A, or generated content — and the source classification governs what “edit” should mean.

Axes: Bounded / User-direct (in-platform) / External-folder-file or KH-derivative / Single-record (with multi-doc citation impact) / Concurrent-user + Citation-immutability / Lineage + Citation-stability.

4.2.1 User outcome

User wants to change the wording of a paragraph and have the platform handle the consequences honestly:

The paragraph reflects the new wording wherever it surfaces.
The user is not silently let to invalidate prior citations or shipped artefacts.
If the source of the paragraph was an approved/draft Q&A, the user gets a clear choice: revise the Q&A (propagates) or create a one-off variation (doesn’t).
If the source was an MCP-search-derived response (one-off generation), the user gets a chance to capture the variation as a candidate Q&A pair so the next similar question doesn’t re-surface the old answer.
If the source was generated-without-citation, the edit is straightforward; provenance updates to reflect the new wording.

4.2.2 Required outputs

Output	Purpose
Updated paragraph text in the artefact (bid response, etc.)	The user’s primary intent
Source classification at edit time (approved Q&A / draft Q&A / MCP-derived / generated)	Governs edit policy + downstream actions
Edit-intent capture — “local fix only” vs “revise the source Q&A” vs “promote variation to corpus”	Tells the platform what to propagate
Provenance update — actor, ts, prior version, intent	Audit trail; future “why did this change?” answer
Downstream-impact surface — which other artefacts cite this source?	User sees what else is affected before committing
Citation reference update if Anthropic citations API in use	Citation must remain truthful — either re-anchored to the new text or marked as a paraphrase
New Q&A candidate (if user promotes variation)	Feeds UC5 promotion flow

4.2.3 Business sequence

User opens the artefact containing the paragraph (e.g. a bid response).
Platform surfaces the paragraph’s source classification (approved Q&A / draft Q&A / MCP-derived / generated) inline — visible at the paragraph level, not buried in metadata.
User indicates intent to edit the paragraph.
Platform shows edit-policy hint based on source classification:
- Approved Q&A: “This paragraph is sourced from an approved Q&A pair cited in N artefacts. Revise the Q&A (propagates), edit locally only, or capture variation as new Q&A?”
- Draft Q&A: “Sourced from a draft Q&A awaiting approval. Revise it now (still draft), edit locally only, or capture variation?”
- MCP-derived: “This was generated from a corpus search. Edit locally; consider capturing as a Q&A pair so future similar questions return your refined answer.”
- Generated (no citation): “This was generated without a citation source. Edit freely.”
User makes the edit (CRDT collab if multi-user).
User confirms intent (only if approved/draft Q&A; auto for MCP-derived/generated).
Platform applies the edit + propagation per intent + provenance entry + downstream-impact notification + citation reference update.

4.2.4 Success criteria (user view)

User sees the source classification before editing — never edits blindly.
User makes deliberate decision about propagation; not silently locked or silently propagated.
User sees downstream-impact list before committing to a propagating change (“revising this Q&A affects bids X, Y, Z”).
After edit, audit trail readably explains “why did this change?” with intent + actor + ts.
If user promotes a variation, new candidate Q&A appears in review queue (UC5 trigger).

4.2.5 What could go wrong (user view)

Failure	User-visible symptom	Mitigation needed
Silent propagation — user edits an approved Q&A locally, change propagates to other bids without their knowledge	User loses confidence in shipped citations across portfolio	Edit-intent gate at step 6 — explicit choice required before propagation
Silent isolation — user thinks they’re revising the Q&A, edit only applies locally	Future bids continue to surface the old wording	Same gate; clear UI showing which intent was selected
Downstream impact not surfaced — user revises an approved Q&A, doesn’t realise 5 shipped bids cite it	User can’t make informed decision; may be embarrassed by inconsistencies later	Pre-commit downstream-impact list (mempalace Shape A query: “what cited this Q&A, valid_to >= ?”)
Citation drifts — user edits a paragraph cited via Anthropic citations; citation now points at text that no longer exists verbatim	Citation becomes a lie; compliance risk	Citation update logic: re-anchor or mark as “paraphrased from”; specify in §6
MCP-derived paragraph never captured as Q&A — user perfects an answer; next bid asks same question; AI starts fresh from corpus, ignoring the perfected version	User repeats work; corpus doesn’t learn	Promote-to-Q&A prompt at step 4 for MCP-derived; nudge but don’t force
Locked-when-user-needed-to-edit — citation-stability policy too strict; user can’t fix a typo in cited content	User frustrated; edits in spreadsheet outside platform; corpus stays broken	Edit-policy must always allow at least the “edit locally only” path; never hard-lock

4.2.6 Open questions for §6

#	Question
4.2.Q1	Edit-policy per source classification — what set of options is offered for each (approved Q&A / draft Q&A / MCP-derived / generated)? Currently provisional in §4.2.3 step 4; needs ratification.
4.2.Q2	Downstream-impact surface UI — list / count / interactive preview? How are dozens of affected bids represented without overwhelming the user?
4.2.Q3	Intent-at-edit-time vs intent-at-save-time — does the user pick “revise Q&A” before editing, or after, or implicit?
4.2.Q4	Anthropic citations integration shape — re-anchor on edit, or mark as paraphrased, or invalidate? Needs API behaviour study.
4.2.Q5	Promote-to-Q&A capture — silent capture as candidate, or prompt user, or background AI suggestion?
4.2.Q6	”Edit locally only” semantics — does this fork the source in the artefact (bid response now has its own variant text) or just override-this-instance? Provenance differs.
4.2.Q7	Citation immutability mode — RESOLVED by UC6 §3.5 ratification: version-on-cite at ship time (cite-time-snapshot for shipped artefacts; pre-ship Q&A pair can continue to evolve). Carry-forward to UC4 edit-policy + UC5 promotion + UC8 dedup-merge. (Question retained for cross-UC traceability.)

4.2.7 Tooling implications (referenced from §10)

Anthropic citations PRIMARY for cited content (per S228 Liam direction).
Mempalace Shape A SUPPORTING — temporal KG queries for “what cited this Q&A, valid_to >= ?” downstream-impact lookups.
Tiptap + Yjs PRIMARY for the editor surface (concurrent-user CRDT).
Existing Q&A ContentEditor (S198 components/qa/qa-answer-display.tsx) — natural integration point for paragraph-level edits.
Confidence taxonomy (Q4.7 KG-provenance enum + Q4.14 graphify-confidence-label) — informs source classification at step 2.

4.3 UC6 — Q&A pair revision

User (or AI suggesting via source-doc change) is revising the Q&A pair itself — not a downstream artefact (UC4 covers that). Q&A pair revision must respect shipped-bid version-on-cite (S228 ratified) and surface in-flight citers honestly.

Axes: Bounded / User-direct or AI-suggest / KH-derivative (or both-sidecar if Q&A backed by markdown) / Multi-doc (citers affected) / Citation-immutability / Lineage + Citation-stability + Change-report.

4.3.1 User outcome

User wants to update a Q&A pair (typo, factual correction, regulatory change, source-doc-driven, dedup-merge consequence) and have the platform handle the consequences honestly:

Shipped artefacts citing this Q&A continue to reference the version they cited at ship time (version-on-cite ratified).
In-flight artefacts are surfaced before commit — user gets explicit choice about whether to update them or keep at the prior version.
The reason for the revision is captured durably (typo / factual / regulatory / source-doc-change / dedup / promotion).
If revision was triggered by an underlying source-doc change, the lineage links the source change to the Q&A revision so future readers can trace back.
Future use of this Q&A picks up the new version.

4.3.2 Required outputs

Output	Purpose
Updated Q&A pair (new current version)	The user’s primary intent
Prior version preserved with temporal bounds	Shipped citers continue to reference it (version-on-cite)
Provenance entry — actor, ts, intent, source-of-change	Audit trail; future “why did this change?” answer
Trigger linkage — if source-doc-change-driven, link to the source-change event	Lineage: revision ↔ underlying-doc-change
Citers report — shipped count + in-flight count + (optionally) list	User decision-support before commit
In-flight citer decision — auto-update / prompt-each / keep-at-prior — chosen per UC6 policy	Resolves the “in-flight bid suddenly has different text” risk
Notification to subscribers	Workspace members tracking this Q&A
KG event capturing temporal transition	Mempalace Shape A — `(qa_pair, revised, valid_from, valid_to_prior=ts, actor, intent)`

4.3.3 Business sequence

Trigger. Either (a) user-direct — user navigates to Q&A pair to revise; OR (b) AI-suggest — platform surfaces the Q&A for review because an underlying source doc changed in a way that may affect this Q&A; OR (c) system — UC5 promotion / UC8 dedup-merge produces a revision candidate.
Platform displays current state. Current version of question + answer; prior versions with timestamps; citers summary: N shipped, M in-flight; for AI-suggest trigger, the source-doc delta is shown alongside.
User reviews. If AI-suggest with source-doc delta: platform proposes a candidate revision; user accepts / modifies / rejects.
User edits the question and/or answer (CRDT collab if multi-user).
User states intent from a closed vocabulary (provisional, see §4.3.6 Q4): typo / factual-update / regulatory-change / source-doc-driven / dedup-merge / promotion-from-bid-variation / clarification.
Platform shows in-flight citer impact. “M in-flight bids cite this Q&A. Choose: (a) keep them at prior version, (b) update in-flight bids to new version, (c) prompt me per bid.”
User confirms. Platform applies revision: new version becomes current; prior version preserved with valid_to=ts; in-flight citers handled per choice; shipped citers untouched; lineage entry written; notifications dispatched.
Optional follow-up. If revision was source-doc-driven and the source doc has multiple Q&A pairs derived from it, platform offers to walk the user through related Q&A pairs (multi-revision atomicity — see §4.3.6 Q6).

4.3.4 Success criteria (user view)

Shipped bids stay stable. Period. User confidence in the bid library is preserved.
In-flight bids never silently change. User explicitly chose what happens to each.
Lineage answers “why did this change, when, who, in response to what?” — readable months later.
Source-doc change → Q&A review chain is traceable backwards (from Q&A revision → source-doc change event).
Future bids using the Q&A get the refined version.

4.3.5 What could go wrong (user view)

Failure	User-visible symptom	Mitigation needed
Silent in-flight propagation — user edits Q&A; 3 in-flight bids quietly get new text; user finds out when a colleague queries the changed bid	Trust collapse — colleagues can’t rely on bid-in-progress text	§4.3.3 step 6 — explicit in-flight choice required before commit
Source-doc change unsurfaced — underlying doc changed weeks ago; Q&A still reflects old reality; customer flags the inconsistency	Reputational risk; manual triage needed	§4.3.6 Q1 — define source-doc-change detection criteria; AI-suggest review prompt
Lineage gap — user can’t recall why they revised this Q&A 6 months ago	Audit fails; compliance review fails	§4.3.3 step 5 — closed-vocabulary intent capture, mandatory
Version-on-cite violated — somehow a shipped bid retroactively gets the new text	Shipped artefact is now a lie — embarrassing or illegal	Architectural enforcement (mempalace temporal bounds + citation locking); never relax this guarantee
In-flight choice fatigue — user faces 50 in-flight bid prompts and clicks “all-update” without thinking	Same risk as silent propagation	Sensible defaults (keep-at-prior is safer); batch summary before commit; never auto-default to “update”
Multi-Q&A revision desync — user revises Q&A A, doesn’t realise Q&A B (related; same source doc) needs the same revision; B becomes stale	Internal inconsistency between Q&A pairs	§4.3.3 step 8 — multi-revision walk surfacing related Q&A
AI-suggest false positive — platform surfaces Q&A for review when source-doc change was cosmetic; user gets fatigued	User dismisses the next AI-suggest, missing a real one	§4.3.6 Q1 — change-detection signal must be precise; tunable threshold

4.3.6 Open questions for §6

#	Question
4.3.Q1	Source-doc change detection criteria — any-change / material-change / citation-relevant change? Needs definition + threshold. Likely: any structural change to a paragraph that’s the source for a cited Q&A.
4.3.Q2	In-flight citer policy default — keep-at-prior (safer) vs prompt-each? Probably keep-at-prior + opt-in-prompt; not auto-update.
4.3.Q3	Dedup-merge revision (UC8 trigger) — does it use this UC6 flow, or a separate flow with system-as-actor + post-merge review?
4.3.Q4	Intent vocabulary — closed taxonomy as listed in §4.3.3 step 5, or free-text-required, or free-text-optional? Closed taxonomy aids analytics; free text catches edge cases.
4.3.Q5	Q&A lifecycle states — does revision interact with `publish_status` (draft / in_review / published / archived)? E.g. revising a published Q&A — does it move to in_review automatically?
4.3.Q6	Multi-Q&A revision atomicity — can the user revise 5 related Q&A pairs as one transactional change with shared provenance? Useful for regulatory updates affecting many Q&A pairs.
4.3.Q7	Q&A backed by markdown sidecar — if Q&A pair has a markdown file in the folder (open per §2 UC6 row), does revision write back to the file? Likely yes for two-way pure consistency, but Q&A pairs are curated derivatives — different shape than UC1 source-doc edits.
4.3.Q8	AI-suggest revision composition — when AI proposes a revision based on a source-doc change, is the AI’s proposal itself a “draft” requiring user approval, or does it write a draft Q&A version automatically?

4.3.7 Tooling implications (referenced from §10)

Mempalace Shape A PRIMARY — temporal columns + KG queries are the substrate for version-on-cite + citer queries.
Anthropic citations PRIMARY — shipped citation immutability enforced at the citation API level (cite captures the Q&A version-id; immutable).
Tiptap + Yjs SUPPORTING — Q&A editor surface (existing S198 ContentEditor).
Cocoindex NO for the Q&A revision itself (KH-derivative); SUPPORTING for source-doc-change detection (UC10 territory) which feeds AI-suggest trigger.
Mempalace miner SUPPORTING — if AI-suggest proposes a revision based on the source-doc change, mempalace miner’s Q+A-pair extraction pattern is one candidate substrate (per Q4.3 PENDING-ARCH).

4.4 UC7+UC10 collapsed — External folder change detected (incl. binary re-upload)

System-driven, not user-driven. Trigger: a file in the connected folder changed (added / edited / deleted / renamed / binary-replaced) — externally OR via in-platform write-back. Platform must detect, classify, reconcile, and surface consequences. Per S228 Liam insight: under two-way pure write-back, the only “unique” cases left for UC7 (binary re-upload) are external-edit-while-platform-editing transactional collisions — otherwise UC7 = UC10 for binary shape.

Axes: Atomic / Bounded / Structural — depending on what changed in the file / External-edit (or User-upload-to-folder) / Materialised representation update / Single or multi-record / External-vs-platform / Lineage.

4.4.1 User outcome

User has changed something in the connected folder (added a doc, edited a markdown file in their preferred editor, replaced a .docx with a revised version, renamed something, deleted something). Or someone else has — a colleague, an automated process, a SharePoint-side workflow. The user expects:

The platform notices promptly. “Promptly” varies by tolerance — for a brand-new doc that needs to be ingested before the next bid, “minutes” is fine; for a typo fix the user wants visible immediately, “seconds” is preferred.
The platform handles each change kind appropriately: new docs ingested + classified; edited docs get their materialised representation updated; renamed docs preserve identity; deleted docs archived (not silently disappeared); binary replacements extract + update sidecars.
Shipped citations stay stable. If an external edit changes content that’s cited in a shipped bid, the bid’s cited version remains intact; the new version becomes current going forward (version-on-cite from UC6).
Q&A pairs derived from a doc that changed are surfaced for review (feeds UC6 AI-suggest trigger).
If the platform was editing the same record at the same time, the conflict is surfaced — never silently resolved one way.
The audit trail captures the external change as the trigger for any downstream effects.

4.4.2 Required outputs

Output	Purpose
Detected change classification — add / edit / delete / rename / binary-replace	Drives downstream handler choice
Updated materialised representation per change kind	Keeps platform queryable + accurate
Identity preservation across rename	Same logical-doc identity even when path changes (per cocoindex Appendix §9.1 trace)
Prior-version snapshot	Audit + version-on-cite for shipped citations
Q&A review queue items	If derived Q&A pairs affected by the change (feeds UC6 AI-suggest)
Conflict surface if platform was editing the same record	User-visible reconciliation prompt
Source-doc-change event in lineage	Captures “external triggered this” for downstream traceability
Notifications to subscribers	Workspace members tracking the doc / its derivatives
Citation re-anchoring if cited content text changed	Citations remain truthful (Anthropic citations integration)

4.4.3 Business sequence

Detection. Folder source binding scans (cadence TBD per §4.4.6 Q1) OR receives push (e.g. SharePoint webhook). Compare current folder state vs last-known state.
Change classification per file. Each diff is classified:
- Add — new file at a path never seen.
- Edit — same path, content-hash changed.
- Delete — path no longer exists.
- Rename — content-hash equal to a recently-seen path that no longer exists (delete+add pair with hash-equality).
- Binary-replace — same path, file is binary, content-hash changed (same shape as edit but extraction needed).
Conflict check per change. Was the platform mid-edit on a record sourced from this file? If yes, route to conflict surface (step 7); else proceed.
Per-kind handler dispatch.
- Add → ingest pipeline → classify → surface in workspace → notify if relevant.
- Edit / Binary-replace → re-extract → update materialised representation → preserve prior snapshot → check for derived Q&A pairs → queue Q&A review (UC6) if affected.
- Delete → mark canonical record archived (not deleted) → check for citing artefacts (shipped bids, in-flight bids, derived Q&A pairs) → surface impact list to admin → archive Q&A pairs sourced from this doc with stale-source flag.
- Rename → update path reference on the record while preserving its identity → no re-extraction needed (content unchanged).
Citation re-anchor for any change to cited content. Per Anthropic citations integration shape (open per UC4 Q4): re-anchor or mark-as-paraphrased.
Lineage write. Event recorded — what changed, when, hash-before, hash-after, classification, downstream effects.
Conflict surface (if step 3 flagged). Show user: “external file changed [diff]; you have an in-flight platform edit [diff]. Resolve: keep platform / keep external / merge / cancel both for review.” User decision propagates.
Notify subscribers + admin if material change.

4.4.4 Success criteria (user view)

Platform reflects external folder edits within tolerance window (per polling/webhook cadence chosen).
Renames preserve identity — user doesn’t lose the link from “this Q&A came from this doc”.
Deletes don’t vaporise audit trail — archived records remain queryable for “what did this say last quarter?”.
Conflicts surface to a human — never silently resolved.
Q&A pairs needing review actually surface promptly when their source docs change.
AI consumers (Claude via MCP) get fresh content within tolerance window — never serve stale data because the platform missed an external change.

4.4.5 What could go wrong (user view)

Failure	User-visible symptom	Mitigation needed
Polling too slow	User edits folder file at 10:00; platform serves stale data via MCP at 10:30; AI gives outdated answer	§4.4.6 Q1 polling cadence decision; SharePoint-style webhooks where available
Webhook silently fails	Push notification lost; platform never sees the change; stale forever	Belt-and-braces: webhook + scheduled scan as fallback; alert on scheduled-scan-finds-drift
Rename misdetected as delete+add	Q&A pairs / citations lose their source link → orphaned	Content-hash-equality check in step 2; tunable hash-window for “recently-seen”
Identity collision on rename	Two unrelated files happen to share content hash; rename detection wrongly merges them	Combine content-hash with size + mtime windows; rare but real
Delete cascade panic	User accidentally deletes a folder; platform mass-archives everything; recovery painful	Soft-delete-with-grace-period + admin confirmation for bulk delete; restore window
External-edit-during-platform-edit silent loss	User edits in platform; colleague edits same file in folder; one silently wins	Step 3 conflict detection; explicit user resolution per step 7
Q&A review queue overwhelm	One source doc with 30 derived Q&A pairs gets a punctuation fix; 30 review prompts surface	Material-change threshold per OQ4.3.Q1 (UC6); cosmetic changes don’t trigger review
Citation re-anchor failure	External edit removes the exact text a citation pointed at; citation now lies	Surface to user at step 5; never silently invalidate; mark-as-paraphrased fallback
Cocoindex ops-DB out-of-sync with reality	Engine thinks state X is current when actually Y; subsequent decisions wrong	Periodic full-resync; alert on hash mismatches; spike S2 + S1 verifies
Binary-replace extraction degrades quality	New .docx version extracts to worse markdown than the prior; user sees regression	Pre-cutover comparison preview; user can reject the new extraction (UC8 territory)

4.4.6 Open questions for §6

#	Question
4.4.Q1	Polling cadence + webhook strategy per connector — SharePoint native push; LocalFS via fs-watch (real-time); Notion via push; Google Drive via push API. What’s the minimum-viable cadence per connector at v1?
4.4.Q2	Rename detection precision — content-hash + path-disappearance heuristic; what’s the time window? What about identical-content unrelated files?
4.4.Q3	Delete handling policy — auto-archive (current proposal) vs prompt-admin vs require-explicit-confirm? Q&A pair orphan policy: archive-with-source / mark-stale / require-review?
4.4.Q4	External-edit-during-platform-edit reconciliation — git-style merge UI / pick-one / cancel-both-for-review? Liam S228 mentioned git-branching investigate (§1.5).
4.4.Q5	Q&A review queue UX — per-pair prompt / bulk-summary-with-batch-action / dashboard tile? What’s the threshold for “material change” that triggers review?
4.4.Q6	Audit retention for deleted files — indefinite / 7 years (compliance baseline) / per-tenant policy?
4.4.Q7	Binary-replace sidecar update — automatic regeneration or warn user about extraction-quality variation? Pre-cutover preview UI?
4.4.Q8	Cross-record dedup at ingest (UC8 overlap) — when “add” classification applies, does the platform check for near-duplicates against existing records before classifying as new?
4.4.Q9	Bulk-change scenarios — user does a bulk-rename via SharePoint; platform receives 50 webhook notifications. Throttling / batching strategy?

4.4.7 Tooling implications (referenced from §10)

Cocoindex PRIMARY — source binding is the engine for this entire UC family. Appendix §9.1 trace is the canonical data-flow reference.
Mempalace Shape A SUPPORTING — lineage events recorded as KG transitions; temporal queries answer “what changed in the source for this Q&A pair?”.
Anthropic citations SUPPORTING — re-anchoring on cited content change.
Tiptap + Yjs NO — UC4.4 is system-driven, no user-edit surface (except for conflict resolution UI at step 7 which uses git-branching-style or merge UI, not Tiptap).
Skill-seekers metadata + RAGChunker SUPPORTING for “add” classification — chunking + categorisation runs as part of the cocoindex flow’s @coco.fn for new files.
Mempalace miner SUPPORTING — for “add” with Q&A-shape source files (mempalace mine extracts Q&A pairs natively per Q4.3 PENDING-ARCH).

Foundational UCs (1, 4, 6, 7+10) populated. Pattern set. Mechanical UCs (3, 5, 8, 9) follow per template; populating sequentially per Liam direction or batched to sub-agent following ratified patterns.

4.5 UC3 — Sweeping rename

User (or AI surfacing variations) wants to apply one logical change everywhere it appears across many records — a brand rename (“Phew Group” → “Phew Limited”), a policy reference update, a job title that’s changed across dozens of docs, a regulatory clause version bump. Per S228 Liam ratification, both trigger variants are in scope: a find-replace UI for known-string sweeps and a smart agent for semantically-equivalent variations (“the company” / “our organisation” / “we” → “Phew Limited” branding sweep).

Axes: Sweeping / User-direct (find-replace UI) AND AI-suggest (smart agent) / External-folder-file (every match) / Multi-doc / External-vs-platform / Lineage + Change-report.

4.5.1 User outcome

User wants to issue one logical change once and have the platform faithfully apply it across every relevant record — without losing control, without silently mutating cited content, and without grinding their day to a halt while it works:

The user states the change once (a literal string for find-replace, or a brief and target for the smart agent) and gets a confident preview of where it will land before any record is written.
The user can see the full list of affected records and either trim it (exclude specific matches) or proceed wholesale.
The user is shown which matches are inside cited content and gets to decide whether those are revised, left alone, or marked as variations needing review.
The user can cancel mid-sweep without leaving the corpus in a half-applied state.
After the sweep, the user gets a single Change Report summarising what was changed, where, by whom, and why — so a colleague reviewing the corpus next week understands the source of the shift.
For semantically-equivalent variations, the user gets a per-match confidence score and can approve / reject / edit individual matches before commit, never being asked to trust a blanket auto-apply.

4.5.2 Required outputs

Output	Purpose
Affected-record list with per-record match-count, before commit	User decision-support; lets user trim the sweep scope
Per-match preview — original text + proposed replacement + surrounding context	User can verify each match isn’t a false positive (especially for smart-agent variant)
Cited-content overlap flag per match	Surface citation risk so user makes informed call per match
Per-match confidence score (smart-agent variant only)	Distinguishes “company → Phew Limited” (high confidence with context) from incidental references that should NOT be swept
Updated text in every approved record	The user’s primary intent
Per-record provenance entry linking each change to the sweep operation	Audit; one logical operation, N records — must be traceable back to a single sweep ID
Single Change Report for the whole sweep	”Why did all these records change?” — readable months later
Notification to subscribers of affected records	Workspace members tracking specific records see the sweep landed
Rollback affordance — sweep ID can be reversed (or per-record un-applied)	Per §1.5 Audit/Rollback requirement; sweeps are high-risk operations
Citation re-anchor / paraphrase mark for any cited content swept	Citations remain truthful

4.5.3 Business sequence

Trigger. User opens a sweep surface and chooses variant:
- Find-replace variant: user enters a literal source string, the replacement string, and optional scope (workspace / specific folder subtree / specific record type).
- Smart-agent variant: user describes the change in natural language (e.g. “everywhere we refer to ourselves as a company or organisation, standardise to ‘Phew Limited’”) and optionally provides a reference document showing the target style.
Platform proposes the affected-record list with per-record match counts. For the smart-agent variant, the platform also returns per-match candidates with surrounding context and a confidence score.
User trims the scope — deselects records that shouldn’t be touched (e.g. archived corpus that should stay verbatim, or a quotation where the source string is intentional).
Platform surfaces cited-content overlap. Any match inside text cited by a shipped artefact is highlighted; the user explicitly decides for each whether to revise the cited record, leave it untouched, or mark as a variation needing review.
User reviews matches. For the smart-agent variant, the user can approve, reject, or edit individual matches; nothing auto-applies. For the find-replace variant, the user sees a representative sample of matches in context (full review optional for very large sweeps).
User states intent from a closed vocabulary (provisional, see §4.5.6 Q5): brand-rename / policy-reference / regulatory-update / clarity-pass / dedup-driven / other-with-note.
User confirms the sweep. Platform begins applying changes record-by-record. Progress is visible; the user can pause / cancel.
Platform commits each record under a shared sweep ID — every affected record’s provenance entry references the sweep ID so the operation can be queried as one logical event.
Platform generates the Change Report at completion — summary of records affected, intent, actor, ts, plus per-record links. Notifications dispatched.
Sweep ID retained for rollback support. If the user (or admin) later determines the sweep was wrong, the sweep ID can be reversed, restoring prior versions across all touched records.

4.5.4 Success criteria (user view)

User issues one logical change once and sees the result land everywhere it should — no silent misses, no surprise hits.
User retains veto over every match in the smart-agent variant; nothing is applied without explicit approval.
Cited content is never silently mutated; user is forced to make a per-match decision for citation overlaps.
The sweep can be paused or cancelled mid-flight without leaving the corpus inconsistent.
The Change Report tells a clear story months later about what changed, where, why, by whom.
A wrongly-applied sweep can be rolled back as one operation, restoring every affected record at once.

4.5.5 What could go wrong (user view)

Failure	User-visible symptom	Mitigation needed
False positive in find-replace — literal string matches an intentional quote or a similar-but-distinct term (“Phew Limited” vs “Phew Limited Partnership”)	Sweep silently corrupts records the user didn’t intend to change	§4.5.3 step 5 — representative-sample review for large sweeps; full preview for small ones; never zero-preview commit
False positive in smart-agent variant — the agent rewrites a paragraph that wasn’t actually about the target referent	User loses trust in the smart-agent feature; reverts to manual edits	Per-match confidence scores + mandatory per-match approval; configurable threshold below which matches don’t even surface
Citation silently invalidated — sweep hits cited text in a shipped artefact; citation now points at text that no longer exists verbatim	Citation becomes a lie; compliance / reputational risk	§4.5.3 step 4 — explicit per-match decision for cited content; default to “leave untouched” not “revise”
External-folder edit during sweep — colleague edits one of the affected records mid-sweep; their change is overwritten or the sweep fails partway	Lost work; inconsistent corpus	Step 7 — per-record concurrency check; if external edit detected, skip that record and report it in the Change Report for follow-up
Partial sweep, no recovery path — sweep crashes at record 47 of 200; the corpus is half-changed and there’s no clear way to finish or undo	Manual triage; user cannot determine what state the corpus is in	Step 7 transactionality decision (per §4.5.6 Q4) — either all-or-nothing OR resumable + visibly-progressing OR explicit “in-progress” state on each record
Sweep cannot be rolled back — user realises an hour later the sweep was wrong; no single-operation undo	User edits 200 records by hand to reverse the sweep	Step 10 — sweep ID + per-record prior-version linkage; one rollback operation reverses the whole sweep
Cross-workspace leakage — admin runs a sweep meant for one workspace; it accidentally touches another	Cross-tenant data corruption	§4.5.6 Q1 — explicit scope confirmation; default scope is current workspace; cross-workspace requires elevated permission
Smart-agent variant overwhelms the user — agent proposes 500 candidate matches across 50 records; review is impractical	User clicks “approve all”; falls into the silent-propagation trap	Match-grouping (by record / by phrase / by confidence band); batch-approve within group; “low confidence” hidden by default
Sweep blocks live editing — user cannot edit any record while a sweep is running	Productivity halt for whole team	Concurrency model: sweep takes per-record locks just-in-time, releases immediately; other records remain editable; per §4.5.6 Q3

4.5.6 Open questions for §6

#	Question
4.5.Q1	Sweep scope — workspace-only (default) / cross-workspace / platform-global? Cross-workspace likely requires admin-of-admins permission; platform-global probably never v1.
4.5.Q2	Preview-before-commit UX — full preview required for every sweep, or representative-sample acceptable for large sweeps? Threshold for “large”?
4.5.Q3	Per-record concurrency model — per-record lock during sweep, or optimistic with conflict-skip-and-report? How does it interact with Yjs collab on a record being swept?
4.5.Q4	Sweep transactionality — all-or-nothing (rollback whole sweep on any single failure) vs partial-progress-with-resume (sweep retains per-record state, can resume) vs best-effort (apply where possible, report failures)?
4.5.Q5	Intent vocabulary — closed taxonomy (brand-rename / policy-reference / regulatory-update / clarity / dedup / other) or free-text? Closed aids analytics + rollback grouping.
4.5.Q6	Smart-agent confidence threshold — what threshold below which a match is hidden by default? Tunable per workspace?
4.5.Q7	Admin gating — find-replace variant available to editor role, or admin-only? Smart-agent variant similar restrictions? Per §3.8, UC3 is likely admin-only — confirm.
4.5.Q8	Cited-content default — for matches inside cited text, is the default “revise” or “leave untouched”? Probably “leave untouched + flag for review” given UC6 version-on-cite stance.
4.5.Q9	Sweep on archived records — included in default scope, or excluded? Likely excluded; archived is supposed to be verbatim historical.
4.5.Q10	Reuse of UC4 edit-policy classification — sweep that hits Q&A-sourced content — does it follow UC4’s per-paragraph classification flow (revise Q&A vs edit locally) or does the sweep ID supersede that flow? Tension between sweep-as-bulk-operation and per-paragraph classification semantics.

4.5.7 Tooling implications (referenced from §10)

Claude API text-editor-tool PRIMARY for the smart-agent variant (per §10 row UC3) — natural fit for “find semantically-equivalent variations and propose the right replacement with context”.
Cocoindex SUPPORTING — re-runs the canonical flow on every changed file, ensuring the materialised representation reflects the swept text without bespoke re-ingest logic per record.
Tiptap + Yjs NO for the sweep operation itself (sweeps are system-driven write, not interactive editing) but the per-record concurrency model interacts with Yjs collab sessions on records being swept (per §4.5.6 Q3).
Anthropic citations SUPPORTING — re-anchoring or marking-as-paraphrased for matches inside cited content (per §4.5.6 Q8).
Mempalace Shape A SUPPORTING — sweep ID surfaces as a KG event linked to every per-record edit, enabling “show me all changes from sweep S” temporal queries + downstream-impact analysis.
Find-replace variant is the lower-risk path; smart-agent variant is the higher-value path. Both can be developed independently; sequencing decision belongs in §6.

4.6 UC5 — Bid response → Q&A promotion

User has crafted a strong response to a bid question — either by editing an MCP-derived draft (the UC4 step 7 “promote variation” path) or by recognising during review that a one-off answer should join the curated corpus so the next similar question doesn’t start from scratch. UC5 is the inverse of UC4’s “MCP-derived → capture” path: instead of generating one-off, the user is enriching the canonical Q&A library so the next answer is grounded.

Axes: Compositional / User-promote / KH-derivative (Q&A is curated; no folder write-back unless Q&A backed by markdown sidecar) / Single-record (new Q&A pair) / None expected / Lineage + Citation-stability.

4.6.1 User outcome

User wants to convert a bid response (or a refined variation of one) into a curated Q&A pair so the corpus learns and future bids benefit, while keeping the bid itself intact:

The user’s primary intent is to create a new Q&A pair, not to alter the shipped or in-flight bid.
The promoted Q&A clearly inherits its lineage from the bid response — actor, ts, source bid, source question — so a reviewer can later trace “where did this Q&A come from?”.
The new Q&A is treated as a draft (or candidate) by default, not auto-published; a reviewer / approver decides whether it joins the production corpus.
If a very similar Q&A already exists, the user is alerted at promotion time so they can choose to extend / merge / supersede instead of creating a near-duplicate.
The bid response that triggered the promotion remains unchanged in the bid — promotion does NOT mutate the artefact.
After approval, future bid drafts that surface the same question (or semantically-similar) prefer the new Q&A.

4.6.2 Required outputs

Output	Purpose
New Q&A pair (draft state) — question text, answer text, scope tags, applicable contexts	Primary artefact created
Lineage entry linking to source — actor, ts, source bid ID, source bid question, source variation type (approved-Q&A revision / draft-Q&A revision / MCP-derived / manually-authored)	Audit; future “why does this Q&A exist?” answer
Provenance metadata — confidence classification at capture time (cf. UC4 source classification taxonomy)	Inherits source’s confidence quality; informs reviewer
Similarity report at promotion time — any existing Q&A pairs that look similar enough to warrant merge consideration	Prevents near-duplicate proliferation in the corpus
Review queue item for an approver	Approval gate before joining production corpus
Untouched bid response in the originating artefact	Promotion is non-destructive to the bid
Notification to subscribers (curators, workspace admins)	Visibility into curation pipeline
KG event capturing promotion	Mempalace Shape A entry — `(bid_response_X, promoted_to, qa_pair_Y, valid_from, actor, intent)`

4.6.3 Business sequence

Trigger. User initiates promotion from one of three entry points:
- From UC4 step 6 — user picked “capture variation as new Q&A” during a paragraph edit on a bid response.
- From a dedicated review UI — user browsing bid responses chooses “promote this answer to Q&A”.
- From AI suggestion — system surfaces a candidate-for-promotion (high-quality bid response that doesn’t have a matching Q&A pair in the corpus); user accepts the suggestion.
Platform pre-fills the new Q&A draft — question text inferred from the bid question; answer text inherited from the bid response (the user can edit either before commit).
Platform runs similarity check against existing Q&A pairs — uses the existing corpus to find candidates that overlap on question intent, answer content, or both. Results surface with a per-candidate similarity score.
User chooses path based on similarity results:
- No close match → proceed with new Q&A draft.
- Close match exists → choose: supersede the existing pair (UC6 revision flow takes over), merge the new content into the existing pair (UC6 revision flow with merge intent), or proceed regardless (create a new pair anyway — user accepts curation risk).
User reviews and edits the draft — refines question wording, trims the answer to the canonical form, adds scope tags per workspace vocabulary (UC9 territory), specifies applicable contexts.
User states promotion intent from a closed vocabulary (provisional, see §4.6.6 Q3): novel-question / refined-existing / regulatory-driven / client-specific / dedup-from-variations / other-with-note.
User submits. The draft Q&A is created with full lineage. The originating bid response remains untouched.
Approval workflow. Depending on workspace policy (per §4.6.6 Q2), the Q&A either: (a) goes directly into a curator’s review queue requiring explicit approval; (b) auto-publishes if the actor has approval rights; or (c) sits in a “candidate” state until enough confidence signals accumulate.
On approval, the Q&A becomes available for future bid drafts to cite. Lineage is preserved indefinitely.

4.6.4 Success criteria (user view)

User’s bid response remains unchanged after promotion — the user trusts that promotion is non-destructive.
The new Q&A carries clear lineage so any future reviewer can answer “where did this come from?”.
Near-duplicate Q&A pairs are surfaced before promotion, not after — curation discipline is enforced at entry, not retroactively cleaned up.
The user’s contribution surfaces in the next relevant bid draft (after approval) — the corpus visibly learned.
The approval workflow doesn’t bottleneck — promotion isn’t a black hole where good content goes to die.

4.6.5 What could go wrong (user view)

Failure	User-visible symptom	Mitigation needed
Silent bid mutation — user promotes a response; the bid response itself is altered or partially copied out	User cannot trust promotion; reverts to manual copy-paste-to-spreadsheet	Architectural enforcement — promotion creates a new artefact; never edits the source bid
Near-duplicate Q&A explosion — every promoted variation becomes a new Q&A pair; corpus accumulates 5 versions of the same answer	Corpus quality degrades; AI consumers get inconsistent answers	§4.6.3 step 3 — similarity check pre-commit; merge / supersede paths preferred over duplicate-creation
Promotion approval black hole — Q&A drafts pile up in review queue; nothing gets approved; promoted content never reaches future bids	Users stop promoting; corpus stagnates	§4.6.6 Q2 — workspace-level approval policy + SLA; reminder workflow; admin override
Lineage gap — promoted Q&A has no link back to the bid that triggered it	Reviewer cannot answer “is this from a real client bid or invented?”	§4.6.3 step 7 — mandatory lineage; can’t bypass
Bid version drift after promotion — bid is later edited; promoted Q&A pair still claims it was sourced from a version of the bid that no longer exists	Lineage is misleading	Pin lineage to the version of the bid at promotion time, not a moving pointer; explicit version-on-cite from UC6 already implies this
Promoted Q&A wrongly scoped — user promotes a client-specific answer; AI later surfaces it for a different client’s bid	Cross-client information leakage	§4.6.6 Q6 — scope tag (UC9) is mandatory at promotion; default is “this workspace only”
AI-suggested promotion fatigue — system surfaces dozens of promotion candidates daily; user dismisses them all	Real high-value promotions get missed	AI-suggest threshold tunable; throttle suggestions per user per day; suggestion quality metrics
Promoted Q&A immediately surfaces in another in-flight bid — user promotes, approval auto-fires, next draft picks it up before user expects	User feels they’ve lost control of when their content goes live	§4.6.6 Q2 — explicit approval state; user can mark promotion as “draft-only” pending review
Quality gates inconsistent — one curator approves loose, another strict; corpus quality varies by curator	Inconsistent corpus	§4.6.6 Q5 — pre-promotion quality checklist or rubric; reviewer guidance

4.6.6 Open questions for §6

#	Question
4.6.Q1	Auto-promote vs always-prompt — should AI ever auto-promote a high-confidence variation, or is user-initiated only? Likely user-initiated only at v1; AI suggests, never commits.
4.6.Q2	Approval workflow — does the promoted Q&A start as draft requiring explicit approval, or auto-publish if the actor has rights, or candidate-pool with confidence accumulation? Per Q3.8 PENDING-ARCH document-lifecycle integration.
4.6.Q3	Intent vocabulary — closed taxonomy at step 6 or free-text? Closed aids analytics, but bid-promotion intents are more varied than UC6 revisions.
4.6.Q4	Review queue ownership — workspace-level curator role, admin, original author re-reviews, or distributed?
4.6.Q5	Pre-promotion quality gates — checklist (scope tagged? answer self-contained? question phrasing canonical?) or rubric or none? Risk of gate-as-blocker vs gate-as-quality-floor.
4.6.Q6	Scope tag handling at promotion — inherit from source bid (likely too broad), require user to pick (most explicit), or auto-classify (lower friction, higher risk)? Interacts with UC9 + Q3.12 (per-pair vs per-source-doc).
4.6.Q7	Q&A backed by markdown sidecar at promotion time — does promotion immediately write a sidecar `.md` to the folder, or only once Q&A is approved + published? Likely on-publish; promotion → draft is KH-DB-only.
4.6.Q8	Integration with KBIntegrationReview component (per Q3.8 PENDING-ARCH) — is the promotion review queue the same surface as the broader bid integration review, or separate?
4.6.Q9	Duplicate-detection threshold at promotion time — what similarity score triggers the “this looks like an existing pair” surface? Tunable per workspace?
4.6.Q10	Promotion source classification carry-through — when the promoted bid response was originally MCP-derived vs approved-Q&A-variation vs manually-authored, does the new Q&A draft inherit a confidence label from that taxonomy (UC4 step 2)?

4.6.7 Tooling implications (referenced from §10)

Mempalace Shape A PRIMARY — provenance + lineage are exactly what Shape A’s temporal columns are designed for; “promoted from bid X version v, by user U, at ts” maps cleanly onto (subject, predicate, object, valid_from, source_content_item_id, actor, confidence).
Anthropic citations SUPPORTING — the source bid response may itself carry citations; the promoted Q&A inherits the citation lineage (citation transitivity is a useful property).
Existing Q&A ContentEditor (S198 components/qa/qa-answer-display.tsx) — natural integration point for §4.6.3 step 5 editing.
Tiptap + Yjs SUPPORTING — Q&A draft editing in a collab-aware editor surface; useful if multiple curators co-review the draft.
Cocoindex NO for the promotion itself (KH-DB derivative); SUPPORTING only if/when the approved Q&A pair is materialised to a markdown sidecar in the folder, at which point cocoindex source-binding observes the new file.
Mempalace miner SUPPORTING — pattern-of-extraction for “find Q&A-shaped content in this artefact” is mempalace miner’s native shape; could inform AI-suggest trigger logic (per Q4.3 PENDING-ARCH).
Skill-seekers metadata NO — different shape (categorisation, not promotion lineage).

4.7 UC8 — AI-suggested dedup merge

The corpus accumulates near-duplicates over time: a DRAFT of a doc alongside its final version, the same Q&A worded slightly differently in two places, two records describing the same client policy with minor variations. Exact-content-hash dedup at ingest catches identical files; UC8 covers the much harder case — semantically-similar records that need a human-approved merge into one golden record.

Axes: Compositional / AI-suggest → User-approve / External-folder-file (golden record) + KH-DB cleanup / Multi-doc (collapses N → 1) / Dedup-collision / Lineage + Change-report.

4.7.1 User outcome

User (typically a curator or admin) wants to keep the corpus clean — one logical artefact = one canonical record — without having to manually scan for duplicates and without losing anything material when merges happen:

The platform proactively surfaces likely-duplicate candidates with enough context for the user to make an informed merge decision (side-by-side diff, similarity reasoning, citation impact).
The user picks (or composes) the golden record that survives the merge — they’re not forced to accept “newest wins” or “system-chooses”.
Every shipped citation pointing at any of the merged records continues to resolve to its cited text — version-on-cite is preserved.
Content that’s distinct between the candidates (not just redundancy) isn’t silently dropped — the user is shown what’s unique to each and chooses whether to incorporate.
A merge that proves wrong (closer inspection reveals the two records really were different) can be reversed.
The corpus visibly shrinks toward one record per logical artefact, and the audit trail tells the story of how that happened.

4.7.2 Required outputs

Output	Purpose
Duplicate-candidate set — N records suspected to represent the same logical artefact	The proposal to be reviewed
Detection signal — what triggered the suggestion (content-hash similarity / KG entity overlap / chunk-vector similarity / draft-vs-final pattern)	Reviewer needs to understand why these were grouped
Per-pair similarity reasoning — surfaceable explanation (high vector similarity / same source-doc lineage / overlapping entity set)	Builds reviewer confidence; debugs false positives
Side-by-side diff of candidate records	Primary review UI
Unique-content list per candidate — what exists in one record but not the others	Prevents silent loss of distinct content during merge
Citation impact report — which shipped or in-flight artefacts cite any of the candidates	User decision-support; merge must preserve citation validity
Golden-record selection — user-chosen survivor (newest / most-cited / admin-chosen / AI-recommended starting point that user can edit)	The artefact that survives
Merged content — user-curated synthesis if the user composes the survivor, OR direct adoption of one candidate as-is	The final canonical record
Archived (not deleted) merged-away records with redirect lineage	Audit + recoverability
Per-citation re-anchor — every citation pointing at a merged-away record now resolves to the golden record (or to its archived snapshot if version-on-cite applies)	Citations remain truthful
Provenance entry capturing the merge — actor, ts, intent, candidate set, golden record, unique-content-incorporated list	Audit; future “why is this one record instead of three?” answer
KG event — `(record_A, merged_into, record_B, valid_from, actor)`	Mempalace Shape A entry; enables temporal queries about merge history
Rollback affordance	Merge can be reversed if user later determines it was wrong
Change Report	User-visible summary of the merge

4.7.3 Business sequence

Detection. Platform surfaces a duplicate-candidate set via one or more signals — high content-hash / chunk-vector similarity, overlapping entity set in the KG, draft-vs-final pattern recognition (per S188 unmet requirement), shared lineage. Detection runs ambiently after ingest; AI-suggest reviews accumulate in a queue for the curator.
User opens the candidate review. Platform displays: the N candidate records, the detection signal that grouped them, per-pair similarity reasoning, and a citation-impact summary (“merging these would affect 3 shipped bids and 1 in-flight”).
User assesses the proposal. Three primary paths:
- Reject — these are genuinely distinct records; dismiss the suggestion. The platform records the rejection so the same candidates don’t immediately re-surface.
- Defer — looks plausible but needs more thought; park the suggestion for later.
- Proceed to merge — accept that these should become one record.
User selects the golden record — pick one of the candidates as-is, OR compose a new survivor by merging content from multiple candidates (UI assistance: side-by-side editor showing unique-content per candidate, user incorporates desired pieces).
Platform surfaces unique-content warnings — anything present in a non-survivor record that isn’t in the chosen survivor is flagged with a “this will be lost on merge” warning. User confirms acceptance or returns to step 4 to incorporate it.
User reviews citation impact — for each shipped or in-flight artefact citing any of the merged-away records, the user picks: re-anchor to golden record (citation text remains intact if golden contains it verbatim) / mark-as-paraphrased / leave citation pointing at archived snapshot (version-on-cite from UC6 applies).
User states merge intent from a closed vocabulary (provisional, see §4.7.6 Q5): duplicate-versions / draft-and-final / overlap-with-distinct-shapes / hash-collision / admin-cleanup / other-with-note.
User confirms the merge. Platform applies it as a single transactional operation: golden record persists, merged-away records archived (not deleted) with redirect lineage, citations re-anchored per step 6, derived Q&A pairs pointing at merged-away records updated (UC6 review queue if non-trivial), notifications dispatched.
If the underlying source files are external (golden record sourced from an external folder file) — the merge may include archiving / renaming the non-survivor source files in the folder (per write-back path chosen in §6). Cocoindex source-binding observes the resulting folder state and reconciles.
Platform generates the Change Report + KG event + provenance entry. Merge ID retained for rollback support.

4.7.4 Success criteria (user view)

User trusts that no distinct content is silently lost — every unique piece across the candidate set is explicitly accounted for (preserved / incorporated / consciously dropped).
Shipped citations continue to resolve correctly after the merge — never silently broken.
The corpus visibly shrinks toward one record per logical artefact over time.
Rejected suggestions don’t immediately re-surface; the platform learns from the user’s decisions.
A wrongly-applied merge can be rolled back as one operation, restoring the candidates.
The audit trail tells the story months later: which records were merged, when, why, by whom.

4.7.5 What could go wrong (user view)

Failure	User-visible symptom	Mitigation needed
False positive merge proposed — system groups two records that are actually distinct (e.g. two policies covering similar topics for different domains)	Curator fatigue; reduced trust in AI suggestions	§4.7.3 step 1 — detection signal quality matters; surface reasoning so curator can reject quickly; learn from rejections
Silent unique-content loss — user accepts default golden record without realising candidate B had a distinct paragraph that’s now gone	Corpus loses material content; later discovery as missing-answer issue	§4.7.3 step 5 — unique-content warnings; user must explicitly confirm “yes, drop this”
Citation silently invalidated — shipped bid cited a paragraph in merged-away record; paragraph not in golden; citation now lies	Compliance / reputational risk	§4.7.3 step 6 — explicit per-citation decision; never silent re-anchor without user awareness; default to preserving archived-snapshot pointer
Wrong golden chosen — user picks the newer record, but the older had the more accurate content	Loss of accuracy; manual reconstruction needed	§4.7.3 step 4 — let user compose a survivor from multiple, not just pick one; default presentation shows side-by-side diff, not “newest is the answer”
Bulk-merge runaway — system proposes 200 merge candidates after a re-ingest; user clicks “accept all” without per-pair review	Mass corpus corruption; recovery requires bulk rollback	§4.7.6 Q6 — no bulk-accept-all UI; throttle proposals; require per-pair review
Auto-merge over-confidence — very-high-confidence merges auto-fire without user review; one slips through that shouldn’t have	Silent corpus mutation; user loses governance	§4.7.6 Q7 — auto-merge threshold (if any) is very conservative; default is always-prompt; auto-merge logged + reversible
Merge breaks Q&A lineage — Q&A pair sourced from a merged-away record now has a dangling parent	Lineage queries fail; “where did this Q&A come from?” returns null	§4.7.3 step 8 — derived Q&A pairs updated atomically with the merge; if non-trivial, UC6 review queue entry
External folder state desync — merge archives source files; cocoindex hasn’t seen the change yet; KH-DB and folder are inconsistent until next scan	Brief inconsistency window; tooling-side or user-side confusion	§4.7.3 step 9 — write to folder synchronously where possible; cocoindex re-runs flow on observed change; document the eventual-consistency window
Cross-workspace bleed — merge accidentally includes a record from a different workspace	Cross-tenant data corruption	§4.7.6 Q8 — scope confirmation; default scope is current workspace; cross-workspace requires elevated permission
DRAFT-vs-final pattern missed — system fails to recognise `DRAFT-X.docx` and `X.docx` as duplicates; both ingested as independent records	Silent duplicate accumulation	§4.7.6 Q1 — detection signal coverage for the DRAFT-vs-final pattern (per S188 unmet requirement); exercise on `docs/client-documentation-base/binary/` DRAFT fixtures during spike

4.7.6 Open questions for §6

#	Question
4.7.Q1	Primary detection signal — content-hash similarity threshold / KG entity overlap / chunk-vector similarity / combination? Each candidate maps to a different substrate (cocoindex post-target-write `@coco.fn` / mempalace KG entity-resolution / skill-seekers metadata). `[DECISION-PENDING-§6]` — spike S2 + S3 + S5 probe substrate fit.
4.7.Q2	Proposal UX — side-by-side diff / merged-preview / interactive composition (let user assemble survivor from multiple)? Interactive composition is highest-fidelity but most expensive to build.
4.7.Q3	Golden-record selection default — newest record / most-cited / longest / admin-chosen / AI-recommended-with-edit? Probably “AI-recommended-with-edit” — system proposes, user adjusts.
4.7.Q4	Citation preservation policy — re-anchor to golden where text matches, mark-as-paraphrased otherwise, OR always preserve archived-snapshot pointer (version-on-cite from UC6)? Likely a combination, decided per-citation.
4.7.Q5	Intent vocabulary — closed taxonomy at step 7 (duplicate-versions / draft-and-final / overlap-with-distinct-shapes / hash-collision / admin-cleanup / other) or free-text? Closed aids analytics + rollback grouping.
4.7.Q6	Bulk-merge throttling — N proposals max per review session, or batch-grouped (e.g. “these 12 DRAFT-vs-final pairs all surface together”) with batched approval?
4.7.Q7	Auto-merge threshold — should the system ever auto-merge without user review (very high confidence, e.g. byte-identical files with different paths)? If yes, what threshold + audit + reversibility? Probably no auto-merge at v1 — always-prompt.
4.7.Q8	Cross-workspace merge — admin-only? Never v1?
4.7.Q9	Derived Q&A pair handling on merge — auto-update Q&A pair source-doc references, or queue for UC6 review, or both depending on materiality? Tension with UC6 in-flight citer policy.
4.7.Q10	Folder-state side effects — does merge archive / rename the source files in the folder (writing back), or only operate on the materialised representation in KH-DB? Likely both — golden record’s source file kept; merged-away source files moved to an `_archived/` subfolder or renamed. Interacts with chosen write-back path (Candidate A/B/C).
4.7.Q11	Detection-signal coverage for DRAFT-vs-final — explicit pattern detector (filename prefix + content overlap), or generic high-similarity detection that happens to catch DRAFT-vs-final, or both? Per S188 user requirement + corpus fixtures in `docs/client-documentation-base/binary/`.
4.7.Q12	Reject-learning — does the system learn from rejected suggestions (don’t re-propose this pair) or only suppress per-session? Per-workspace rejection memory adds DB burden but improves curator UX over time.

4.7.7 Tooling implications (referenced from §10)

Cocoindex PRIMARY for content-hash + cross-record post-ingest dedup detection via @coco.fn (per §10 row UC8) — runs after target-write, comparing newly-ingested record against existing corpus. Closes the cross-record dedup gap per §9.9.
Mempalace Shape A PRIMARY for KG entity-resolution (per §10 row UC8) — records sharing significant entity overlap are dedup candidates; temporal columns track merge history.
Skill-seekers metadata categorisation SUPPORTING — pattern-inspiration only; categorisation rules could inform “these two records sit in the same category and have high overlap” detection signal (per §10 row UC8).
Substrate-choice for cross-record dedup is [DECISION-PENDING-§6] — spikes S2 (cocoindex post-target-write @coco.fn) + S3 (mempalace KG entity-resolution) + S5 (skill-seekers metadata as inspiration) probe fit. Choice constrains where dedup logic lives.
Claude API tool use SUPPORTING — propose-merge UI may use Claude to generate per-pair similarity reasoning (“these two records both describe the same Bitdefender deployment but differ on date”) that’s more useful than raw similarity scores.
Anthropic citations SUPPORTING — citation re-anchoring on merge follows the same shape as UC4 / UC6 citation-update logic.
Tiptap + Yjs SUPPORTING — interactive golden-record composition (step 4) may use the existing collab editor surface.
Existing KH primitives RETIRED per §9.2 — 'identical' warning + 'new_version' INSERT path + upload-time content-hash dedup are obsoleted by cocoindex Δ semantics. Cross-record near-duplicate detection (UC8 substrate) is the new design, not an extension of the upload-time path.

4.8 UC9 — Scope-tag taxonomy update

A workspace admin is changing the vocabulary of scope tags that label “what does this content apply to?” — adding a new tag, splitting an existing one into more precise children, retiring a tag that proved unused, or revising the keyword + anti-tag hints that drive classification. Per 0.8.5-skill-seekers-evaluation.md §2.4 verdict, this is a KH-native typed-column implementation; the skill-seekers categories keyword pattern is inspiration only. Per Q1.7 RESOLVED, scope tags are multi-valued; per the client feedback Item 3 quote, anti-tags (“does NOT apply to: production-infrastructure”) are required to prevent high-confidence-wrong-scope retrieval errors. Per-tenant taxonomy: Phew uses internal-it / production-infrastructure / application-layer / office-physical / data-centre-physical; another client may have entirely different scopes.

Axes: Structural / User-direct (admin) / KH-derivative (metadata) / Workspace-wide / None expected / Lineage.

4.8.1 User outcome

Admin wants to evolve the workspace’s scope vocabulary so retrieval honestly distinguishes content domains, without painfully hand-relabelling thousands of records and without breaking shipped artefacts that depended on the old taxonomy:

The admin can introduce, rename, split, merge, retire, or refine the keyword + anti-keyword hints of any scope tag in the workspace’s vocabulary, in one place, with the change applied consistently across the corpus.
Existing records pick up the new taxonomy on the admin’s chosen rollout strategy: re-classify everything immediately, re-classify only ambiguous records, or apply only to newly-ingested records (taxonomy goes forward only).
Records that match multiple scope tags (or match a tag whose anti-keywords also fire) are surfaced for explicit review rather than silently first-match-wins.
Anti-tags (“does not apply to”) are first-class citizens — the admin can declare them, the platform respects them at retrieval, and the user surface shows them so a reviewer understands why a record was excluded.
AI consumers (Claude via MCP search) immediately respect the updated taxonomy on the next query — search filters honour the new tag set without a separate cache-invalidation step.
Shipped artefacts that cited records under the prior taxonomy continue to resolve correctly; tag changes do not retroactively invalidate citations.

4.8.2 Required outputs

Output	Purpose
Updated scope vocabulary for the workspace — added / renamed / split / merged / retired tags + their keyword + anti-keyword hints	The admin’s primary change
Re-classification result per affected record (when rollout chosen) — new tag set, anti-tag set, conflict-flag if multiple tags fire	Records reflect the new vocabulary
Conflict-surfacing queue — records that triggered multi-tag matches or keyword/anti-keyword collisions	Admin reviews + resolves rather than silent default
Per-record provenance entry for each tag change	Audit; “why does this record have these tags now?”
Rollout summary — tally of records re-classified, conflict-flagged, unchanged	Admin decision-support post-rollout
Search-filter availability — `scope_filter` parameter on the corpus-search MCP tool reflects new tags immediately (per CX.27 RESOLVED)	AI consumers respect new taxonomy on next query
Lineage — taxonomy version with timestamps + actor; prior versions queryable	Audit; rollback support
Notification to subscribers	Workspace members + curators see the taxonomy change
Optional: derived-Q&A scope-tag review queue	Q&A pairs inheriting tags from source docs (per Q3.12 PROVISIONAL) may need separate review

4.8.3 Business sequence

Admin opens the workspace’s scope vocabulary surface — sees the current tag set, each tag’s keyword hints + anti-keyword hints + a usage count (how many records currently carry this tag).
Admin makes the change — adds a new tag with hints, renames an existing tag, splits one tag into two more precise children, merges two tags into one, retires a tag, or revises hints on an existing tag. Each change is captured as a discrete edit so the admin can review before commit.
Platform shows the impact preview — for each pending change, a count of affected records, a sample of records that would be re-tagged or conflict-flagged, and an estimate of how many records would land in the conflict-surfacing queue under the new rules.
Admin chooses the rollout strategy for this batch of changes:
- Re-classify everything — apply new taxonomy to all existing records immediately.
- Re-classify ambiguous only — only records whose current tags would change under the new vocabulary; leave clearly-tagged records alone.
- Forward-only — taxonomy applies only to records ingested from now on; existing records keep their prior tags until manually re-classified or naturally re-ingested.
- Bulk-prompt-admin — re-classify but route every changed record through the conflict-surfacing queue for admin approval (high control, high cost).
Admin states intent from a closed vocabulary (provisional, see §4.8.6 Q4): new-domain / domain-split / domain-merge / vocabulary-cleanup / regulatory-driven / client-feedback-driven / other-with-note.
Admin confirms. Platform applies the taxonomy change as a single atomic operation with a shared taxonomy-update ID. Rollout proceeds per chosen strategy.
Conflict-surfacing. Records that match multiple tags (or trigger keyword + anti-keyword collisions) land in a review queue. Admin works through the queue: confirm one tag wins, accept multi-tagging, override with manual selection, or send back for hint refinement.
Lineage write. Taxonomy version recorded; per-record tag changes attributed to the taxonomy-update ID; prior tag values preserved for temporal queries (per UC6 version-on-cite spirit).
Notify subscribers + admin if material change affecting many records.
Optional follow-up. If the taxonomy change implies derived Q&A pairs need re-tagging (per Q3.12 — Q&A scope inherits source-doc tag by default), platform offers to walk through affected Q&A pairs in a follow-up review queue.

4.8.4 Success criteria (user view)

Admin makes one taxonomy change and sees it land everywhere it should — no records silently keeping stale tags after a rename, no records silently re-tagged when forward-only was chosen.
Conflict cases (multi-tag matches, keyword/anti-keyword collisions) are surfaced for review, never silently first-match-wins.
Anti-tags work — a record with “does not apply to: production-infrastructure” never surfaces in a production-infrastructure-scoped search, regardless of how strong the positive match is.
AI consumers honour the new taxonomy immediately on the next query — no stale-cache window where MCP search returns the old vocabulary.
Shipped artefacts with citations are unaffected by tag changes — citations resolve to the cited content regardless of how the source’s tags were updated.
The audit trail tells the story of how the vocabulary evolved — readable months later: which tags were added when, which were retired and why.

4.8.5 What could go wrong (user view)

Failure	User-visible symptom	Mitigation needed
Silent re-tagging — admin chose “forward-only”, but existing records get re-tagged anyway because of an implementation bug	Trust collapse — admin can’t predict what happens to the corpus	Architectural enforcement of rollout strategy at commit time; per-record provenance proves what was changed
Conflict-surfacing queue overwhelm — taxonomy change fires conflicts on hundreds of records; admin can’t realistically work through them	Admin clicks “accept all”; conflicts silently default	§4.8.6 Q3 — batch grouping, per-pattern resolution (“all records matching this pattern → tag X”), throttled review surface
First-match-wins regression — under load or concurrency, conflict-detection silently picks one tag without flagging	The exact failure mode the client called out — high-confidence-wrong-scope retrieval	Architectural enforcement; conflict-detection runs synchronously in classification path; never optimised away
Anti-tag ignored at retrieval — record has anti-tag “does not apply to: production-infrastructure”, but search filter `scope_filter=production-infrastructure` returns it anyway	The Bitdefender failure repeats; client loses trust	Architectural test: anti-tags are filter-time exclusions, not just labels; integration tests required (per CX.27 RESOLVED, MCP search must honour scope_filter + anti-tags together)
Cross-tenant taxonomy bleed — admin’s vocabulary change accidentally affects another workspace’s records	Cross-tenant data corruption	Workspace-scoped taxonomy enforced at every layer; cross-workspace changes (if ever needed) require platform-admin role
Q&A pair scope drift — taxonomy update changes a source doc’s tags; Q&A pairs derived from that doc still carry old tags; AI surfaces old-tag Q&A in new-tag scope	Inconsistency between source and derivative; the Bitdefender problem at the Q&A layer	§4.8.6 Q5 — Q&A scope-tag inheritance policy (per Q3.12 PROVISIONAL); follow-up Q&A re-tag review at step 10
Hint regression — admin tweaks keyword hints; classifier now mis-tags previously well-tagged records	Corpus quality degrades silently	Step 3 impact preview — show admin which currently-tagged records would change classification under new hints
Stale MCP-search cache — taxonomy updated, but search results served from a stale cache for minutes/hours	AI consumer returns old-vocabulary results	Architectural choice: cache invalidation on taxonomy commit; or cache-key includes taxonomy version
Retired-tag references in shipped citations — admin retires a tag that’s referenced in metadata of a shipped artefact’s citation	Citation metadata broken; reviewer can’t tell what scope the cited record had at ship time	Pin citation metadata to taxonomy-version-at-ship-time; retired tags remain queryable in archived snapshots
Rollback complexity — admin tries to undo a taxonomy change; some affected records were edited after the rollout, so their state is mixed	Rollback ambiguous; manual triage needed	Taxonomy-update ID retains per-record prior values; rollback prompts admin for each post-rollout-edited record

4.8.6 Open questions for §6

#	Question
4.8.Q1	Taxonomy definition UX — admin-managed dropdown form / YAML config in workspace settings / DB seed file with admin UI overlay? Maps to skill-seekers `categories` keyword-rule pattern (inspiration only per §10). Likely DB-backed with admin UI (per CX.16 PROVISIONAL ~7-9d cost).
4.8.Q2	Rollout strategy default + permitted set — re-classify everything / re-classify ambiguous only / forward-only / bulk-prompt-admin? Per-change choice or workspace policy? Default likely “re-classify ambiguous only” to balance currency vs admin load.
4.8.Q3	Conflict-surfacing UX — per-record review / pattern-grouped review / dashboard tile with batch actions? Threshold for routing to bulk vs individual review?
4.8.Q4	Intent vocabulary — closed taxonomy at step 5 (new-domain / domain-split / domain-merge / vocabulary-cleanup / regulatory-driven / client-feedback-driven / other) or free-text? Closed aids analytics + rollback grouping.
4.8.Q5	Q&A scope-tag inheritance — per Q3.12 PROVISIONAL “per-pair”, does a taxonomy change on a source doc auto-propagate to derived Q&A pairs, queue them for review (UC6 AI-suggest), or leave them unchanged unless explicitly re-classified?
4.8.Q6	Anti-tag UX — separate field on each scope tag definition / negative-polarity flag on a single field / dedicated `anti_scope_tag` array on each record? Implementation per Q1.7 RESOLVED (multi-value array); admin surface still TBD.
4.8.Q7	Per-tenant vocabulary vs platform-default seed — does each workspace start blank, with a platform-default starter taxonomy, or by selecting a sector template (e.g. “MSP”, “professional services”)? Phew’s vocabulary is unlikely to suit a non-MSP client; some seed pattern speeds onboarding.
4.8.Q8	MCP search-filter integration shape — `scope_filter` parameter on `search_knowledge_base` accepts single tag / array of tags / boolean expression (tag-AND-tag, tag-OR-tag, NOT-tag)? Per CX.27 RESOLVED the parameter exists; expressiveness TBD. Anti-tag enforcement is filter-time exclusion regardless of caller’s filter expression.
4.8.Q9	Classifier integration — keyword-rule scan tier + AI classification tier (per skill-seekers-eval §2.9 proposed pattern) — both? AI-only? Keyword-only? Hybrid is most flexible but more moving parts.
4.8.Q10	Taxonomy versioning + rollback — full version history with named taxonomy-update IDs (per step 6 + step 8) — granularity: workspace-level taxonomy version OR per-tag version? Retention period?
4.8.Q11	Admin gating for taxonomy edits — workspace admin only, or specific “curator” role within workspace? Per §3.8 UC9 likely admin-only; confirm.
4.8.Q12	Stale-cache window post-commit — synchronous cache invalidation on commit, or eventually-consistent? Acceptable lag for MCP search reflecting new taxonomy?
4.8.Q13	Tag deletion / retirement semantics — hard-delete (forbidden if any record carries the tag), soft-archive (records keep the tag but it doesn’t surface in admin UI), or split-and-replace required (admin must retag all references first)?

4.8.7 Tooling implications (referenced from §10)

None primary. Per §10 row UC9, no third-party tool covers this — KH-native typed columns + anti-tags + conflict-surfacing per 0.8.5-skill-seekers-evaluation.md §2.4 verdict + Q1.7 RESOLVED.
Skill-seekers categories keyword pattern is INSPIRATION ONLY (per §10 row + §2.4 + §2.9 verdict) — informs the keyword + anti-keyword classifier-rule shape; NOT a source of code or schema.
Mempalace NO — taxonomy is workspace-scoped operational metadata; out of mempalace’s KG/temporal scope.
Cocoindex NO — taxonomy lives in KH-DB, not in the canonical-pipeline output. SUPPORTING only in the indirect sense that re-ingest of an external file re-runs classification, naturally picking up the latest taxonomy on the next flow execution.
Anthropic citations NO for the taxonomy operation itself; SUPPORTING-via-architecture for ensuring shipped citation metadata pins to the taxonomy-version-at-ship-time (per §4.8.5 retired-tag-citation row).
Tiptap + Yjs NO — admin taxonomy editor is a form, not a CRDT-collab editor.
Implementation effort: new OPS-X-SCOPE-TAGS work-package, ~1-2 weeks per skill-seekers-eval §2.4 recommendation (DB column + classification rule + MCP response shape + UI surface). Per CX.16 PROVISIONAL ~7-9d total. Independent of cocoindex / mempalace / skill-seekers integration.

4.9 UC2 — Date/version-number bump — possibly merge into UC1 (de-scoped per §3.2)

5. Tooling-fit evaluation per data flow

§5 refines §10’s PRIMARY/SUPPORTING/NO matrix into per-UC narrative + Candidate A/B/C fit per write-back UC. §10 captures capability mapping (what each tool can do for each UC); §5 captures implementation fit (which candidate path is the natural carrier for each UC’s primary intent). §6 turns §5 narratives into ratified decisions.

5.0 Three write-back candidates (carry-forward from placeholder)

Candidate A — In-platform editor + filesystem write. KH UI captures the edit; KH server writes both DB row and external folder file. Source file rewritten via filesystem API (LocalFS) or connector API (SharePoint, Notion). Simplest UX; KH owns the write-back. Risk: connector API limitations; version-bump semantics differ across providers; transactionality between DB write + file write (UC1 §4.1.6 Q2).
Candidate B — Claude API text-editor-tool write-back. KH server invokes Anthropic API with the tool; tool writes file; cocoindex source-binding observes the change; flow runs; UPSERTs DB row. KH server does NOT write DB directly; DB is materialised view. Strength: handles natural-language-to-edit translation natively; reusable for bulk + sweeping ops; cleanly resolves Candidate A’s transactionality bug (file is single source of truth, DB lags by one scan cycle). Risk: cost per edit (atomic typo via API is wasteful); latency (round-trip to Anthropic); tool-use limits. Research URLs in 0.9-context.md §4.
Candidate C — Managed Agent (dedicated documentation agent). KH queues a task for a documentation-agent (Anthropic Managed Agents or similar long-running agent surface); agent reads file + edit intent + writes file with structured audit log; cocoindex picks up; flow updates DB. Strength: best fit for sweeping / scheduled / AI-suggest triggers with rich context; preserves human-in-the-loop review without UI plumbing. Risk: orchestration complexity; permission model; per-task cost; latency.

Substrate tooling layered on top of any candidate (already mapped in §10):

Cocoindex — engine-native Δ semantics; source-key + content-hash UPSERT; ops-DB ledger for provenance.
Mempalace Shape A — temporal KG records edits as events; valid_from/valid_to for version-on-cite.
Anthropic citations — citation immutability at API level (cite captures version-id; immutable).
Tiptap + Yjs — concurrent-user CRDT for in-platform edits (already adopted; one plugin away).
Skill-seekers categorisation — inspiration only for UC8/UC9 (per §2.4 verdict).

5.1 UC1 — Typo fix

Primary substrate: Tiptap + Yjs for the editor surface (concurrent-user CRDT). Cocoindex SUPPORTING via source-binding observing the resulting file change.

Candidate fit recommendation: Candidate A. Atomic single-record edits do not justify per-edit Claude API cost (Candidate B) or Managed Agent orchestration overhead (Candidate C). KH server writes DB row + file at source_documents.original_path; cocoindex source-binding observes the file on next scan; idempotency confirmed by S9 spike skips flow re-run when hash matches. Yjs collab plugin enables concurrent-user resolution at the editor layer; last-write-wins at the file layer is post-CRDT-merge.

Bypass-candidate-B rationale: the typo case is the worst economic fit for Claude API per-edit cost. Reserve Candidate B for cases where the LLM’s natural-language-to-edit translation earns its keep (UC3 smart-agent variant).

Gaps requiring new design:

Yjs collab plugin enable on non-Q&A content editors (~1 day; existing for Q&A per S198).
Write-back path: filesystem API for LocalFS; SharePoint Files API + Notion API for v1.1+ connectors.
Sidecar policy for binary sources (§4.1.6 Q6).

5.2 UC2 — Date / version-number bump (de-scoped)

UC2 reduces to UC1 per S228 §3.2 ratification. Sweeping date update is rare; expiry-dates handled separately by Q1.8 extractDates flow. Adopt UC1’s Candidate A for the residual atomic case. No distinct tooling fit.

5.3 UC3 — Sweeping rename

Primary substrate: Claude API text-editor-tool for smart-agent variant. Bespoke @coco.fn over markdown corpus for find-replace variant. Cocoindex re-runs flow on every changed file. Mempalace Shape A SUPPORTING — sweep ID surfaces as KG event linked to every per-record edit, enabling “show me all changes from sweep S” temporal queries.

Candidate fit recommendation: Candidate B for smart-agent variant; Candidate A or bespoke @coco.fn for find-replace variant. Smart-agent’s natural-language-to-edit translation is exactly the Anthropic SDK’s strength; per-match confidence scores + surrounding-context reasoning fall out naturally. Find-replace doesn’t need LLM cost; KH server iterates affected files + writes them directly under a shared sweep ID.

Candidate C alternative: Managed Agent makes sense if find-replace + smart-agent variants both run under one orchestration surface that captures provenance per-sweep. Worth probing in S9.

Gaps requiring new design:

Sweep-ID provenance shape (per-record entries reference shared op ID); supports rollback-by-operation-ID (§6.0 decision).
Preview-before-commit UI for both variants.
Per-record concurrency model interacting with Yjs collab on in-flight records (§4.5.6 Q3).

5.4 UC4 — Paragraph rewrite (cited content)

Primary substrate: Anthropic citations for cited content (PRIMARY per §10). Tiptap + Yjs for the editor surface (PRIMARY in-platform). Mempalace Shape A SUPPORTING for downstream-impact queries (“what cited this Q&A, valid_to >= ?”). Confidence taxonomy (Q4.7 KG-provenance enum + Q4.14 graphify-confidence-label) informs source classification at edit time.

Candidate fit recommendation: Candidate A for in-platform edit + folder write-back. UC4 is fundamentally a human-driven paragraph rewrite within an artefact context (a bid response); Claude API would add latency without commensurate value. Candidate B is the right tool for AI-suggested edits or sweeping variations (UC3, UC8) — not interactive paragraph editing.

The hard part is NOT tooling, it is policy: edit-intent classification (revise Q&A vs edit locally only vs promote variation), citation re-anchor strategy, downstream-impact UI. §6.0 + §6.4 resolve these as decisions, not tool choices.

Gaps requiring new design:

Source-classification UI at the paragraph level (approved Q&A / draft Q&A / MCP-derived / generated).
Edit-intent capture flow at save time.
Anthropic citations re-anchor mechanism (per §6.0 decision).

5.5 UC5 — Bid response → Q&A promotion

Primary substrate: Mempalace Shape A for provenance + lineage. Anthropic citations SUPPORTING (the source bid response may carry citations that the promoted Q&A inherits). Existing Q&A ContentEditor (S198) is the natural editing surface; Tiptap + Yjs SUPPORTING for collaborative review.

Candidate fit recommendation: None applies directly — UC5 is KH-DB-only. Promotion creates a new Q&A pair (draft state); no external folder write-back at promotion time. Cocoindex SUPPORTING only when an approved Q&A pair gets materialised to a markdown sidecar in the folder (deferred decision per §4.6.6 Q7) — at which point the sidecar write follows UC6’s chosen candidate.

Gaps requiring new design:

Similarity check against existing Q&A pairs at promotion time (echoes UC8 substrate decision).
Approval workflow integration with publish_status lifecycle.
AI-suggest promotion candidate triggering (mempalace miner pattern SUPPORTING per Q4.3 PENDING-ARCH).

5.6 UC6 — Q&A pair revision

Primary substrate: Mempalace Shape A for version-on-cite + temporal queries. Anthropic citations PRIMARY for shipped bid citation immutability. Tiptap + Yjs SUPPORTING for the Q&A editor surface. Cocoindex SUPPORTING only for source-doc-change detection feeding AI-suggest trigger (UC10 territory).

Candidate fit recommendation: None applies for the Q&A revision itself — KH-DB-only. If Q&A is backed by a markdown sidecar (per §4.3.6 Q7), the sidecar write follows UC1’s Candidate A pattern. AI-suggest revision composition (§4.3.6 Q8) is a strong Candidate B fit — Claude API generating a draft revision based on a source-doc change is exactly the smart-rewrite use case.

Gaps requiring new design:

Citers report query (mempalace KG SUPPORTING).
In-flight citer policy enforcement (§6.0 + §6.6 decisions).
Source-doc change detection criteria + threshold (§4.3.6 Q1).
AI-suggest composition shape (Candidate B: KH server invokes API to propose revision; user reviews and edits; final commit follows §4.3.3 step 7).

5.7 UC7 + UC10 (collapsed) — External folder change detected

Primary substrate: Cocoindex source binding (PRIMARY per §10 — Appendix §9.1 trace is the canonical reference). Mempalace Shape A SUPPORTING for lineage events; temporal queries answer “what changed in the source for this Q&A pair?”. Anthropic citations SUPPORTING for re-anchoring on cited content change.

Candidate fit recommendation: None applies — UC7/UC10 is system-driven, not user-driven. Cocoindex’s source binding IS the implementation. The only user-facing surface is the conflict-resolution UI when an in-platform edit collides with a concurrent external edit; that conflict UI uses git-style merge prompts (or similar), NOT Tiptap or a Candidate.

Gaps requiring new design:

Conflict surface UI when transactional-window collision detected.
Polling cadence + webhook strategy per connector (§4.4.6 Q1; spike S2 probes).
Rename detection precision (content-hash + path-disappearance heuristic).
Soft-delete-with-grace-period UX for bulk-delete scenarios.

5.8 UC8 — AI-suggested dedup merge

Primary substrate: Cocoindex @coco.fn for content-hash + post-target-write cross-record dedup. Mempalace Shape A for KG entity-resolution. Substrate choice is [DECISION-PENDING-S10-spike] — S10 spike compares cocoindex post-target-write @coco.fn vs mempalace KG entity-resolution vs skill-seekers metadata-as-inspiration; chosen substrate becomes UC8 PRIMARY. Anthropic citations SUPPORTING for citation re-anchoring on merge. Claude API tool use SUPPORTING — propose-merge UI may use Claude to generate per-pair similarity reasoning more useful than raw scores.

Candidate fit recommendation: Candidate C is the natural fit for AI-driven dedup merge orchestration. A documentation-agent receives the candidate set + side-by-side diff + user-chosen golden record selection + intent, then executes the merge under a shared op ID with structured audit log. Candidate A is feasible (KH server does the merge directly) but loses some of the “agent-as-orchestrator” leverage for complex compositional merges. Candidate B fits the similarity-reasoning sub-step but not the full merge orchestration.

Open question for §6: does Candidate C make Managed Agents a v1 commitment (additional infrastructure cost) or v2 (UC8 starts with Candidate A + AI-as-LLM-tool for reasoning steps; Candidate C upgrade later)? §6.8 resolves.

Gaps requiring new design:

Cross-record dedup detection signal (S10 spike outcome).
Side-by-side diff + interactive golden-record composition UI.
Per-citation decision UX (re-anchor / mark-as-paraphrased / leave-archived-snapshot).
Reject-learning memory (per-workspace rejection state; per §4.7.6 Q12).

5.9 UC9 — Scope-tag taxonomy update

Primary substrate: None — KH-native typed-column work-package per skill-seekers-eval §2.4 verdict + Q1.7 RESOLVED. Skill-seekers categories keyword pattern is INSPIRATION ONLY (informs the keyword + anti-keyword classifier-rule shape, not a code source).

Candidate fit recommendation: None applies — UC9 is KH-DB workspace-metadata operation. Admin taxonomy editor is a form, not a CRDT-collab editor; no folder write-back; no LLM-driven smart-edit.

Gaps requiring new design (all KH-native):

DB schema for scope-tag definitions (per-workspace) + anti-keyword hints.
Admin UI surface for vocabulary management (CRUD + impact preview + rollout-strategy chooser).
Conflict-surfacing queue UI for multi-tag matches + keyword/anti-keyword collisions.
Classifier integration (keyword-rule scan tier + AI classification tier per §4.8.6 Q9).
MCP search-filter integration: scope_filter parameter expressiveness (single tag / array / boolean expression per §4.8.6 Q8).
Taxonomy versioning + per-tag rollback support.
Stale-cache invalidation on taxonomy commit (§4.8.6 Q12).

Per OPS-X-SCOPE-TAGS work-package — ~1-2 weeks per skill-seekers-eval §2.4 recommendation; CX.16 PROVISIONAL ~7-9d total.

5.10 Summary candidate fit matrix

Per-UC Candidate-A/B/C fit recommendations (output of §5.1-§5.9). Drives §6 decisions.

UC	Candidate A (in-platform + FS write)	Candidate B (Claude API text-editor-tool)	Candidate C (Managed Agent)	Substrate tooling primary
UC1 typo fix	RECOMMEND — atomic, no LLM value-add	NO — per-edit API cost wasteful	NO — orchestration overhead unjustified	Tiptap + Yjs + cocoindex
UC2 date bump (de-scoped)	RECOMMEND — collapses to UC1	NO	NO	UC1 inherits
UC3 sweeping rename (find-replace)	RECOMMEND — KH server iterates files under sweep ID	SUPPORTING — for confidence-reasoning per-match	CANDIDATE — orchestration value if both variants share	Cocoindex re-runs flow
UC3 sweeping rename (smart-agent)	NO — needs LLM	RECOMMEND — natural fit for NLP-to-edit	CANDIDATE — wraps Candidate B with orchestration	Cocoindex re-runs flow
UC4 paragraph rewrite (cited)	RECOMMEND — human-driven; LLM unnecessary	NO — interactive editing not API-fit	NO	Anthropic citations + Tiptap + mempalace
UC5 bid → Q&A promotion	N/A — KH-DB only	N/A	N/A	Mempalace Shape A
UC6 Q&A revision (user-direct)	N/A — KH-DB only	N/A	N/A	Mempalace + Anthropic citations
UC6 Q&A revision (AI-suggest)	NO	RECOMMEND — KH server invokes API for revision draft	CANDIDATE — wraps Candidate B with orchestration	Mempalace + Anthropic citations
UC7+10 external folder change	N/A — system-driven, no write-back UC	N/A	N/A	Cocoindex source binding
UC8 AI-dedup merge	CANDIDATE — KH server does merge directly	SUPPORTING — for similarity-reasoning sub-step	RECOMMEND — orchestrate compositional merge with audit log	Cocoindex `@coco.fn` or mempalace KG (S10 decides)
UC9 scope-tag taxonomy	N/A — workspace-metadata, no write-back	N/A	N/A	KH-native (no third-party)

Net read:

Candidate A is the v1 baseline for atomic + bounded human-driven in-platform edits (UC1 / UC2 / UC4). Lowest cost, simplest path, leverages existing Tiptap + Yjs.
Candidate B carries the AI-driven UCs (UC3 smart-agent / UC6 AI-suggest / UC8 reasoning sub-steps). Per-edit API cost is justified by the LLM’s value-add.
Candidate C is conditional — strong fit for UC8 orchestration + UC3 sweep wrapping, but introduces Managed Agents as a v1 dependency. §6.8 decides whether UC8 ships as Candidate A + LLM-tool-for-reasoning (v1) or Candidate C (v1.1+).
Substrate tooling (cocoindex / mempalace / Tiptap+Yjs / Anthropic citations) layers across all candidates and is already adopted (decisions ratified S228). No substrate spike blocks §6.

§6 takes these recommendations and turns them into ratified decisions — including the cross-UC decisions in §3.9 that apply uniformly regardless of candidate.

6. Architectural decision

§6.0 captures the 7 cross-UC consolidated decisions (per §3.9). §6.1-§6.9 capture per-UC residuals (primarily Candidate A/B/C choices). §6.10 maps decisions back to 0.9-decision-graph.md, 0.9-intended-architecture.md, and 0.9-spike-plan.md.

Status: RATIFIED S229 via sequential AskUserQuestion rounds (Liam). All Candidate A/B/C choices + cross-UC decisions accepted as recommended unless noted. Implementation work follows architecture rewrite (sub-agent B) + spike phase outputs.

6.0 Cross-UC consolidated decisions

6.0.1 Intent-taxonomy policy — RATIFIED

Decision: Closed per-UC vocabulary + free-text ‘other’ escape.

Each UC defines its own closed vocabulary at commit time (UC6 revision: typo / factual-update / regulatory-change / source-doc-driven / dedup-merge / promotion-from-bid-variation / clarification; UC8 merge: duplicate-versions / draft-and-final / overlap-with-distinct-shapes / hash-collision / admin-cleanup; etc.). Every closed list includes an other-with-note option requiring a short free-text reason.

Rationale: closed taxonomies aid analytics + rollback grouping; the free-text escape valve preserves edge-case capture without forcing users into nearest-fit miscategorisation. Governance is uniform across all UCs (one rule); per-UC vocabularies differ in content but obey the same enforcement style.

Carry-forward to: UC4.2.Q3 (intent-at-edit-vs-save-time) — intent captured at commit time, before transaction lands. UC5.6.Q3, UC6.3.Q4, UC8.6.Q5, UC9.6.Q4 ratifications follow this policy. Per-UC §6.x sections do not re-litigate.

6.0.2 Anthropic citations re-anchor policy — RATIFIED

Decision: Hybrid — re-anchor if verbatim match, else mark-as-paraphrased with archived-snapshot pointer.

When an edit lands on text cited by a shipped or in-flight artefact: (1) the platform tests whether the cited substring still appears verbatim in the new text. If yes → re-anchor citation pointer to the new location (citation remains truthful and current). (2) If the cited substring no longer appears verbatim → citation is marked paraphrased from [snapshot] with a pointer to the archived snapshot of the prior text version. User reviews ambiguous cases per the downstream-impact UI (§6.0.5).

Rationale: preserves citation truthfulness without forcing user re-review on every edit. Re-anchor opportunity is captured where the text still matches; paraphrase mark is honest about loss of verbatim equivalence. Per-citation explicit; never silent invalidation.

Implementation caveat: depends on Claude API citation primitives. If the Anthropic citations feature does not natively expose re-anchor APIs, KH wraps citations in its own pointer layer that mediates the verbatim-vs-paraphrased decision. Spike S9 + edit-flow §5 implementation work confirms the mechanism. The decision stands regardless of low-level mechanism.

Carry-forward to: UC4 (4.2.Q4 RESOLVED), UC6 (3.5 reaffirmed), UC7+10 (4.4 step 5), UC8 (4.7.Q4).

6.0.3 Citation immutability binding — REAFFIRMED (RESOLVED at UC6 §3.5)

Decision: Version-on-cite at ship time. Shipped artefacts capture the cited Q&A pair version at ship time; that version is preserved with valid_from/valid_to temporal bounds. Pre-ship Q&A pairs continue to evolve; shipped citations resolve to the cited version snapshot, not the moving head.

Rationale: balances corpus evolution (Q&A pairs improve over time) against shipped artefact integrity (a bid response cannot retroactively change). Maps cleanly onto mempalace Shape A temporal columns.

Carry-forward to: UC4 (4.2.Q7), UC5 (4.6 — promoted Q&A inherits citation lineage), UC6 (§3.5), UC8 (4.7.Q4 per-citation policy implementation).

6.0.4 Permission gating per UC — REAFFIRMED (RESOLVED at §3.8)

Decision: Per publication-lifecycle-state-machine-spec.md role matrix — publish_status enum (draft / in_review / published / archived) + editor / admin role + state-machine transitions.

Allocation by UC:

Editor + admin: UC1, UC4, UC5, UC6 (user-direct + AI-suggest review)
Admin only: UC3 (sweeping rename), UC8 (dedup merge), UC9 (scope-tag taxonomy)
System-driven (no role gate): UC7, UC10 (external folder change detection + reconciliation)

UI surfaces 403 via toast on disallowed transitions per spec AC (j). Cross-workspace operations (UC3 cross-workspace sweep, UC8 cross-workspace merge, UC9 platform-level taxonomy) require elevated permission (admin-of-admins) if ever enabled — not v1.

Carry-forward to: UC1 (4.1.Q5), UC3 (4.5.Q7), UC4 (mapping), UC8 (4.7.Q8), UC9 (4.8.Q11). Per-UC §6.x sections do not re-litigate.

6.0.5 Downstream-impact UI shape — RATIFIED

Decision: Count + paginated affected-record list. User sees an impact summary (“revising this Q&A affects 12 shipped bids and 3 in-flight”), expandable into a paginated list showing per-record citation context. Interactive per-record diff preview is NOT v1; user clicks through to the affected record for full detail if needed.

Rationale: balances decision-support against UI complexity. Count gives a quick gut-check; paginated list with per-record context lets user trim or proceed informed. Interactive preview for every affected record would be expensive to build + overwhelming at scale (e.g. taxonomy update affects hundreds of records).

Carry-forward to: UC4 (4.2.Q2), UC6 (4.3.3 step 6, 4.3.6 carry), UC8 (4.7.3 step 6, 4.7.6 Q2 — but interactive composition UI still applies to the golden-record selection step, which is a different UI from the downstream-impact list).

6.0.6 Rollback-by-operation-ID affordance — RATIFIED

Decision: Full per-op rollback with prior-version restore. Every sweep (UC3), merge (UC8), and taxonomy-update (UC9) commits under a shared op ID; per-record prior values stored; one-click rollback restores all touched records to their pre-op state. Post-op edits on touched records are flagged for user resolution (rollback prompts admin per record). Admin permission required to invoke rollback (per §6.0.4 admin-only gating for UC3/UC8/UC9).

Rationale: sweep/merge/taxonomy operations are high-blast-radius; one-click reversibility is what makes them safe to attempt. Per-record prior-value storage is the audit trail cost we pay for the safety.

Implementation notes:

Op ID = UUID generated at sweep/merge/taxonomy-update start.
Per-record provenance entry references the op ID.
Prior values stored either in content_history (UC3/UC8 record state) or in a dedicated taxonomy_versions table (UC9).
Mempalace Shape A KG records the op as a single event linked to N per-record edges.

Carry-forward to: UC3 (4.5.3 step 10, 4.5.5 final row), UC8 (4.7.3 step 10), UC9 (4.8.3 step 8, 4.8.5 final row).

6.0.7 AI-suggest fatigue mitigation — RATIFIED

Decision: Threshold tuning + rejection memory + daily cap. Three-layer mitigation:

Per-workspace tunable confidence threshold — suggestions below threshold are hidden by default; threshold lives in workspace settings.
Rejection memory — when user rejects a suggestion, the system stores the (suggestion-signature, user, ts, intent) tuple; identical candidates do not re-surface for that user. Periodic admin review of rejection memory ensures it doesn’t accumulate stale entries.
Daily-per-user suggestion cap — hard upper bound on AI-suggest surface counts per user per day; excess suggestions queue but don’t notify.

Rationale: compound mitigation handles different failure modes (noisy day → cap; persistent false-positive → rejection memory; corpus-wide signal quality → threshold). Rate limit alone is too coarse; rejection memory alone misses noisy days; threshold tuning alone misses repeated false-positives.

Carry-forward to: UC4 (4.2.5 final row), UC5 (4.6.5 row 7, 4.6.6 Q1), UC6 (4.3.5 final row), UC8 (4.7.5 row 5, 4.7.6 Q12).

6.1 UC1 — Typo fix — RATIFIED

Implementation: Candidate A — in-platform editor + filesystem write.

KH UI captures the edit via existing Tiptap ContentEditor with Yjs collab plugin enabled.
KH server writes DB row (content_items.content + content_history via auto-version trigger).
KH server writes file at source_documents.original_path (markdown) or sidecar .md (binary source per §6.1.1).
Cocoindex source binding observes file change on next scan; idempotency confirmed by S9 spike skipping flow re-run when content-hash matches KH’s just-written hash.
Yjs collab plugin handles concurrent-user CRDT at the editor layer; post-CRDT-merge last-write-wins at the file layer.

Rationale: atomic single-record edits cannot economically justify Candidate B’s per-edit API cost or Candidate C’s orchestration overhead. Candidate A leverages existing Tiptap infrastructure (S198 ship); marginal new work is the Yjs plugin enable on non-Q&A editors (~1 day per §9.8) + the filesystem write per connector.

6.1.1 Residual decisions

#	Question	Resolution
4.1.Q1	Candidate A vs B vs C	A (this §6.1).
4.1.Q2	Transactional guarantee DB ↔ file	Best-effort + retry queue. KH writes DB first, then file; if file write fails, retry queue + admin alert. If DB succeeds + file fails persistently, cocoindex’s next scan eventually drives reconciliation (eventual consistency window ≈ one scan cycle). Two-phase commit deferred as over-engineering for v1.
4.1.Q3	Cocoindex idempotency on equal-hash	GATES ON S9 spike result. If engine skips → clean; if not → KH writes a brief marker-file or marks the row dirty=true for one scan cycle. Spike S9 outputs the workaround if needed.
4.1.Q4	Yjs persistence (`y-supabase` adapter)	Defer to v1.1. v1 ships Yjs collab without DB persistence; awareness state lives in-memory + browser; recovery handled by Tiptap’s local-storage fallback. v1.1 evaluates `y-supabase` once collab usage patterns clear.
4.1.Q5	Permission mapping for `editor` on `published` content	Per §6.0.4 carry-forward — `editor` permitted on `draft` + `in_review`; `admin` required to edit `published` directly (typo fix on published content is rare; usually triggers UC6 revision flow with version-on-cite).
4.1.Q6	Binary source — sidecar policy auto-vs-prompted	Prompted on first edit; silent thereafter per record. First in-platform edit on a binary-sourced record surfaces a one-time “this binary source will use a sidecar markdown file for edits — OK?” prompt; once accepted, subsequent edits are silent. Per-record dismissal state persists.

6.2 UC2 — Date / version-number bump — RATIFIED (collapses to UC1)

Implementation: inherits UC1 Candidate A per S228 §3.2 de-scope ratification. Expiry-dates are handled by Q1.8 extractDates flow (separate concern). Residual atomic date-bump cases edit a single record via the UC1 path.

No distinct §6.2 residual decisions.

6.3 UC3 — Sweeping rename — RATIFIED (two-variant split)

Implementation: two variants under one sweep surface.

Find-replace variant — Candidate A. KH server iterates affected files; writes each under a shared sweep ID; per-record provenance entry references sweep ID; rollback affordance per §6.0.6. No LLM cost.
Smart-agent variant — Candidate B. KH server invokes Anthropic API with text-editor-tool; tool generates per-match candidates with surrounding-context reasoning + confidence scores; user reviews + approves per-match before commit; approved matches commit under the same sweep ID as find-replace. LLM cost is justified by the NLP value-add.

Shared UI surface: one sweep workflow with variant chooser at trigger. Both variants share the affected-record list (§6.0.5 count + paginated), the per-match preview, the cited-content overlap surface, the intent-vocabulary capture (§6.0.1), the per-record concurrency model, and the rollback affordance (§6.0.6).

6.3.1 Residual decisions

#	Question	Resolution
4.5.Q1	Sweep scope (workspace / cross-workspace / platform-global)	Workspace-only in v1. Cross-workspace deferred; platform-global never v1. Scope confirmation surfaced at sweep start; default is current workspace.
4.5.Q2	Preview-before-commit (full vs representative-sample)	Full preview for ≤50 matches; representative-sample (default 20) + optional full-load for larger. Threshold tunable per workspace.
4.5.Q3	Per-record concurrency model	Optimistic with conflict-skip-and-report. Sweep does not lock records; per-record concurrency check at write time; if external edit detected, skip that record + log in the Change Report for follow-up. Yjs collab on records being swept: sweep waits for active collab session to end (10s timeout) before commit; if timeout, skips + reports.
4.5.Q4	Sweep transactionality	Partial-progress with resume. Sweep retains per-record state (committed / pending / skipped); can pause + resume mid-flight; failure on a record reports it + continues; rollback (§6.0.6) reverses all committed records under the op ID.
4.5.Q5	Intent vocabulary	Per §6.0.1 carry-forward — closed list: brand-rename / policy-reference / regulatory-update / clarity-pass / dedup-driven / other-with-note.
4.5.Q6	Smart-agent confidence threshold	Default 0.85; tunable per workspace. Matches below threshold hidden by default; user can toggle “show low-confidence”.
4.5.Q7	Admin gating	Per §6.0.4 carry-forward — admin-only for both variants.
4.5.Q8	Cited-content default	Leave untouched + flag for review. Default is conservative (no silent mutation); user explicitly opts in per-match to revise cited content.
4.5.Q9	Sweep on archived records	Excluded by default. User can opt to include via “advanced scope” flag (admin warning shown).
4.5.Q10	Sweep + UC4 per-paragraph classification interaction	Sweep ID supersedes per-paragraph classification. A swept paragraph inherits sweep-level intent (e.g. brand-rename) rather than UC4’s source-classification flow. Tension acknowledged; sweep is a bulk-administrative operation, not a per-paragraph editorial choice.

6.4 UC4 — Paragraph rewrite (cited content) — RATIFIED

Implementation: Candidate A.

Edit happens in-platform via Tiptap + Yjs (existing Q&A ContentEditor for Q&A-backed paragraphs; new Tiptap mount for other content shapes).
Source classification surfaced inline at the paragraph level (approved Q&A / draft Q&A / MCP-derived / generated).
Edit-intent gate at save time per §4.2.3 step 6 with options derived from classification:
- Approved Q&A: revise the Q&A (triggers UC6 flow) / edit locally only / capture variation as new Q&A (triggers UC5 flow).
- Draft Q&A: revise draft (in-place) / edit locally only / capture variation.
- MCP-derived: edit locally + (optionally) promote-as-Q&A.
- Generated: edit freely.
Citation re-anchor per §6.0.2 hybrid policy.
Downstream-impact preview per §6.0.5.

Rationale: UC4 is fundamentally human-driven paragraph editing within an artefact context (a bid response). Per-edit Claude API cost is not justified for the typical paragraph rewrite; the LLM’s value-add is concentrated in the AI-suggest flow for UC6 revision (Candidate B per §6.6).

6.4.1 Residual decisions

#	Question	Resolution
4.2.Q1	Edit-policy per source classification	Per the four-class set above (approved Q&A / draft Q&A / MCP-derived / generated).
4.2.Q2	Downstream-impact surface UI	Per §6.0.5 carry-forward — count + paginated list.
4.2.Q3	Intent-at-edit-vs-save-time	At save time per §6.0.1 carry-forward — user reviews classification at paragraph open; gate triggers at commit with intent chooser.
4.2.Q4	Anthropic citations re-anchor shape	Per §6.0.2 carry-forward — hybrid (re-anchor if verbatim, else mark-as-paraphrased).
4.2.Q5	Promote-to-Q&A capture	Prompt user at gate; not silent + not background. Promote-as-Q&A option appears in the edit-intent chooser for MCP-derived paragraphs; user opts in explicitly. AI-suggest is the separate background pathway (UC6 4.3 trigger b).
4.2.Q6	”Edit locally only” semantics	Override-this-instance. Edit applies to the paragraph within the artefact; source Q&A unaffected; provenance records the local-only intent. No fork of the source.
4.2.Q7	Citation immutability mode	Per §6.0.3 reaffirm — version-on-cite at ship time.

6.5 UC5 — Bid response → Q&A promotion — RATIFIED (KH-DB-only; no candidate)

Implementation: KH-DB-only operation. Promotion creates a new q_a_pair (draft state) with lineage to source bid response + bid question; originating bid response unchanged; approval workflow per publish_status lifecycle (per §6.0.4).

No Candidate A/B/C applies — UC5 is not a write-back operation. If/when an approved Q&A pair is materialised to a markdown sidecar in the folder (per 4.6.6 Q7 — deferred to v1.1), the sidecar write follows UC1’s Candidate A pattern.

6.5.1 Residual decisions

#	Question	Resolution
4.6.Q1	Auto-promote vs always-prompt	Always user-initiated in v1. AI surfaces candidates as suggestions (per §6.0.7 fatigue mitigation); never commits without user click.
4.6.Q2	Approval workflow	Draft → in_review (curator review queue) → published. Per `publish_status` lifecycle. Workspace-level policy permits “auto-publish if actor is curator-or-admin” as opt-in setting.
4.6.Q3	Intent vocabulary	Per §6.0.1 carry-forward — closed list: novel-question / refined-existing / regulatory-driven / client-specific / dedup-from-variations / other-with-note.
4.6.Q4	Review queue ownership	Workspace-level curator role. Defaults to workspace admin if no dedicated curator role configured.
4.6.Q5	Pre-promotion quality gates	Soft checklist + reviewer-judgement. Platform displays a quality checklist (scope tagged / answer self-contained / question phrasing canonical / lineage present) but does not block submission; reviewer applies judgement. Gate-as-blocker rejected.
4.6.Q6	Scope tag handling	User picks at promotion + (optional) AI-suggest. Default is “this workspace only”; user picks scope tags from UC9 vocabulary; AI-suggest may propose tags based on inferred classification (per §6.0.7 fatigue rules apply).
4.6.Q7	Markdown sidecar on promotion	Defer to v1.1. v1 keeps approved Q&A pairs KH-DB-only; sidecar materialisation evaluated once external-folder write-back patterns are mature (UC1 + UC4 + UC6 ship first).
4.6.Q8	KBIntegrationReview integration	Same surface as broader bid integration review. Promotion review queue is one tab within the existing review surface (per Q3.8 PENDING-ARCH integration).
4.6.Q9	Duplicate-detection threshold at promotion	Default cosine-similarity 0.85; tunable per workspace. Above threshold: surface as “close match” with merge/supersede/proceed options. Threshold lower than UC8 cross-record dedup (more aggressive surfacing at promotion is desirable — better to over-prompt than create near-duplicate).
4.6.Q10	Promotion source-classification carry-through	Yes — new Q&A draft inherits confidence label from UC4 source classification. Approved-Q&A-variation → “user-refined”; draft-Q&A-variation → “user-refined-from-draft”; MCP-derived → “captured-from-MCP-generation”; manually-authored → “manually-authored”. Labels surface in review queue for reviewer context.

6.6 UC6 — Q&A pair revision — RATIFIED (split: user-direct + AI-suggest)

Implementation:

User-direct revision — KH-DB-only operation (no candidate). User opens Q&A pair in existing Tiptap + Yjs editor; edits question/answer; states intent (§6.0.1); chooses in-flight citer policy (§6.6.1 carry); commits with mempalace Shape A temporal columns recording the version transition.
AI-suggest revision — Candidate B. KH server detects source-doc change via cocoindex source-binding event; invokes Anthropic API to propose a draft revision (with the source-doc delta as context); user reviews + edits the draft + commits via the same user-direct flow above. Hybrid: B for proposal, A for human refinement step.

Rationale: the proposal step is exactly Candidate B’s strength (NLP context-aware draft generation); the refinement + commit step belongs in the user’s hands with provenance + classification. Avoids Managed Agent (Candidate C) overhead while preserving the AI value-add.

6.6.1 Residual decisions

#	Question	Resolution
4.3.Q1	Source-doc change detection criteria	Material-change threshold. Any structural edit to a paragraph that’s the source for a cited Q&A triggers AI-suggest review. Cosmetic changes (whitespace / punctuation only) suppressed. Threshold tunable per workspace per §6.0.7 fatigue mitigation.
4.3.Q2	In-flight citer policy default	Keep-at-prior (default) + opt-in prompt-each. Safer default; user opts in explicitly to “update in-flight bids” or “prompt me per bid” per revision.
4.3.Q3	Dedup-merge revision (UC8 trigger)	Uses UC6 flow with system-as-actor. Merge-driven Q&A revisions go through the UC6 flow; actor is “system (sweep ID)”; intent is “dedup-merge”; user reviews the merged result in the queue.
4.3.Q4	Intent vocabulary	Per §6.0.1 carry-forward — closed list: typo / factual-update / regulatory-change / source-doc-driven / dedup-merge / promotion-from-bid-variation / clarification / other-with-note.
4.3.Q5	Q&A lifecycle interaction with `publish_status`	Revising a `published` Q&A moves to `in_review` automatically. Per `publication-lifecycle-state-machine-spec.md` — published content edits require approval before re-publication. v1 enforces this transition; admin override available.
4.3.Q6	Multi-Q&A revision atomicity	Yes — shared op ID supports multi-Q&A transactional revision. Per §6.0.6 rollback. Useful for regulatory updates touching many Q&A pairs; rollback reverses the whole op.
4.3.Q7	Q&A backed by markdown sidecar	Defer to v1.1. Same as 4.6.Q7 — sidecar materialisation patterns evaluated post-UC1/UC4/UC6 user-direct ship.
4.3.Q8	AI-suggest revision composition shape	Proposal as draft requiring user approval. Candidate B (KH → Anthropic API) generates a Q&A revision draft; user reviews + edits + commits. Draft never auto-writes the new version; always user-mediated.

6.7 UC7 + UC10 — External folder change detected — RATIFIED (cocoindex native; no candidate)

Implementation: cocoindex source binding (PRIMARY per §10). No Candidate A/B/C applies — system-driven.

Conflict-resolution UI for transactional-window collisions (in-platform edit + concurrent external edit on the same record) is the only user-facing surface. Uses git-style merge prompt (per §1.5 strategies); detail in §4.4.6 Q4 carry-forward.

6.7.1 Residual decisions

#	Question	Resolution
4.4.Q1	Polling cadence + webhook per connector	GATES ON S2 spike result. LocalFS via fs-watch (real-time); SharePoint via webhook (push); Notion + Google Drive + Dropbox + Box per S2 spike’s connector inventory. Default polling fallback 5min where no webhook available.
4.4.Q2	Rename detection precision	Content-hash equality within a 60-second window. Content-hash + path-disappearance within 60s of new path appearing with same hash → classify as rename. Tunable per workspace. Identical-content unrelated files: cocoindex flags + surfaces for admin review (rare but real).
4.4.Q3	Delete handling policy	Auto-archive with 7-day grace + admin override. Deleted records soft-archived for 7 days (recoverable); after 7 days, archived permanently but still queryable. Q&A pairs sourced from deleted docs flagged “stale-source” for review (not auto-archived). Bulk-delete (>10 records in single op) requires admin confirmation.
4.4.Q4	External-edit-during-platform-edit reconciliation	Git-style merge UI surfacing both diffs. User sees “platform diff” + “external diff” + a “merged proposal”; user picks keep-platform / keep-external / accept-merged / cancel-both-for-review. Per §1.5 git-style strategy.
4.4.Q5	Q&A review queue UX	Bulk-summary with batch-action + per-pair drill-in. Default view groups affected Q&A pairs by source-doc change; user batch-approves “all impacted by source X” or drills into individuals. Threshold for “material change” per 4.3.Q1 (UC6).
4.4.Q6	Audit retention for deleted files	Indefinite at platform level. Archived records remain queryable; tenant policy may override (post-launch feature).
4.4.Q7	Binary-replace sidecar update	Automatic regeneration + warn-on-quality-variation. Sidecar regenerated automatically; if new extraction’s quality score deviates >20% from prior, user notified (“extraction quality changed — review?“).
4.4.Q8	Cross-record dedup at ingest	NO — defer to UC8 substrate. “Add” classification does not invoke cross-record dedup at ingest time; UC8 substrate (S10 spike) handles post-ingest detection. Avoids two competing dedup logics.
4.4.Q9	Bulk-change throttling	Batch within 10s window + admin notification. Multiple webhook notifications within 10s coalesce into one batch; >50 changes in batch surface admin notification before processing.

6.8 UC8 — AI-suggested dedup merge — RATIFIED (v1 Candidate A + LLM-reasoning; v1.1 upgrade to C)

Implementation:

v1: Candidate A — KH server orchestrates the merge directly. Claude API used only for per-pair similarity reasoning (“these two records both describe the same Bitdefender deployment but differ on date”) at the propose-merge step. No Managed Agent dependency.
v1.1+: evaluate Candidate C upgrade once UC8 usage patterns clear. Migration path: documentation-agent replaces KH server orchestration; Claude API LLM-reasoning step folds into the agent’s tooling.

Substrate (cross-record detection): GATES ON S10 spike result. Cocoindex post-target-write @coco.fn / mempalace KG entity-resolution / hybrid — chosen substrate becomes UC8 PRIMARY substrate.

6.8.1 Residual decisions

#	Question	Resolution
4.7.Q1	Primary detection signal	GATES ON S10 spike. Substrate winner becomes primary; others become inspiration.
4.7.Q2	Proposal UX	Side-by-side diff + interactive composition. User can pick one candidate as-is OR assemble a survivor from multiple via the existing Tiptap collab editor surface. Unique-content warnings (§4.7.3 step 5) enforced.
4.7.Q3	Golden-record selection default	AI-recommended-with-edit. System proposes a starting point (most-cited or newest depending on signal); user adjusts. Never blindly auto-newest-wins.
4.7.Q4	Citation preservation policy	Per §6.0.2 carry-forward — hybrid: re-anchor to golden where text matches, else mark-as-paraphrased with archived-snapshot pointer. Per-citation explicit.
4.7.Q5	Intent vocabulary	Per §6.0.1 carry-forward — closed list: duplicate-versions / draft-and-final / overlap-with-distinct-shapes / hash-collision / admin-cleanup / other-with-note.
4.7.Q6	Bulk-merge throttling	Batch-grouped review. Detected candidate pairs group by similarity-pattern (e.g. “these 12 DRAFT-vs-final pairs”); user batch-approves within pattern; per-pair drill-in available. Hard cap 50 active proposals per curator queue.
4.7.Q7	Auto-merge threshold	None in v1. All merges require user review. Byte-identical files with different paths are still surfaced (rare but worth confirming). Auto-merge revisited post-v1.1 once curator UX validated.
4.7.Q8	Cross-workspace merge	Never v1. Workspace-scoped; cross-workspace requires elevated permission if ever enabled.
4.7.Q9	Derived Q&A pair handling on merge	Auto-update Q&A source-doc references + queue for UC6 review if non-trivial. Per §4.7.3 step 8. “Non-trivial” = derived Q&A pair’s source-paragraph no longer exists verbatim in golden; UC6 review queue entry created.
4.7.Q10	Folder-state side effects on merge	Golden record’s source file kept; merged-away source files moved to `_archived/` subfolder. Renames preserve identity in cocoindex’s logical-doc-id model. Per §6.1 Candidate A pattern for the file moves.
4.7.Q11	DRAFT-vs-final pattern coverage	Explicit pattern detector + generic high-similarity catch. Filename-prefix heuristic (`DRAFT-` / `_DRAFT.*`) plus content-overlap detection. Per S188 user requirement; exercise on `docs/client-documentation-base/binary/` DRAFT fixtures during S10 spike.
4.7.Q12	Reject-learning memory	Per-workspace; persists indefinitely with admin review. Per §6.0.7 fatigue rejection-memory rules apply.

6.9 UC9 — Scope-tag taxonomy update — RATIFIED (KH-native; no candidate)

Implementation: KH-native typed-column work-package per skill-seekers-eval §2.4 verdict + Q1.7 RESOLVED. New OPS-X-SCOPE-TAGS work-package, ~1-2 weeks per skill-seekers-eval §2.4 (CX.16 PROVISIONAL ~7-9d total).

No Candidate A/B/C applies — workspace-metadata operation; no folder write-back; no LLM-driven edit.

6.9.1 Residual decisions

#	Question	Resolution
4.8.Q1	Taxonomy definition UX	DB-backed with admin UI. Per CX.16 PROVISIONAL ~7-9d cost. CRUD interface for tags + keyword/anti-keyword hints + per-tag usage count.
4.8.Q2	Rollout strategy default + permitted set	Default: re-classify ambiguous only. Permitted: all four (re-classify everything / ambiguous only / forward-only / bulk-prompt-admin). Default chosen to balance currency against admin load.
4.8.Q3	Conflict-surfacing UX	Pattern-grouped review with batch actions. Records grouped by conflict pattern (multi-tag matches sharing same tag set; keyword/anti-keyword collisions); admin batch-resolves per pattern. Per-record drill-in available.
4.8.Q4	Intent vocabulary	Per §6.0.1 carry-forward — closed list: new-domain / domain-split / domain-merge / vocabulary-cleanup / regulatory-driven / client-feedback-driven / other-with-note.
4.8.Q5	Q&A scope-tag inheritance on source-doc taxonomy change	Queue derived Q&A pairs for UC6 review (AI-suggest trigger). Not auto-propagate; not silent. Per §6.0.7 fatigue rules.
4.8.Q6	Anti-tag UX	Separate field on each scope-tag definition + dedicated `anti_scope_tag` array on each record. Per Q1.7 RESOLVED (multi-value array). Admin surface shows positive + negative hints side-by-side per tag.
4.8.Q7	Per-tenant vocabulary vs seed	Sector-template seed with per-tenant override. Workspace setup offers sector templates (MSP / professional services / etc.) as starting point; admin edits freely from there. Phew’s vocabulary becomes the MSP-sector template seed.
4.8.Q8	MCP search-filter expressiveness	Array-of-tags + boolean expression (AND / OR / NOT). Per CX.27 RESOLVED `scope_filter` parameter; expressiveness extends to boolean expressions. Anti-tag enforcement is always filter-time exclusion regardless of caller’s expression.
4.8.Q9	Classifier integration	Hybrid: keyword-rule scan tier + AI classification tier. Keyword-rule tier runs first (cheap, deterministic); AI classification fills the gaps + handles ambiguous cases. Per skill-seekers-eval §2.9 proposed pattern.
4.8.Q10	Taxonomy versioning + rollback	Workspace-level taxonomy version with per-tag granularity. Each commit creates a new taxonomy version; per-tag changes within the commit retain prior values; per §6.0.6 rollback affordance applies. Retention indefinite.
4.8.Q11	Admin gating	Per §6.0.4 carry-forward — workspace admin only.
4.8.Q12	Stale-cache window post-commit	Synchronous invalidation on commit. No eventually-consistent window; MCP search reflects new taxonomy immediately. Cache-key includes taxonomy version as belt-and-braces.
4.8.Q13	Tag deletion / retirement semantics	Soft-archive with split-and-replace prompt. Admin attempting to retire a tag with active records gets a “split-and-replace” prompt (retag affected records before retirement) or “soft-archive” option (records keep the tag but it doesn’t surface in admin UI). Hard-delete forbidden if any record carries the tag.

6.10 Decisions → architecture-rewrite + spike-plan mapping

Maps into `0.9-decision-graph.md`:

Q2.9 IMPLEMENTATION → RESOLVED with per-UC implementation set: UC1/UC2/UC4 Candidate A; UC3 two-variant (A+B); UC6 user-direct KH-DB-only + AI-suggest Candidate B; UC8 v1 Candidate A + LLM-reasoning, v1.1 Candidate C upgrade.
Q1.15 (source-doc → content edit → re-upload provenance) → RESOLVED via UC1/UC4/UC6/UC7+10 flows + cocoindex source-key + mempalace Shape A + content_history.
Q5.10 (OPS-X-CLASSIFY-UI re-ingest for already-edited content) → RESOLVED via UC10 conflict-resolution flow (§6.7.1 Q4) + UC4 source classification + UC6 AI-suggest revision.

Maps into `0.9-intended-architecture.md` (sub-agent B rewrite scope):

§2.3 / §5.1 / §5.2 — flip HYBRID write-back to “Candidate A primary for human-driven UCs; Candidate B for AI-driven UCs; Candidate C deferred to v1.1 (UC8 upgrade)”. Reference §6.1-§6.9 of this doc.
§10.1 / §10.2 — re-frame agent-browser swap as Playwright-not-Firecrawl (OQ6).
§16 — replace OQ1+OQ3 baked-in provisionals with ratified text (§6.0 + §6.1-§6.9); add OQ4-OQ9 ratifications from 0.9-context.md §2.
§6.2 / §6.3 — caveat that wave-08 D14 / D19 were TBD not ratified.
§11.2 — resolve “8 features → MCP” header vs 5-bullet list discrepancy (V2 finding).
Throughout — weave graphify-feedback context per 0.9-context.md §3.

Maps into `0.9-spike-plan.md` (updates needed):

S9 write-back semantics validation — concrete success criteria refined: Candidate A in-platform + filesystem write end-to-end on docs/client-documentation-base/markdown/; cocoindex idempotency confirmation; Yjs collab plugin enable; sidecar pattern for binary. Decision gate aligned: pass → v1 UC1 ships Candidate A; fail-on-idempotency → marker-file workaround or escalate.
S10 cross-record dedup substrate — concrete success criteria refined: UC8 v1 substrate decision (cocoindex / mempalace / hybrid). Output feeds §6.8 substrate slot.
NEW (optional) S14 Anthropic citations re-anchor primitives — Claude API behaviour study confirming §6.0.2 hybrid policy implementation. Half-day foreground; gates UC4 + UC6 citation re-anchor work.

End of §6. All decisions RATIFIED S229. Per-UC implementation set + cross-UC consolidated decisions captured. Hand-off to sub-agent B (architecture rewrite) + spike phase dispatch.

7. Open principles (locked unless flipped)

One golden record — Wikipedia principle. Source file (or KH-derived golden record where the file is binary-RO) is the single truth.
Two-way semantics — edits propagate both ways where possible.
Lineage — every edit attributable, timestamped, rollbackable.
AI-consumer-first — implementation must work cleanly when Claude edits via MCP / tool use, not just when users edit via web UI.
External folder canonical — per Q2.1 ratified.
No reinvention — adopt + customise per ai-strategy North Star (see 0.9-context.md §1).

8. Risks / unknowns

SharePoint / Notion / Google Drive write-back APIs — vary in capability. Bulk + transactional writes may be unsupported. (Spike S2 partly covers.)
Binary regeneration fidelity — markdown → docx via pandoc loses formatting nuances. Practical for v1?
Citation-immutability vs edit freedom — fundamental tension. Strict freeze blocks UC6; loose lets edits silently invalidate shipped bids.
Cost of Candidate B (Claude API per edit) — atomic typo fixes via API are wasteful; sweeping ops via API are cost-justified. Threshold needed.
Conflict-resolution UX — UC4 + UC7 + UC8 + UC10 all need clear policies before implementation. None defined yet.

9. Existing KH infrastructure — what to RETIRE vs reuse

S228 reframe per Liam: the 11 ingestion pathways are a historical artifact. Canonical pipeline’s purpose is to REDUCE complexity by adopting third-party tooling that already covers most of this. Don’t fall into “extend the existing infrastructure” trap — built-not-wired primitives have NO claim on the new architecture if cocoindex / mempalace / skill-seekers / pullmd cover the same primitive better. 70+ columns in content_items are exactly the kind of historical accretion that needs to shrink.

This section now lists existing KH primitives with the verdict: retire / reuse / conditional.

9.1 `source_documents` table — re-upload primitives

Primitive	Existing	Cocoindex equivalent	Verdict
`version` auto-increment for re-uploads	YES	Cocoindex ops-DB ledger tracks every flow run with code-hash + content-hash	RETIRE — cocoindex’s per-run ledger is stronger provenance than a column int
`parent_id` chain	YES	Cocoindex source-key + content-hash UPSERT; logical-doc-id is the chain primitive	RETIRE — chain becomes implicit in the source-key history
`filename` per-user re-upload detection	YES	Cocoindex source-key (NOT filename-keyed)	RETIRE — filename-keying is exactly the bug the user flagged at 07-synthesis-feedback L87 (per cocoindex-eval Appendix §9.1 trace). Logical-doc-id solves this.
`original_filename` intended-but-unused rename detection	Built-not-wired	Cocoindex source-key independent of filename	RETIRE — this entire primitive exists only because filename-keying was broken

9.2 Detection states — `'identical'` / `'new_version'` / dedup

Primitive	Existing	Cocoindex / skill-seekers / mempalace equivalent	Verdict
`'identical'` warning (same filename+user+MD5)	YES	Cocoindex source-binding sees same content-hash → ignores (Δ semantics)	RETIRE — engine handles natively
`'new_version'` INSERT path	YES	Cocoindex source-key + content-hash → UPSERT existing row	RETIRE — engine handles natively, NO new content_items orphan rows
Content-hash dedup at upload	PROD	Cocoindex content-hash native; post-ingest cross-record dedup via mempalace KG entity-resolution OR skill-seekers metadata	RETIRE upload-time path + NEW — design cross-record post-ingest dedup (UC8)

9.3 `source_document_diffs` table

ACTIVE-EMPTY — built for old re-upload-creates-new-content_items model. RETIRE. Cocoindex ops-DB ledger gives per-row “what input + code-hash → what output” for every flow run — stronger provenance for free.

9.4 Re-upload notifications

sendSourceDocumentUpdateNotifications + admin fallback. REUSE conditional — notification surface is independent of pipeline; reusable but the source-events feeding it change shape (cocoindex flow events not P7 RPC events).

9.5 S188 user-feedback-from-re-ingestion required UI behaviours

3 captured at S188 (docs/audits/user-feedback-from-re-ingestion.md):

Track Changes detection on .docx upload — has_tracked_changes() exists at scripts/docx_utils.py → REUSE as cocoindex @coco.fn in docx-shape adapter.
Duplicate detection at upload — partly covered by cocoindex content-hash; cross-record dedup gap remains (UC8).
Draft-vs-final detection — content overlap detection. NEW WORK — neither cocoindex nor skill-seekers covers natively. Spike S2 with docs/client-documentation-base/binary/ DRAFT files exercises this; verdict drives design.

9.6 EP8 spec status (OQ7)

EP8 spec at docs/specs/ep2-ep8-chunk-at-ingest-spec.md (v5).
Authored S189 before key dependencies shipped: P0-BM Phase 3 extractors landed S194; Q&A ContentEditor landed S198 (components/qa/qa-answer-display.tsx mounts Tiptap-markdown ContentEditor); S205-S207 widened ingest schema.
~60% of EP8 lib/ work already shipped. Q&A ContentEditor SUPERSEDES EP8 downstream framing.
Remaining genuinely-unbuilt: UI surface, routes, Storage bucket, run-post-insert TS port.
OQ7 confirmed: EP8 needs partial rewrite to reflect post-S198 reality + edit-flow investigation outcomes.

9.7 Cocoindex Appendix §9.1 — full data-flow trace for UC7/UC10/Q1.15

docs/plans/phase-0-investigation/0.8.2-cocoindex-evaluation.md §9.1 traces the user’s 07-synthesis-feedback L87 question end-to-end under cocoindex Option A. Key result:

KH API generates a logical document key K at upload (UI affordance: dropdown “this is a new version of: [existing document]”).
Cocoindex source binding sees new row keyed by K → runs binary-shape adapter → UPSERTs content_items keyed by K.
Re-upload (policy-v2.docx, different filename, same K) → engine sees same key + new content-hash → re-runs flow → UPDATES same content_items row → content_history v3 via DB trigger.
The hard part: UI must capture “this is the new version of K” at upload — engine doesn’t infer logical identity from content alone.

This trace is the reference data-flow for UC7 + UC10 + Q1.15. Read it before §4 of this doc.

9.8 Tiptap + Yjs — already in toolchain

KH uses Tiptap for the Q&A ContentEditor (S198 ship). Tiptap supports Yjs collab plugin natively. REUSE — concurrent-user CRDT conflict resolution (UC1 / UC4 / UC6 in-platform-edit) is one plugin enable away. Architectural unlock with near-zero infrastructure cost.

9.9 Implications for the edit-flow investigation (revised)

UC1 / UC2 / UC4 in-platform edits — Tiptap+Yjs CRDT covers concurrent-user. Write-back to external folder (the actual UC challenge) is NEW design, choice of (A) in-platform editor + filesystem write / (B) Claude API text-editor-tool / (C) Managed Agents.
UC3 sweeping rename — find-replace UI = bespoke (likely @coco.fn over markdown corpus); smart-agent variant = Claude API tool use (sweep-and-edit pattern fits text-editor-tool well).
UC5 bid response → Q&A — KH-DB-only; no folder write-back. Provenance via mempalace Shape A temporal columns + content_history.
UC6 Q&A revision — version-on-cite = mempalace Shape A valid_from/valid_to directly. Citers: query mempalace KG for “what cited this Q&A pair, valid_to >= ship_date” to surface affected bids.
UC7 binary re-upload — collapses into UC10 + transactional-window. Cocoindex’s logical-doc-id model resolves the “different filename” case (Appendix §9.1).
UC8 AI-dedup merge — NEW design at cross-record level. Candidates: cocoindex post-target-write dedup @coco.fn / mempalace KG entity-resolution / skill-seekers metadata.
UC9 scope-tag taxonomy — KH-native typed-column work-package (OPS-X-SCOPE-TAGS, ~1-2 weeks per skill-seekers-eval §2.4 verdict). Anti-tags + conflict-surfacing + per-tenant taxonomy not covered by skill-seekers.
UC10 external-folder edit — cocoindex source-binding native. Polling frequency TBD architecture phase.

Net retirement candidates: source_documents.version, source_documents.parent_id, source_documents.original_filename, source_document_diffs, P7 detect_reupload RPC, 'identical' / 'new_version' upload-state paths. Estimated ~500-800 LOC retired (precise count via spike S1).

Net new work: Tiptap-Yjs collab enable (~1 day), cross-record dedup design (UC8, ~1 week), draft-vs-final detection (UC8 + binary-corpus, ~1 week), scope-tag KH-native work-package (UC9, ~1-2 weeks), edit-flow implementation per chosen candidate A/B/C (TBD §5 per UC).

10. UC × tooling capability matrix (S228)

Cross-reference of UCs against third-party tooling per their evaluations. Cells: PRIMARY (tool is the chosen substrate) / SUPPORTING (tool contributes a sub-capability) / NO (not a fit) / TBD (needs spike).

UC	Cocoindex (Option A)	Mempalace	Skill-seekers	pullmd	Tiptap+Yjs	Claude API tool use	Anthropic citations
UC1 typo fix	SUPPORTING — sees the resulting file change via source-binding	NO	NO	NO	PRIMARY for concurrent-user (in-platform)	SUPPORTING for write-back-to-folder	NO
UC2 date bump (de-scoped)	SUPPORTING	NO	NO	NO	SUPPORTING	NO	NO
UC3 sweeping rename	SUPPORTING — re-runs flow on every changed file	SUPPORTING — Shape A KG event for sweep-as-operation, links to per-record edits	NO	NO	NO	PRIMARY for smart-agent variant (text-editor-tool)	NO
UC4 paragraph rewrite (cited)	SUPPORTING	SUPPORTING — Shape B verbatim chunks	NO	NO	PRIMARY in-platform	SUPPORTING for folder write-back	PRIMARY for citation immutability
UC5 bid → Q&A promotion	NO — KH-DB only	PRIMARY for Shape A provenance + lineage	NO	NO	SUPPORTING (Q&A ContentEditor)	NO	SUPPORTING
UC6 Q&A revision	NO — KH-DB only	PRIMARY for Shape A version-on-cite + temporal queries	NO	NO	SUPPORTING (Q&A editor)	NO	PRIMARY for shipped bid citations
UC7 binary re-upload	PRIMARY — Appendix §9.1 trace	SUPPORTING — temporal events on UPDATE	NO	NO	NO	NO	NO
UC8 AI-dedup merge	PRIMARY for content-hash + cross-record post-ingest `@coco.fn`	PRIMARY for KG entity-resolution	SUPPORTING — metadata categorisation as inspiration	NO	SUPPORTING — interactive golden-record composition uses existing collab editor surface	SUPPORTING — propose-merge UI	NO
UC9 scope-tag taxonomy	NO	NO — taxonomy is workspace-scope; out of mempalace scope	NO — `categories` keyword pattern wrong shape (per §2.4 verdict)	NO	NO	NO	NO
UC10 external-folder edit	PRIMARY — source-binding native	SUPPORTING — temporal events on UPDATE	NO	SUPPORTING — URL source if folder includes URL list	NO	NO	NO

10.1 Where third-party stack DOES NOT cover

Identified gaps requiring KH-native or new design:

UC4/UC6 cited-content edit policy — needs custom UI + classification taxonomy + Anthropic citations integration. Tooling supports; design is bespoke.
UC5 / UC6 Q&A schema — q_a_pairs + q_a_extractions + citations tables per 0.9-intended-architecture.md §4.3. KH-native.
UC8 cross-record dedup — neither cocoindex nor mempalace nor skill-seekers ships a turnkey “find near-duplicates across content_items + propose merge” surface. Spike to evaluate cocoindex post-target-write @coco.fn vs mempalace KG entity-resolution; design afterwards.
UC9 scope-tag — KH-native typed columns + anti-tags + conflict-surfacing per skill-seekers-eval §2.4 verdict. New OPS-X-SCOPE-TAGS work-package.
Edit-flow implementation choice (A/B/C) — design + decision needed. Tooling supports each candidate; choice is product/architecture decision.
Draft-vs-final detection — neither tool covers natively. New design.

10.2 Where multiple tools overlap (need de-duplication of effort)

UC8 dedup: cocoindex content-hash + mempalace KG entity-resolution + skill-seekers metadata all touch this. Spike-and-decide which substrate; the others become inspiration.
UC1/UC4/UC6 in-platform editing: Tiptap+Yjs (CRDT) + Claude API text-editor-tool (LLM-driven edit) overlap for concurrent-edit-with-AI-help. Likely BOTH adopted but for different surfaces (Tiptap for human direct edit; text-editor-tool for AI-suggested smart-rewrite).
UC10 external-folder change detection: cocoindex source-binding + mempalace temporal events. cocoindex PRIMARY (engine); mempalace SUPPORTING (records the event in KG for query).

11. Next step

§1-§6 + §9-§10 ratified S229. Hand-off complete; next actions:

✅ §5 tooling-fit per UC populated (§5.1-§5.10).
✅ §6 architectural decision ratified (§6.0 cross-UC + §6.1-§6.9 per-UC + §6.10 mapping).
Dispatch sub-agent B to rewrite 0.9-intended-architecture.md per §6.10 mapping (gates lifted).
Dispatch spike phase in parallel with sub-agent B per Liam S228 unlock direction. S9 + S10 success criteria refined per §6.10.
Update 0.9-decision-graph.md Q2.9 / Q1.15 / Q5.10 → RESOLVED (this session).
Update 0.9-context.md §2 OQ1 → RESOLVED-IMPLEMENTATION (this session).
Liam reviews §5 + §6 outputs.

End of edit-flow investigation. §1-§6 + §9-§10 reflect S228 + S229 Liam ratifications. Full hand-off to sub-agent B + spike phase. Round-trip with cocoindex / skill-seekers / mempalace evaluations completed S228; §6 carries forward via §6.10 mapping.