Architecture sub-doc construction guide

Architecture sub-doc construction guide

Audit date: 14/05/2026 (S238 close — WP4 Wave 1 wrap) Status: ACTIVE — discipline reference for S239+ architecture sub-doc drafting. Patterned from the S238 docs/plans/phase-0-investigation/architecture/01-vision.md pilot. Scope: WP4 architecture sub-docs only — the 9-way split of docs/plans/phase-0-investigation/0.9-intended-architecture.md (01-vision.md through 09-diagrams.md). NOT a general doc-drafting guide. Companion: docs/specs/core-docs-pathway-assessment/INV-architecture-split-readiness.md (the wave plan + readiness map this guide instantiates).

---

1. Purpose + scope

1.1 What this guide is

This guide codifies the pattern and the discipline rules established by the S238 pilot sub-doc docs/plans/phase-0-investigation/architecture/01-vision.md (242 lines, 8 sections), so that subsequent architecture sub-doc drafts — written by sub-agents in worktree isolation across multiple sessions — land consistently in section structure, citation discipline, heritage-doc handling, and gap-flagging.

The guide is paired with the readiness map in docs/specs/core-docs-pathway-assessment/INV-architecture-split-readiness.md. The readiness map answers “what is ratified, what is still open?”; this guide answers “given that, how do I draft a sub-doc that holds up across review?”.

Canonical collapse-tag vocabulary — the 7 collapse / retire / defer tags ([RATIFIED-RETIRE] / [RATIFIED-RENAME] / [RATIFIED-DO-NOT-BUILD] / [DEFERRED-v1.1] / [CONDITIONAL-RETIRE] / [LOCKSTEP-WITH-MIGRATION] / [DEFERRED-POST-LAUNCH]) live at docs/plans/phase-0-investigation/architecture/07-collapse-list.md §1.1. Sub-doc authors apply these tags by reference; the construction-guide does not duplicate the table. [DEFERRED-POST-LAUNCH] is the S243-polish addition distinguishing external-gate deferrals (mempalace v4 standalone) from KH-internal v1.1 deferrals.

1.2 When this guide applies

Apply this guide when:

• Drafting any of the 7 remaining WP4 architecture sub-docs: 02-data-flow.md, 03-tech-stack.md, 04-workspace-types.md, 05-qa-flow.md, 06-mcp-tooling.md, 07-collapse-list.md, 08-new-features.md, 09-diagrams.md.
• Re-drafting the pilot 01-vision.md after Liam-flagged content-fix passes (the same discipline applies to revisions).
• Adding new architecture sub-docs to the same split family in future waves (if Liam ratifies an extension beyond the 9).

1.3 When this guide does NOT apply

Do NOT apply this guide to:

• Tech specs, product specs, PRDs (use the write-tech-spec / write-product-spec skills instead).
• Reference docs in docs/reference/, runbooks in docs/runbooks/, design specs in docs/design/, audit reports in docs/audits/, or planning/research docs in .planning/.
• Heritage docs in docs/client-documentation/ or docs/client-documentation-base/markdown/.
• The central register itself (docs/plans/phase-0-investigation/10-feedback-investigation-findings/00-synthesis-v2.md) or the decision graph (docs/plans/phase-0-investigation/0.9-decision-graph.md) — these have their own consolidation conventions.

The guide is narrow on purpose. The discipline rules below (especially §5 no-fabrication) apply broadly; the section-structure rules in §2 apply specifically to WP4 architecture sub-docs.

---

2. The pattern (from the S238 pilot 01-vision.md)

The pilot established an 8-section structure that subsequent sub-docs adopt as a template, NOT as a hard rule. Section count and depth flex per sub-doc; section order is preserved where possible.

2.1 Section template

§	Section	Purpose	Required?
1	Mission	Sub-doc-level positioning paragraph. What is this sub-doc about; why now; how it frames the rest of the content.	Required (every sub-doc)
2	Core content / Vision	Sub-doc-specific main content section. For 01 = “Vision”; for 02 = “Data-flow architecture”; for 03 = “v1 stack composition”; for 04 = “Workspace types”; for 05 = “Q&A flow”; etc.	Required
3	User model / consumer model	Who consumes this sub-doc’s subject area; primary surfaces; secondary surfaces. Useful where consumer framing changes the schema/flow shape. Skip where not load-bearing.	Optional (skip for 07-collapse-list, 09-diagrams)
4	Application types / cross-coupling	How the sub-doc’s subject couples to the application_types-as-applications framing. Useful for sub-docs that span application types.	Optional (load-bearing for 04, 05, 08; mention-only for 02, 03)
5	First domain or main-content section	Sub-doc-specific. For 01 = “First domain applications”; for 04 = “Combined-PR scope detail”; for 05 = “q_a_pairs corpus-level pattern”; for 08 = “Knowledge Map / Change Reports / bid-feedback loop”.	Required
6	Anti-patterns to avoid	Table of explicitly-rejected framings with rationale + ratification citation. Pulls forward from the §6 pilot table; each sub-doc extends with its own subject-specific anti-patterns.	Required
7	Status of 0.9-intended-architecture.md	Boilerplate cross-link to INV-architecture-split-readiness.md §2 audit trail; explains the source doc is preserved as pre-split snapshot. Identical paragraph across all 9 sub-docs (consistency over re-invention).	Required (identical wording across sub-docs encouraged)
7.1	Heritage docs table	Vision/strategy/reference docs that predate the sub-doc and carry useful framings. One table row per heritage doc with current status + useful-for. Sub-doc-specific.	Optional (load-bearing for 01, 03, 04; thinner or skip for 07, 09)
8	Outstanding judgment calls	Pilot review notes — sections, framings, and length-balance items flagged to Liam. Includes the “no fabrication” gap flags from §5 of this guide.	Required (even if empty — at least an “Outstanding judgment calls: none surfaced for review” line)

2.2 Concrete pattern reference from the pilot

The pilot opens with:

# 01 — Vision

**Audit date:** 14/05/2026 (S238 Wave 1 — WP4 architecture-split pilot)
**Scope:** Mission, vision, user model, and the application-types-as-applications framing for Knowledge Hub v1.
**Status:** WORKING DRAFT — pilot sub-doc; first of the 9-way split of `docs/plans/phase-0-investigation/0.9-intended-architecture.md`. Shape under Liam review.
**Predecessor sub-doc framing:** None — Layer-1 (no upstream deps) per `docs/specs/core-docs-pathway-assessment/INV-architecture-split-readiness.md` §4.
**Companion sub-docs (planned):** `02-data-flow.md`, `03-tech-stack.md`, `04-workspace-types.md`, `05-qa-flow.md`, `06-mcp-tooling.md`, `07-collapse-list.md`, `08-new-features.md`, `09-diagrams.md`.

Adopt the same five-line header convention on every sub-doc:

1. Audit date: — DD/MM/YYYY plus parenthetical session/wave attribution.
2. Scope: — one-sentence statement of the sub-doc’s subject area.
3. Status: — WORKING DRAFT / RATIFIED / SUPERSEDED-BY-X.
4. Predecessor sub-doc framing: — layer position per INV-architecture-split-readiness.md §4; lists upstream sub-docs the draft references.
5. Companion sub-docs (planned): — the full list of 9 sub-docs (or the subset still planned at draft time) so a reader can navigate forward and back.

2.3 Pattern is a template, not a hard rule

Where sub-docs may diverge:

• 07-collapse-list.md is a transformation of docs/plans/phase-0-investigation/0.9-collapse-candidates.md per the S232 Liam reframe (“list ONLY items collapsing, no duplication”) — it may be a thin pointer doc, not a full narrative. Sections §3, §4, §5, §7.1 likely shrink to a few lines or disappear.
• 09-diagrams.md carries ERDs + flow diagrams as primary content. Sections §3, §4, §5 are likely absent; §2 (“Diagrams” overview) and a dense series of diagram sub-sections take their place.
• 06-mcp-tooling.md is gated on Theme F MCP-action review (per docs/specs/core-docs-pathway-assessment/INV-architecture-split-readiness.md §5 + docs/plans/phase-0-investigation/10-feedback-investigation-findings/00-synthesis-v2.md §5.2 row 1). When drafted, its §2 covers mempalace direct vs wrapped, MCP tool inventory, wing wire-up; §3-§5 may be thin.

Where consistency matters most:

• §6 Anti-patterns and §7 source-doc-status are the load-bearing consistency points. Adopt the same table format + boilerplate wording across all 9 sub-docs.
• §1 Mission positions the sub-doc within the 9-doc family. Use the same opening rhythm — “X is the [n]th sub-doc that…” — to make navigation predictable.

---

3. Citation discipline

Every ratification claim in a sub-doc requires an explicit citation. The pilot establishes five citation patterns; subsequent sub-docs should match these formats.

3.1 The five common citation patterns

Pattern 1: Q-OQR1-XX Liam ratification references — when claiming a Q-OQR1 ratification, cite the synthesis register section that records it.

The shape is Q-OQR1-01 "Option (c) hybrid with provenance", ratified per
`docs/plans/phase-0-investigation/10-feedback-investigation-findings/00-synthesis-v2.md` §3.4.

Or alternatively, cite the feedback investigation that drove the ratification:

…per Q-OQR1-01 (Option (c) hybrid) + Q-OQR1-03; see
`docs/plans/phase-0-investigation/10-feedback-investigation-findings/phase-b-prerequisite-1-onthology-pipeline-feedback-investigation.md` §8.

Pattern 2: WP8 N7 / N9 / audit_log RLS references — these landed S236 outside the Q-OQR1 register.

…per N9 RESOLVED-S236 (separate `embedding_score` + `fulltext_score` columns;
op-verify deferred to feature spec), cited at
`docs/plans/phase-0-investigation/10-feedback-investigation-findings/00-synthesis-v2.md` §5.1.

Pattern 3: S237 CV resolutions — the 9 CV-level Liam pre-decisions in commit 099eb5f6.

…per S237 CV 04 content-type author-vs-evidence rule (ISO management-system framing),
ratified per `docs/plans/phase-0-investigation/10-feedback-investigation-findings/00-synthesis-v2.md` §5.4.

Pattern 4: Astro+Starlight docs-site framework — ratified S237; lives in the ontology README.

…docs-site mirror via Astro+Starlight per
`docs/ontology/README.md` "Docs-site auto-update plan".

Pattern 5: Schema-level claims dependent on Q-OQR1-16 combined PR — these are RATIFIED-S235 in framing but the migration is STILL-OPEN. Always qualify.

The `workspaces.application_type_id` FK replaces the `workspaces.type` CHECK column
(per Q-OQR1-01 + Q-OQR1-03; **RATIFIED-S235**, **migration STILL-OPEN** —
combined-PR scope per `docs/plans/phase-0-investigation/0.9-decision-graph.md` §11.3).

Always include both the ratification status and the migration-state qualifier when discussing the combined PR. Do NOT write as if the schema is already live. Do NOT write as if it might still change shape.

3.2 Citation format conventions

• Use backtick-wrapped path + section identifier: `docs/path/to/file.md` §X.Y.
• Use UK English ratification wording: “ratified”, “superseded”, “deferred”, “retired”.
• Cite once per claim. Do not litter every sentence — cite the section that establishes the framing, then proceed.
• Where multiple cites converge on one claim, list with +: …per Q-OQR1-02 + Q-OQR1-05; `00-synthesis-v2.md` §3.5.

3.3 What to cite vs what not to cite

Citation required	Citation not required
Q-OQR1-XX ratification claims	Generic Knowledge Hub framing already in CLAUDE.md
Schema retire / rename / instance-table introduce decisions	UK English / no-emojis style choices
WP8 N7 / N9 / audit_log RLS claims	Section structure within the sub-doc itself
S237 CV resolutions	Cross-references to the sub-doc’s own §2 or §4
Combined-PR scope items	Forward references to companion sub-docs (use 04-workspace-types.md directly without further qualifier)
Astro+Starlight, Docling, Cloud Run sidecar, pullmd retention decisions	Standard product-design principles (“one record, many views”, AI as invisible infrastructure, programmatic where possible) — these are in CLAUDE.md “Key Product Design Principles”
Heritage-doc framing claims	The fact that CLAUDE.md exists

---

4. Heritage doc handling

The pilot §7.1 establishes a heritage table for vision/strategy docs that predate the sub-doc. Subsequent sub-docs adapt the table to their own subject area.

4.1 The §7.1 heritage table pattern

Column	Content
Doc	Backtick-wrapped path.
Date	DD/MM/YYYY of the heritage doc’s last verified date or last substantive update.
Current status	[CURRENT-CANONICAL] for narrower scope still authoritative; [PARTIALLY-SUPERSEDED] where some claims hold and some don’t; [FULLY-SUPERSEDED] where the doc is preserved only for audit-trail. Brief one-line qualifier indicating which claims hold and which are at variance with current ratifications.
Useful for	One-line summary of what a reader should consult the heritage doc for.

4.2 Per-sub-doc heritage doc guidance

The mapping is non-exhaustive — sub-doc writers should grep broadly during research, not just consult this list.

Sub-doc	Likely heritage docs
01-vision.md (pilot)	docs/client-documentation/Knowledge Hub — Platform Overview.md; docs/client-documentation/Knowledge Hub — Claude Integration Guide.md; docs/reference/ai-integration-strategy.md (§1); docs/reference/product-differentiation-audit.md.
02-data-flow.md	docs/plans/phase-0-investigation/10-feedback-investigation-findings/phase-b-prerequisite-2-cocoindex-deep-dive.md; docs/plans/phase-0-investigation/10-feedback-investigation-findings/phase-b-prerequisite-2d-docling-bakeoff.md; docs/reference/ai-integration-strategy.md (§4-§7 layer descriptions).
03-tech-stack.md	docs/reference/ai-integration-strategy.md (§4-§7); docs/plans/phase-0-investigation/10-feedback-investigation-findings/phase-b-prerequisite-2-cocoindex-deep-dive.md; docs/plans/phase-0-investigation/10-feedback-investigation-findings/phase-b-prerequisite-2d-docling-bakeoff.md.
04-workspace-types.md	docs/plans/phase-0-investigation/10-feedback-investigation-findings/phase-b-prerequisite-1-onthology-pipeline.md; docs/plans/phase-0-investigation/10-feedback-investigation-findings/phase-b-prerequisite-1-onthology-pipeline-feedback-investigation.md; docs/plans/phase-0-investigation/0.9-collapse-candidates.md §12.
05-qa-flow.md	docs/plans/phase-0-investigation/0.9-spike-S16-qa-schema-design.md; docs/plans/phase-0-investigation/0.9-spike-S9-cocoindex-idempotency.md; the same WP-ONTO-R1 §4 q_a_pairs corpus-level investigation.
06-mcp-tooling.md	Theme F MCP-action review register entries; docs/specs/mcp-server-spec/ (if exists at draft time); plugin-bundle docs in lib/mcp/.
07-collapse-list.md	docs/plans/phase-0-investigation/0.9-collapse-candidates.md (full doc — this is essentially a transformation, not a derivative).
08-new-features.md	docs/plans/phase-0-investigation/10-feedback-investigation-findings/05-bid-response-feedback-loop.md; docs/reference/product-differentiation-audit.md; Knowledge Map S7 spike (when ratified).
09-diagrams.md	docs/plans/phase-0-investigation/0.9-intended-architecture.md §15 (illustrative source — treat as predecessor sketch only, redraw from current state); the schemas finalised in 02-data-flow.md / 04-workspace-types.md / 05-qa-flow.md are the canonical source.

4.3 How to handle heritage-doc staleness

Heritage docs predate the S233-S237 ratification cascade. The pilot §7.1 captures the staleness-aware pattern:

• State the heritage doc’s current status with the qualifier ([CURRENT-CANONICAL] / [PARTIALLY-SUPERSEDED]).
• Note specific framings that have shifted (e.g. “Pre-Phase-0.9 in places — e.g. bid_workspaces framing superseded by procurement umbrella per Q-OQR1-02”).
• Note which framings remain load-bearing (e.g. “Source of the ‘data is the blocker’ framing cited in §1”).
• If a heritage doc framing conflicts with a Phase 0.9 ratification, defer to the ratification and surface the contradiction in §8 outstanding judgment calls.

Do NOT silently lift a heritage doc claim that has been superseded. Do NOT silently rewrite a heritage doc framing — heritage docs have their own ownership and update cadence.

---

5. Discipline: no fabrication

This is the load-bearing rule of the guide. Every other rule defers to it.

5.1 The rule

If a section requires information that is not available in the cited sources, the sub-doc agent MUST:

1. Flag the gap explicitly in the sub-doc — either in §8 Outstanding judgment calls or in a dedicated “Gaps + prerequisite work” section if the gap count justifies it.
2. Categorise the gap using the four categories in §5.2 below.
3. NOT invent an answer. No plausible-sounding extrapolation. No “reasonable default” filled in with framing that reads as ratified. No “TBD” inline in the prose where it looks like a placeholder that an editor will resolve — explicit gap flags only.
4. NOT extrapolate from heritage docs that predate the ratification cascade. If a heritage doc carries a framing that has been superseded, do not lift it just because it sounds confident.
5. Cite which source was checked + what was not found. Make the gap auditable: “checked 00-synthesis-v2.md §3-§5, 0.9-decision-graph.md §11, and 0.9-collapse-candidates.md §12 — no ratification on X found”.
6. Suggest the prerequisite work that would unblock the section. Name the doc to write or the spike to run.

5.2 Gap categories

When flagging a gap, classify it into one of four categories. The category drives the prerequisite work suggestion.

Category	When to use	Prerequisite work pattern
Product spec needed	The gap is user-facing behaviour that has not been decided. The shape of what the user sees / does is unsettled.	Write a docs/specs/<feature>/PRODUCT.md (use the write-product-spec skill).
Tech spec needed	The gap is engineering detail that has not been worked out. The user-facing behaviour is clear but the implementation pattern is unsettled.	Write a docs/specs/<feature>/TECH.md (use the write-tech-spec skill).
Investigation needed	The gap is an empirical question (does X work? what does production data show? does library Y support pattern Z?) that has not been answered.	Schedule a spike. Open a finding doc in docs/plans/phase-0-investigation/<wave>/ or a research doc in .planning/.research/<topic>/.
Ratification needed	The gap is a specific framing that requires a Liam pre-decision. The answer is binary or narrow-set; Liam needs to pick.	Surface as a STILL-OPEN item in 00-synthesis-v2.md §5.2 or 0.9-decision-graph.md §11.4. Flag in the continuation prompt’s “Liam pre-decision” list.

5.3 Concrete gap-flag format

Example, drawn from the pilot’s §8 forward-reference handling:

08-new-features.md Knowledge Map surface scope. Knowledge Map is confirmed as a cocoindex-substrate per CX.32 (0.9-decision-graph.md §11). The user-facing surface — what users see, what they can do, what the navigation looks like — is NOT ratified. Checked 00-synthesis-v2.md §3 + §5, 0.9-decision-graph.md §11.4, and INV-architecture-split-readiness.md §5 — no ratification on surface scope found. Category: product spec needed. Suggested prerequisite work: open docs/specs/knowledge-map/PRODUCT.md ahead of the Knowledge Map sub-section in 08. Until that lands, the 08 sub-doc surfaces Knowledge Map as a mention-only reference to the cocoindex substrate; the surface design is flagged STILL-OPEN per 00-synthesis-v2.md §5.2 row 4.

This pattern:

• Names the specific gap.
• Cites the source(s) checked.
• States what was looked for and not found.
• Classifies the category.
• Suggests the unblocking work.
• Indicates what the sub-doc does in the meantime (mention-only reference, not silent omission).

5.4 Why this rule is load-bearing

The 9 architecture sub-docs are the canonical current state. They supersede 0.9-intended-architecture.md. Once they land and the source doc is archived, fabricated framings get downstream-cited as if ratified. A subsequent agent reading 04-workspace-types.md cannot tell which schema claims were ratified by Liam and which were extrapolated by an earlier sub-agent.

The audit trail in INV-architecture-split-readiness.md §2 lists 10 source-doc claims now superseded — that exercise is only possible because the source doc was written before the ratifications. The sub-doc family being authored now does not have that excuse. Fabricated claims in the sub-docs create the same audit-trail problem the split exists to fix.

The discipline parallel is docs/reference/test-philosophy.md §1 criterion 1 (“Tests verify expected behaviour”). The equivalent here is: sub-docs assert ratified architecture. Anything beyond ratified is flagged, not stated.

---

6. Forward-reference policy

Sub-docs reference each other. The policy keeps cross-references honest without bloating.

6.1 Vision-level forward references — OK

When a sub-doc needs to point at content that properly lives in another sub-doc, vision-level pointers are fine.

Example from the pilot §4.1:

…the workspace pattern uses an instance table per Q-OQR1-01 + Q-OQR1-03;
detailed schema lands in `04-workspace-types.md`.

This:

• Names the pattern at vision level (instance table).
• Cites the ratification (Q-OQR1-01 + Q-OQR1-03).
• Points the reader to the canonical sub-doc for detail.
• Does NOT promise a specific schema shape that 04 may surface differently.

6.2 Schema-specific forward references — NOT OK

A sub-doc must NOT pre-commit schema shape that lives elsewhere.

Bad example (do not do this in 01-vision.md):

-- workspaces table (per 04-workspace-types.md)
CREATE TABLE workspaces (
  id UUID PRIMARY KEY,
  application_type_id UUID NOT NULL REFERENCES application_types(id),
  ...
);

This locks 04-workspace-types.md into a specific schema before 04 is even drafted. If 04 then surfaces a different column set (because a verifier finds a missing column, or because Liam ratifies a refinement at 04-write time), the two sub-docs disagree. The split that was supposed to fix the source-doc drift now creates cross-sub-doc drift.

6.3 The rule

Each sub-doc’s level of detail matches its own section’s purpose. Sibling-sub-doc detail is referenced by pointer, not copied.

Sub-doc	What it owns	What it points to
01-vision.md	Mission, vision, application-types-as-applications framing	Schemas (→ 04), data flow (→ 02), Q&A (→ 05)
02-data-flow.md	Cocoindex flow stages, Cloud Run sidecar topology, ingest paths, op_id, auto-RLS event trigger	Schemas (→ 04), MCP tooling (→ 06)
03-tech-stack.md	Stack composition list (Docling, Cloud Run, pullmd, cocoindex, Tiptap+Yjs, mempalace, Anthropic doc skills)	Flow stages (→ 02), schemas (→ 04)
04-workspace-types.md	Full schema detail for application_types, workspaces, *_workspaces satellites, q_a_pairs corpus-level shape, combined-PR scope	Flow stages (→ 02), Q&A retrieval (→ 05)
05-qa-flow.md	q_a_pairs corpus-level pattern, scope_tag-driven relevance, citations polymorphic, question_matches separate-columns scoring, markdown sidecar v1 pattern	Schemas (→ 04 for table shape), data flow (→ 02 for ingest path)
06-mcp-tooling.md	KH MCP tool inventory, mempalace direct vs wrapped, wing wire-up	Flow stages (→ 02), schemas (→ 04)
07-collapse-list.md	Retire-list per item with tier markers	Schemas (→ 04), retired items detail (→ 0.9-collapse-candidates.md §12-§13)
08-new-features.md	Knowledge Map (cocoindex substrate), change reports, scope_tag taxonomy, governance + freshness, bid-feedback loop	Flow stages (→ 02), schemas (→ 04), Q&A (→ 05)
09-diagrams.md	ERDs + ingest flow + Q&A round-trip + bid feedback + Cloud Run sidecar topology diagrams	Schemas (→ 04), data flow (→ 02), Q&A (→ 05) — renders their narrative

When in doubt: a sub-doc’s section should reference, not duplicate, sibling content. If two sub-docs cover the same schema in detail, one of them is wrong.

---

7. UK English + style

Apply CLAUDE.md “Key Product Design Principles” verbatim. The specifics that bite most often in sub-doc drafting:

7.1 Language

• UK English throughout. “Colour”, not “color”. “Organisation”, not “organization”. “Behaviour”, not “behavior”.
• DD/MM/YYYY dates. Audit dates, ratification dates, source-doc dates — all DD/MM/YYYY.
• No emojis. Anywhere in the sub-doc.

7.2 Banned terminology

These terms are banned per S231+ ratification:

• Budget terminology. No “budget”, no “estimate”, no cost framing for work effort. Phase 0.9 ratification removed dollar/pound-cost framings from architecture docs.
• Day-count terminology. No “~3-5d”, “~1 week”, “~2 person-days”. The pilot §2 of INV-architecture-split-readiness.md §2 row 7 explicitly flags this as a v1.0 source-doc artefact (the 0.9-intended-architecture.md §1.2 “Material impact” line “~3-5d” + “~5d HIGH cost” terminology). Subsequent sub-docs must not reintroduce this framing.
• Spike-confidence terminology. No “95% confidence” / “high confidence” markers in the prose of architecture sub-docs (spike reports retain confidence markers — that is their function). Architecture sub-docs assert ratified state; confidence framing belongs in the spike or finding doc, not the architecture record.

7.3 AI Visibility Policy

Per docs/reference/ai-visibility-policy.md:

• No “AI features” labelling. AI processing is invisible infrastructure. The outputs are platform features (Quality, Summary, Change Reports), not labelled AI capabilities.
• No “powered by Claude” branding in user-facing surfaces. Model names appear only on /provenance admin tabs for audit.
• No embedded chat sidebar referenced as a planned surface. Removed in S109; do not reintroduce.

7.4 Procurement umbrella (NOT “bid” as workspace/application type)

Per Q-OQR1-02 + Q-OQR1-05:

• application_type='procurement' — NOT 'bid'.
• procurement_workspaces — NOT bid_workspaces.
• PROCUREMENT_WORKFLOW_STATES — NOT BID_STATES.
• lib/procurement/procurement-workflow.ts — NOT lib/bid/bid-state-machine.ts.

“Bid” survives in v1 as one form_type value within the procurement umbrella (alongside rfp, pqq, itt, framework, dps, gcloud). It is no longer the name of the application.

If a sub-doc finds itself reaching for “bid_workspaces” or BID_STATES, it is citing the pre-Q-OQR1-02 framing — replace with procurement-umbrella naming.

7.5 Heritage doc cross-link convention

Use backtick-wrapped relative paths with section identifiers:

…per `docs/reference/ai-integration-strategy.md` §1.4 design principles.

Avoid bare paths. Avoid markdown autolink syntax for internal docs. Avoid absolute paths.

---

8. What “ready-to-draft” actually means

Readers entering the sub-doc family may treat “READY-TO-DRAFT” status (as captured in docs/plans/phase-0-investigation/10-feedback-investigation-findings/00-synthesis-v2.md §4) as a green light to dispatch a sub-agent without further checks. This is a misread.

8.1 What READY-TO-DRAFT means

A sub-doc marked READY-TO-DRAFT in 00-synthesis-v2.md §4 has:

• No ratification gates remaining on the sub-doc as a whole. (e.g. 04-workspace-types.md does not have a Theme F-style STILL-OPEN gate.)
• A coherent set of upstream ratifications (Q-OQR1, WP8 N7/N9, S237 CV resolutions, S235 register cascades) that supply the central frame.
• A clear set of source materials (heritage docs + Phase 0.9 finding docs + WP-ONTO-R1 + spike outputs).
• A clear position in the dependency layer (Layer 1 / 2 / 3 per INV-architecture-split-readiness.md §4).

8.2 What READY-TO-DRAFT does NOT mean

READY-TO-DRAFT does not mean:

• Every sentence has a known answer. Sections within a READY-TO-DRAFT sub-doc may still require product spec / tech spec / investigation / ratification per the no-fabrication rule in §5 of this guide.
• The sub-doc agent can fill gaps from heritage docs. Heritage docs predate the ratification cascade.
• The sub-doc agent can extrapolate from cocoindex docs, Supabase docs, or other external references in lieu of a Liam ratification.
• The sub-doc is single-pass. The pilot landed in S238 with a content-fix pass (cited Liam-provided heritage docs that the original sub-agent prompt missed — see pilot §8 last bullet).

8.3 The drafting agent’s standing instruction

When drafting a sub-doc, treat READY-TO-DRAFT as “the framework is settled; you must verify each section’s content against ratifications”. If a section requires a fact that is not in the ratification set, apply §5 of this guide (flag the gap, classify, suggest prerequisite work) — do not paper over.

The verifier sub-agent in §10 below catches sections that violated this rule; the goal of the drafting agent is to flag the gaps explicitly so the verifier has nothing structural to find.

---

9. Per-sub-doc adaptations

A short reference for where the pattern adapts per sub-doc. Sub-doc writers should treat this as the starting point — the readiness map in INV-architecture-split-readiness.md §3 is the canonical inventory.

9.1 02-data-flow.md

Subject: Source-binding model, cocoindex flow stages, binary path with Cloud Run sidecar, audit_log + op_id propagation, auto-RLS event trigger, grants pattern, ingest write paths.

Pattern adaptation:

• Heavier on flow diagrams (cross-link to 09-diagrams.md for the rendered diagrams; carry the prose flow descriptions here).
• §3 user model thin or skipped (consumer is the pipeline, not the user — references 01-vision.md for the consumer framing).
• §4 application-type cross-coupling mention-only (data flow is application-type-agnostic at the substrate level; per-application flow specifics live in 04).
• Section count likely higher than the pilot — Cloud Run sidecar, auto-RLS, N7 op_id, grants pattern each warrant a section.

RLS-PATTERN destination decision: per INV-architecture-split-readiness.md §5 + 00-synthesis-v2.md §3.16, the RLS-PATTERN doc location is “TBD with 04-workspace-types or new RLS-PATTERN.md”. 02-data-flow.md references the auto-RLS event trigger as one of the ingest-write-path concerns; the standalone RLS-PATTERN doc location is Liam pre-decision per INV-architecture-split-readiness.md §7.4.

9.2 03-tech-stack.md

Subject: v1 stack composition list with per-component detail; Docling + Cloud Run sidecar; pullmd retention; cocoindex; Tiptap+Yjs; mempalace; Anthropic doc skills.

Pattern adaptation:

• Composition list as the central form. Each technology entry: role, decision-source (per Q-OQR1-XX or COCO.XX), key constraints, related sub-doc.
• §6 anti-patterns largely about stack rejections (Pattern A/B retire, pipeline_failures DO-NOT-BUILD, cost-tracking dashboards retire).
• Section count similar to pilot (~6-8 sections); depth per stack entry is the load-bearing detail.

9.3 04-workspace-types.md

Subject: BIG sub-doc. application_types instance table; per-application-type satellites; procurement rename; kb_section retirement; q_a_pairs corpus-level + scope_tag pattern; combined-PR scope detail.

Pattern adaptation:

• Largest sub-doc by scope per 00-synthesis-v2.md §4 row 4 — “application_types + kb_section retire + procurement rename + q_a_pairs corpus-level all live here”.
• Combined-PR scope per docs/plans/phase-0-investigation/0.9-decision-graph.md §11.3 (10 items) is the central narrative — cite verbatim.
• Lots of schema-level detail. Use SQL fragments judiciously and only for ratified shapes; flag any shape that is Q-OQR1-16 migration STILL-OPEN.
• §3 user model relevant (workspace creation flow, application-type selection during onboarding).
• §4 application-type cross-coupling is the central content section.
• May warrant a §5.5 or §5.6 “Combined-PR scope walkthrough” subsection per item.
• This sub-doc is the canonical source for everything downstream — 02, 05, 06, 08, 09 all reference its schemas. Get the schemas right.

9.4 05-qa-flow.md

Subject: q_a_pairs corpus-level pattern; markdown sidecar v1; citations polymorphic; question_matches with question_kind discriminator; separate embedding_score + fulltext_score columns.

Pattern adaptation:

• UC-by-UC (use-case-by-use-case) structure is helpful — Q&A round-trip is more flow-like than schema-like at the read tier.
• N9 separate-columns scoring per WP8 ratification (00-synthesis-v2.md §5.1) — cite verbatim.
• N8 polymorphic citations (citations.citing_entity enum) lands here.
• Q-OQR1-06 corpus-level shape lands here — cite the empirical “0 of 395 prod q_a_pair rows workspace-assigned” finding.
• §5 sub-sections likely by question_kind discriminator (bid_question, future kinds).

9.5 06-mcp-tooling.md

Subject: KH MCP tool inventory; mempalace direct vs wrapped pattern decision; wing wire-up; MCP-action refine/remove/extend pass.

Pattern adaptation:

• Gated on Theme F MCP-action review (lone STILL-OPEN gate per 00-synthesis-v2.md §4 row 6 + §5.2 row 1).
• Do NOT draft until Liam pre-decision on Theme F lands. The §5 no-fabrication rule applies strongly here.
• When ratified, this sub-doc’s §2 covers tool inventory + mempalace direct vs wrapped decision; §3-§4 are likely thin (MCP is platform-internal, not application-type-coupled in v1).
• §6 anti-patterns relevant — mcp-handler on Vercel rejection, WebStandardStreamableHTTPServerTransport correct path, fresh server + transport per request.

9.6 07-collapse-list.md

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

Pattern adaptation:

• TRANSFORMATION of docs/plans/phase-0-investigation/0.9-collapse-candidates.md. Very different shape from the pilot.
• May be a thin pointer doc — tier markers + pointer back to 0.9-collapse-candidates.md §12-§13 detail.
• The S232 Liam reframe direction suggests thin-pointer over self-contained — confirm at Wave 1 draft time per INV-architecture-split-readiness.md §6 “In-session Liam decision suggested”.
• §1 Mission still applies (positioning paragraph).
• §3, §4, §5 may be absent. §6 anti-patterns + §7 source-doc-status still apply.
• §8 outstanding judgment calls may capture sub-decisions (which items collapse vs which defer).

9.7 08-new-features.md

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

Pattern adaptation:

• References 02-data-flow.md / 04-workspace-types.md / 05-qa-flow.md heavily.
• Knowledge Map surface scope STILL-OPEN per 00-synthesis-v2.md §5.2 row 4 — mention-only reference to cocoindex substrate; flag the surface gap per §5 of this guide.
• §3 user model relevant (each feature has its own consumer pattern).
• §4 application-type cross-coupling — change reports cross application types; bid-feedback loop is procurement-specific; Knowledge Map is corpus-wide.
• N4 coverage bid_response cosmetic preference (per 00-synthesis-v2.md §2.3 N4) — cite as Liam preference, not as an architectural decision.

9.8 09-diagrams.md

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

Pattern adaptation:

• Diagrams as primary content; prose is connective tissue.
• §3, §4, §5 likely absent.
• §1 Mission + §2 “Diagrams” overview + diagram sub-sections (§3 onwards renumbered as diagram sub-sections).
• §6 anti-patterns thin (no diagrams that contradict the prose sub-docs).
• §7 source-doc-status still applies.
• Sequencing-gated by Wave 1+2 sub-docs landing first per INV-architecture-split-readiness.md §4 (“ERDs need schemas finalised in 04 + 02 + 05”).
• Verification gate per §10 of this guide: no schema appears in a diagram that doesn’t appear in the corresponding prose sub-doc.

---

10. Verification gate

Every sub-doc that lands gets a verifier sub-agent pass — Spec-Code-Verify workflow per CLAUDE.md “Implementation Workflow”. The verifier checks structural compliance with this guide, not subject-matter correctness (that is the drafting agent’s job).

10.1 Verifier checklist

The verifier sub-agent passes the sub-doc through the following checks:

#	Check	Pass criteria	Fail criteria
1	Section structure compliance	Header convention per §2.2; sections §1-§8 present (or documented omission with rationale per §2.3); §1.X / §2.X / §5.X sub-sections numbered.	Missing required sections without rationale; arbitrary section numbering; section-header content drift from §2.1 template.
2	Citation discipline	Every ratification claim cites per §3.1 patterns. Combined-PR Q-OQR1-16 claims qualified with “RATIFIED-S235, migration STILL-OPEN”.	Claims without citation; citations to wrong sections; combined-PR claims as if already migrated.
3	No-fabrication discipline	Gaps flagged per §5.3 format; gap categories per §5.2 assigned; sources checked listed; prerequisite work suggested.	Plausible-sounding claims not backed by ratifications; silent gaps; “TBD” placeholders inline in prose.
4	Forward-reference policy	Vision-level references to sibling sub-docs OK per §6.1; no schema-specific copies of content owned by another sub-doc per §6.2.	Schema definitions duplicated across sub-docs; pre-committing shape that lives in 04; circular references.
5	UK English + style	UK spellings; DD/MM/YYYY dates; no emojis; no banned terminology per §7.2; no “AI features” labelling per §7.3; procurement umbrella per §7.4.	American spellings; budget/day-count/confidence-marker terminology; “bid_workspaces”; “AI feature” labels.
6	Heritage-doc handling	§7.1 table format per §4.1; staleness qualifiers per §4.3; per-sub-doc relevance per §4.2.	Heritage doc framings silently lifted as if current; missing staleness qualifiers; heritage docs cited as ratification source.

10.2 Verifier verdicts

The verifier returns one of three verdicts:

Verdict	When	Next step
PASS	All 6 checks pass. No structural concerns.	Sub-doc merges. Move to next sub-doc in wave per INV-architecture-split-readiness.md §6.
PASS-WITH-NOTES	All 6 checks pass; verifier surfaces non-blocking observations (e.g. heritage-doc cross-link could be added; an §8 outstanding judgment call could be expanded).	Sub-doc merges. Notes captured in the merge commit message; addressed in subsequent content-fix pass if Liam requests.
FAIL	One or more checks fail.	Verifier dispatches a fix-agent sub-agent with the specific fail criteria. Fix-agent rewrites the failing sections; verifier re-runs.

10.3 Fix-agent dispatch criteria

When a verifier returns FAIL, the fix-agent dispatch must include:

1. The specific check(s) that failed (e.g. “Check 3 (no-fabrication): §4.2 claims audit_response_workspaces columns without citation”).
2. The relevant ratification source for the fix (e.g. “Apply §5.3 gap-flag format; cite per §3.1 Pattern 5 if relying on Q-OQR1-16 combined-PR scope”).
3. The acceptance criterion for re-verification (e.g. “Section §4.2 flags the gap explicitly with category ‘tech spec needed’ and suggests prerequisite spec doc path”).

Fix-agents work in worktree isolation per CLAUDE.md “Parallel agent isolation”. After fix-agent completes, the original verifier re-runs the 6 checks.

10.4 Final cross-doc audit

Per INV-architecture-split-readiness.md §6 (S240 — Wave 3 + tail closeup), the final wave includes a cross-doc consistency audit:

• Read all 9 sub-docs end-to-end.
• Flag any forward-reference, drift, or contradiction.
• Confirm 09-diagrams.md ERDs match the schemas in 04-workspace-types.md; flow diagrams match 02-data-flow.md + 05-qa-flow.md.
• Archive 0.9-intended-architecture.md to .planning/.archive/.specs/0.9-intended-architecture.md per CLAUDE.md “Historical planning” convention; preserve as audit trail.

The cross-doc audit is the gate at which the 9 sub-docs become the canonical current state and the source doc retires.

---

End of guide. The pilot (docs/plans/phase-0-investigation/architecture/01-vision.md) is the live reference implementation. Subsequent sub-doc agents read this guide + the pilot + the readiness map (docs/specs/core-docs-pathway-assessment/INV-architecture-split-readiness.md) as their three-doc onboarding pack before drafting.