Skip to content
Canonical

ID-71 {71.2} PRODUCT — AI tooling surface rationalisation (outcome-first surface + headless-completeness guarantee)

ID-71 {71.2} PRODUCT — AI tooling surface rationalisation

Section titled “ID-71 {71.2} PRODUCT — AI tooling surface rationalisation”

Status: {71.2} PRODUCT spec. Asserts the behaviour the rationalised AI-consumption surface must exhibit, with numbered, testable invariants the Checker verifies (primarily via the MCP eval L4 functional-correctness layer and the per-agent ID-104 contract). Predecessors, all ratified: {71.1} RESEARCH.md (Liam-ratified 2026-06-14, §7 dispositions), headless-requirement-refinement.md (WS-4 /idea-refine outcome, 2026-06-13 — the settled headless contract HR-1..HR-6 / HC-1..HC-6), SYNTHESIS.md, and the Lane A workshop record (WS-1..WS-14). Every WS / HR / HC decision below is settled input, not an open question. Three carried items remain for Liam (§Open questions). British English throughout. DD/MM/YYYY dates.

Summary

Section titled “Summary”

Knowledge Hub’s AI-consumption surface (MCP tools + resources + prompts + MCP Apps + plugin commands + plugin skills + inline AI touchpoints) accreted incrementally to 58 tools concentrated in curation, while the ranked client outcomes concentrate in consumption and output — the surface is inverted relative to value. ID-71 rationalises that surface outcome-first: keep / refine / retire / gap verdicts attach to the outcome a tool serves, not to the tool name, and the rationalised surface ships with a testable headless-completeness guarantee — the launch consumption-and-orientation set is completable end-to-end by an AI agent with zero human-in-UI step, every touchpoint born-evaluable against an ID-104 contract.

This spec fixes the behaviour of that surface and the headless guarantee. Runtime and eval mechanics (the goose daemon on IONOS/Coolify, Raindrop Workshop wiring, the ID-104 contract internals, the bid→forms rename lockstep, structured-output / citation shapes) are referenced only where HC-3 / HC-5 require them to state behaviour; they are specified in {71.3} TECH.

Problem

Section titled “Problem”

The 58-tool surface concentrates in curation (content management ≈ half the surface) while the ranked outcomes concentrate in consumption and output (O1 find/answer, O2 revenue documents, O4 briefing, O5 signal→action) — the surface is inverted relative to the outcome ranking (RESEARCH §1.2; SYNTHESIS §1.1). The two biggest gaps — O9 onboarding and the O5 consumption half — are also the two biggest differentiation claims (under-4-hours; signal-to-action). Tools accreted “as the platform developed” rather than from outcome-first design; the failure mode being corrected is exactly that accretion (supporting-ai-tooling-notes.md). Clients were told “you don’t need to remember the tools — just ask”, yet 58 tools is documented as over KH’s own ceiling and inflates the selection surface both Claude and users must “get to grips with”.

The deeper problem this spec must settle is headless completeness: KH’s differentiation thesis is that most applications become headless/agentic, so the core consumption and orientation work must be completable by an AI agent with no human clicking a UI — yet today every briefing is pull-only, there is no outgoing connectivity, and the 7 prompts / 12 resources / plugin skills / 4 MCP Apps are eval-blind (RESEARCH §5.3; SYNTHESIS §1.5). The settled headless-requirement-refinement.md contract resolves the shape of that guarantee (HC-1..HC-6); this spec restates it as verifiable behaviour.

Code-intelligence orientation (gitnexus, knowledge-hub, 2026-06-14)

Section titled “Code-intelligence orientation (gitnexus, knowledge-hub, 2026-06-14)”

The current surface description below is grounded in real symbols (cited verbatim, not paraphrased) so the Checker can confirm orientation and {71.3} TECH can navigate directly:

  • Single tool-registry aggregator. registerSearchTools (lib/mcp/tools/search.ts:60-712, module Tools) registers the search trio + find_similar_items (via findSimilarItemsImpl, lib/mcp/tools/search.ts:381-497) and has exactly one incoming caller: registerTools (lib/mcp/tools/index.ts) — the single registry through which all tool groups register. This is the WS-7 find-consolidation target and the single insertion point an Option-A single-server surface registers through.
  • defineTool annotation discipline is real and central. registerSearchTools calls defineTool and toStructuredContent (lib/mcp/tools/shared.ts), createMcpClient (lib/mcp/auth.ts, per-user RLS client), and tryQuery (lib/supabase/safe.ts) — the defineTool annotation, per-user RLS, and sb()/tryQuery() Supabase-safety patterns the rationalised surface must preserve. Formatters live in lib/mcp/formatters/search.ts (formatSearchResults, formatQASearchResults, formatChunkSearchResults) with truncateResponse (lib/mcp/formatters/shared.ts).
  • Eval substrate the headless guarantee is verified against exists. runSearchToolChecks / runWriteToolChecks / runGuideToolChecks (scripts/mcp-eval/functional-correctness.ts, module Mcp-eval — the L4 layer), runSearchRelevanceChecks / getTokenChecks (scripts/mcp-eval/response-quality.ts, L3), parseToolFile / parseToolBlock (scripts/lib/mcp-parser.ts — the inventory parser that asserts the canonical surface counts) and the canonical fixtures (scripts/mcp-eval/fixtures.ts: getKnownUUIDs, getMinimalArgs, createEvalItem). These are the layers HC-1 completability and HC-5 born-evaluability are checked against.
  • Write-back to the canonical store already has a substrate. writeBackFileFirst (lib/edit-intent/write-back.ts:131-282, module Edit-intent) is the file-first write-back path — directly the HC-4 “write-back to the local-fs canonical store” sanctioned destination, not a greenfield surface.

Orientation outcome: not greenfield — the rationalised surface refines an existing, indexed tool/eval/write-back substrate. No ccc search fallback or greenfield disclaimer applies.

Goals / Non-goals

Section titled “Goals / Non-goals”

Goals (ID-71 PRODUCT scope).

  • Fix the behaviour of the outcome-grouped human-facing surface (Option C layered on Option A — confirmed §7.5): one find, one where-are-we-exposed, one what's-in-my-queue (a single queue concept with a facet), one completing-forms surface, one get (one-or-many), one dedup, one assign; the 4 MCP Apps as the visual-density + resolution layer; prompts/commands as thin orchestrators; plugin skills as the expertise layer.
  • Assert the headless-completeness guarantee HC-1..HC-6 as numbered, testable behaviour invariants.
  • Require every new / refined touchpoint to ship born-evaluable against an ID-104 contract (HC-5; B-INV-13..15).
  • Frame all keep / refine / retire / gap verdicts against outcomes, not tool names.

Non-goals (deliberately out of ID-71’s delivery scope — RESEARCH §4 task-split map).

  • Building or operating a bespoke agent runtime. The runtime is adopted (goose, HR-1), pilot-gated, specified in {71.3} TECH — not built here.
  • The full agent fleet at launch. The launch headless scope is the {O1/O4/O6 reads + W5.6} set plus the one piloted recipe; the fleet is post-launch graduation, additive, grown per-Task as ID-104 metrics earn it (HR-1; WS-5; B-INV-21).
  • Owning W9.3 / onboarding (O9). Delegated to the onboarding Task (HR-4 / HC-6 / WS-6); ID-71 cross-references only.
  • Net-new product capabilities — O5 W5.2 sales triggers, O5 W5.3 marketing pipeline, O2 W2.3 renewal packs, O3 W3.1–W3.3 trust trio, O2 W2.2 proposal assembly — each graduates to its own Task with its own spec chain. ID-71 reserves the surface concepts, it is not the delivery vehicle (WS-2).
  • Net-new SharePoint/Drive source-system write-back at launch. WS-6-gated (HR-2a).
  • Auto-apply at launch. Propose-only; auto-apply is ID-104-earned, per-workflow (WS-5).
  • Hosted Raindrop on client data. Workshop-local only (HR-5 / WS-14).
  • Retrofitting outputSchema onto retiring/changing tools. bl-26 is the forward standard for new entries only (RESEARCH §5.2; {71.3} TECH).

Behavior

Section titled “Behavior”

Numbered, testable invariants. Each headless-completeness invariant (B-INV-1..21) cites the HC / HR / WS id it derives from so the Checker can trace it 1:1, and states an explicit pass/fail an automated check (MCP eval L4 functional-correctness + the per-agent ID-104 contract) or the Checker can verify. Verdict-framing and surface-shape invariants (B-INV-22..40) state the outcome-first surface behaviour.

A. Headless-completeness guarantee (the surface-#4 guarantee — HC-1..HC-6)

Section titled “A. Headless-completeness guarantee (the surface-#4 guarantee — HC-1..HC-6)”

HC-1 — Completable set (zero human-in-UI step).

  1. (B-INV-1, ⇐ HC-1) The launch headless-complete set is exactly the union of: O1 find/answer reads; O4 reorientation/briefing reads (widened beyond KH state — the read reorients the person, not only their KH state); O6 exposure-layer reads presented as the four layers data you have → how you could use it today → the gaps → the opportunities (B-INV-4); and W5.6 re-syndication. No other outcome is in the launch headless set. Pass: an L4 functional-correctness suite enumerates this set and only this set as the headless-complete entries; the Checker confirms the enumeration matches verbatim. Fail: any outcome outside this union is asserted headless-complete, or any member of this union is missing.

  2. (B-INV-2, ⇐ HC-1) Every workflow in the B-INV-1 set is 100% completable through MCP tools + Skills with zero human-in-UI step — an agent (Claude’s own runtime or the goose runtime, B-INV-9) can begin and finish the workflow without any step that requires a human to operate the web UI. Pass: for each B-INV-1 workflow, an L4 end-to-end check drives the workflow MCP-only (no UI affordance invoked) to a terminal result and asserts completion. Fail: any B-INV-1 workflow has a step reachable only through the web UI.

  3. (B-INV-3, ⇐ HC-1 / WS-4) O4 reorientation/briefing reads reorient the person, not only KH state — the briefing surface accepts and reflects context beyond KH’s own data (e.g. “what’s happening in my sector / role / day”, not only “what changed in your workspace”). Pass: the O4 read’s contract exposes a person-level reorientation framing and an eval fixture asserts a non-KH-state dimension is surfaced. Fail: the O4 read is limited to KH-internal state only.

  4. (B-INV-4, ⇐ HC-1 / WS-4 / WS-8) O6 exposure reads present the four layers (data you have → use-today → gaps → opportunities) as the consumption framing, with resolution first-class (gaps/issues surface with suggested resolutions — “Draft content for X”, “Discuss options for Y”). The former “its quality” layer is deliberately not present: ID-131.19 trimmed it from where_are_we_exposed because its sole RPC, get_quality_issue_counts, was dropped at M6 and deliberately not re-pointed (lib/mcp/tools/dashboard.ts:1-10) — this is a settled trim, not a gap to re-litigate. Pass: the O6 read contract returns the four-layer structure and at least one suggested-resolution affordance; an eval fixture asserts the layer ordering and the resolution affordance. Fail: exposure is returned as an undifferentiated list, without a resolution affordance, or a quality layer is reintroduced without a ratified scope change.

  5. (B-INV-5, ⇐ HC-1) W5.6 re-syndication is headless-completable — an agent can re-syndicate (re-publish/re-distribute an existing, already-published consumption output) end-to-end with zero human-in-UI step, within the publication discipline of B-INV-6 (re-syndication of already-published material is not a net-new publication gate event). Pass: an L4 check drives W5.6 MCP-only to a delivered re-syndication. Fail: W5.6 requires a human-in-UI step.

HC-2 — No publication gate inside the read set; propose-writes allowed.

  1. (B-INV-6, ⇐ HC-2 / HR-3 / WS-5 / WS-8) Headless agents MAY create propose-writes — drafts, suggestions, and WS-8 “Draft content for X” / “Discuss options for Y” resolutions — into the queue (B-INV-30), with no publication gate inside the read set. Publication remains human-gated (WS-5): an agent cannot transition content to published, nor perform a governance/outcome write that publishes, without a human gate. Pass: an L4 check confirms (a) an agent can create a propose-row / draft / suggested resolution into the queue with no human step, and (b) an agent attempting to publish (or set publication status to published) is refused at the surface and the action routes to the human gate. Fail: an agent can publish without a human gate, or a propose-write is blocked from the read/queue path.

  2. (B-INV-7, ⇐ HC-2 / WS-5) Auto-apply is off at launch; propose-only is the default. Auto-apply may be switched on per-workflow only when that workflow’s ID-104 quality metric earns it (B-INV-19). Pass: every headless write path defaults to propose-only; no workflow ships with auto-apply enabled at launch; the per-workflow auto-apply switch exists but is verifiably off. Fail: any workflow auto-applies a write at launch.

HC-3 — Dual runtime, both first-class.

  1. (B-INV-8, ⇐ HC-3 / WS-4) “Headless” is satisfied by two runtime forms, neither privileged: (a) Claude’s own runtimes (Claude Desktop / claude.ai / Cowork / Code) consuming the surface as MCP = ability + Skill = expertise; and (b) KH’s thin goose runtime for scheduled / system-actor workflows (W5.6 today; the fleet later). Pass: the headless-complete set (B-INV-1) is reachable identically from both runtime forms; no entry is exposed to one runtime and withheld from the other. Fail: any headless entry is runtime-privileged.

  2. (B-INV-9, ⇐ HC-3) The surface is identical across both runtimes — the same tools, resources, prompts, and contracts back both runtime forms; there is no goose-only or Claude-only consumption tool in the headless-complete set. Pass: the surface inventory consumed by the goose runtime equals the inventory consumed by Claude’s runtimes for the headless-complete set. Fail: the inventories diverge.

HC-4 — Bidirectional connectivity, first-class.

  1. (B-INV-10, ⇐ HC-4) Incoming connectivity is first-class via remote MCP (exists): a headless agent connects to KH’s remote MCP server (SSE / Streamable-HTTP + auth) and reads/proposes through the same surface. Pass: the remote-MCP-with-auth path is a supported, evaluated connection for the headless-complete set. Fail: incoming connectivity requires a non-MCP path.

  2. (B-INV-11, ⇐ HC-4 / HR-2) Outgoing connectivity is first-class as trigger-driven push — RSS / webhook / email delivery of consumption outputs (e.g. a scheduled O4 briefing delivered to an outbound channel), so briefings are no longer pull-only. Pass: at least one trigger-driven push channel delivers a consumption output end-to-end (the MVP pilot’s “deliver to one outbound channel”); an eval asserts delivery. Fail: every consumption output remains pull-only.

  3. (B-INV-12, ⇐ HC-4 / HR-2a / WS-6) Outgoing write-back is first-class but scoped to sanctioned destinations only: the controlled local-fs canonical store (grounded in writeBackFileFirst, lib/edit-intent/write-back.ts), the already-live HubSpot↔Cowork connector (the client’s, ridden — not a KH-built connector), and push delivery (B-INV-11). Net-new SharePoint/Drive source-system write-back stays WS-6-gated and MUST NOT be enabled at launch. Pass: write-back targets only the three sanctioned destinations; an L4 check confirms a net-new source-system write-back is refused at the surface. Fail: any write-back reaches a non-sanctioned destination, or a net-new source-system write-back is enabled.

HC-5 — Born-evaluable.

  1. (B-INV-13, ⇐ HC-5) Every headless agent ships an ID-104 eval contract — a headless agent (and every new / refined touchpoint: tool, prompt, plugin skill, inline touchpoint) MUST NOT ship without a declared eval requirement bound to an ID-104 contract. Pass: the inventory/guard layer (extending the inventory-parser + fixture-sync pattern) rejects a new/refined touchpoint that lacks an ID-104 eval contract. Fail: any new/refined touchpoint ships eval-blind.

  2. (B-INV-14, ⇐ HC-5) Fleet evals are authored locally and committed into KH’s gate — agent evals are authored via Raindrop Workshop (local) and committed into KH’s L3/L4 + baseline harness; the eval artefacts are KH-owned, not coupled to a Raindrop-proprietary format. Pass: a headless agent’s eval lives in KH’s L3/L4 + baseline harness and runs under KH’s CI. Fail: an agent’s eval lives only in a Raindrop-proprietary artefact.

  3. (B-INV-15, ⇐ HC-5 / WS-5 / WS-14) The WS-5 graduation metric is computed in-house, never via Raindrop cloud — the per-workflow quality metric that earns auto-apply is computed on KH’s ID-104 infrastructure; no client-data-derived trajectory is POSTed to Raindrop cloud. Pass: the graduation metric is produced by KH’s in-house harness and a network assertion confirms zero client-data egress to Raindrop cloud. Fail: the metric depends on Raindrop cloud, or client-data trajectories egress to Raindrop cloud.

HC-6 — W9.3 delegated.

  1. (B-INV-16, ⇐ HC-6 / HR-4 / WS-6) W9.3 (onboarding discovery→propose) headlessness is owned by the onboarding Task, not ID-71 — ID-71’s headless-complete set (B-INV-1) deliberately excludes W9.3; ID-71 cross-references the onboarding Task only. Pass: W9.3 is absent from ID-71’s headless-complete enumeration and present as a cross-reference to the onboarding Task. Fail: ID-71 asserts a W9.3 headless guarantee or implements W9.3 tooling.

B. Scope-boundary and graduation invariants

Section titled “B. Scope-boundary and graduation invariants”

  1. (B-INV-17) The ID-71 headless-complete launch scope is exactly {O1/O4/O6 reads + W5.6}; W9.3 is cross-reference only; write-back is sanctioned-destinations-only. Pass: the spec’s scope enumeration matches this set; the Checker confirms no scope creep into net-new capabilities. Fail: scope expands beyond this set.

  2. (B-INV-18) The full agent fleet is post-launch graduation, NOT launch scope. At launch, the headless surface is the {O1/O4/O6 + W5.6} set plus exactly one piloted goose recipe (the MVP pilot: cron → remote-MCP → Claude → one O4 briefing → deliver to one outbound channel + write one propose-row into the queue). Pass: launch ships the headless-complete set + one piloted recipe; no additional fleet agents are launch-gated. Fail: additional fleet agents are required for launch.

  3. (B-INV-19, ⇐ WS-5) The fleet grows additively, per-Task, as ID-104 metrics earn each graduation — each new headless agent graduates via its own Task once its ID-104 quality metric clears the threshold; auto-apply is the per-workflow reward of clearing that threshold (B-INV-7). Pass: fleet additions are Task-gated and metric-gated; no big-bang fleet launch. Fail: fleet agents are added without a Task + metric gate.

  4. (B-INV-20) Net-new product capabilities are NOT ID-71 deliverables — O5 W5.2 sales triggers, O5 W5.3 marketing pipeline, O2 W2.3 renewal packs, O3 W3.1–W3.3 trust trio, O2 W2.2 proposal assembly each graduate to their own Task. ID-71 reserves the surface concepts (A16 source-connection, A22 propose-confirm) only. Pass: none of these capabilities is built under ID-71; each has a reserved concept + own-Task pointer. Fail: ID-71 builds any of them.

    Carried-forward inputs to the O5/O2 own-Tasks (WS-10 / WS-12 — recorded, not built here). Two RESEARCH inputs that must not be lost when these capabilities graduate: (a) W5.2 home assessment (WS-10) — RESEARCH §4.1 found W5.2 (sales-trigger→outreach, O5-consumption) does NOT belong inside the unratified sales-proposal-workspaces Phase-3 drafts (different outcome: O5 intelligence-consumption vs O2 revenue-document-assembly; different data home: the live HubSpot↔Cowork MCP connector, not the sales_proposal_workspaces satellite). W5.2 opens as its own Task, sequenced first in the O5 group; the sales-proposal Phase-3 build is a separate future Task whose four arm-a/arm-b substrate drafts still need Liam ratification + canonical-pipeline reconciliation before adoption. (b) proposal-writer exemplar (WS-12) — the in-repo proposal-writer skill is carried as a named skill-reuse input/exemplar to the O2 W2.2 proposal-assembly thread (NOT to W5.2). Pass: both are recorded as carried-forward inputs to the respective own-Tasks, with W5.2’s home assessment and the proposal-writer exemplar named; neither is built under ID-71. Fail: either is built under ID-71, or silently dropped from the graduation pointer.

  5. (B-INV-21) The MVP pilot proves HC-1 / HC-2 / HC-4 in one slice and is pilot-gated — the single goose recipe (B-INV-18) is the riskiest-assumption-first proof of the headless guarantee; goose is committed as the launch substrate only after the pilot validates the §7 must-be-true assumptions. Pass: the pilot recipe exercises an O4 briefing read (HC-1), a propose-row write (HC-2), and both an outbound push and a queue write (HC-4); goose adoption is gated on pilot success. Fail: goose is committed as the launch substrate without the pilot, or the pilot does not exercise HC-1/HC-2/HC-4.

C. Outcome-first verdict framing (the audit’s unit of analysis)

Section titled “C. Outcome-first verdict framing (the audit’s unit of analysis)”

  1. (B-INV-22, ⇐ WS-11) Verdicts attach to outcomes, not tool names. Every keep-concept / refine / retire / gap verdict in the rationalised surface is recorded against the outcome/workflow the tool serves; renaming or retiring a tool does not change the outcome verdict. Pass: the surface-design record maps each verdict to an O-number / W-number, not (only) a tool name. Fail: a verdict is expressed purely as a tool-name decision with no outcome anchor.

  2. (B-INV-23, ⇐ WS-11) “Keep-concept” means the outcome is retained, not the tool in its current form — a kept concept may ship as a renamed, reshaped, or parameterised entry. Pass: a kept-concept outcome may be served by a differently-named/shaped tool without violating the verdict. Fail: “keep” is read as “freeze the current tool”.

  3. (B-INV-24) Retiring a tool whose outcome survives requires the outcome to be served elsewhere — no outcome in the ranked set (O1, O2, O4, O5, O6) loses its sole affordance through a retire verdict without a consolidation target. Pass: every retire/consolidate verdict names the surviving entry that serves the outcome. Fail: a retire verdict orphans a ranked outcome.

D. Outcome-grouped surface shape (Option C on Option A — §7.5)

Section titled “D. Outcome-grouped surface shape (Option C on Option A — §7.5)”

  1. (B-INV-25, ⇐ §7.5 / RESEARCH §3) The human-facing surface is a single outcome-grouped MCP server (Option A), with Option C’s headless-agent fleet layered on it additively. Option B’s consumption/admin audience-split is deferred until the admin/consumption auth surfaces diverge enough to warrant a second connector. Pass: v1 ships one human-facing server; the fleet is additive on it; no second connector ships at launch. Fail: a second server ships at launch, or the fleet is not additive.

  2. (B-INV-26, ⇐ §7.5) The deferral trigger for Option B is recorded — the consumption/admin split is revisited only when the admin and consumption auth/role surfaces diverge enough to warrant a second connector. Pass: the trigger condition is stated. Fail: Option B is deferred with no revisit trigger.

  3. (B-INV-27, ⇐ WS-7) One outcome-shaped find entry (type / scope / granularity parameterised) serves O1 find/answer and replaces the search trio + find_similar_items (registerSearchTools / findSimilarItemsImpl), unless workflow evidence argues for a named exception. Corpus-level q_a_pairs + scope_tag semantics are preserved as a scope/type param; chunk-vs-item is the granularity param. Pass: O1 find/answer is served by one parameterised entry; the prior trio’s distinct semantics survive as params. Fail: the search trio persists as separate entries with no consolidation, or a preserved semantic (q&a scope, chunk granularity) is lost.

  4. (B-INV-28, ⇐ WS-7 / A21) Ontology-grounded answering (O1 W1.3) is a first-class affordance — entity/ontology grounding (get_entity_relationships, kb://entities) is promoted to a deliberate grounding affordance of the answering outcome, not mis-grouped under content management. Pass: the answering surface exposes an ontology-grounding affordance. Fail: ontology grounding remains a curation-side tool with no answering affordance.

  5. (B-INV-29, ⇐ WS-8) One where-are-we-exposed outcome consolidates the exposure / freshness / coverage / quality / certification reads into the four-layer presentation (B-INV-4), with the resolution loop attached. Pass: exposure is served by one entry in the four-layer shape; the prior exposure reads consolidate into it. Fail: exposure remains fragmented across multiple reads.

  6. (B-INV-30, ⇐ WS-8 / §7.2) One what's-in-my-queue outcome — a single queue concept with a facet, not two outcomes. Content-review and governance-review collapse into one queue concept distinguished by a facet (content-quality vs freshness/ownership governance), not two separate queue outcomes. Pass: the queue is one entry with a facet parameter; content-review and governance items are reachable through the same queue concept. Fail: two distinct queue outcomes ship, or the facet distinction is lost.

  7. (B-INV-31, ⇐ WS-9) One completing-forms surface generalises procurement (the first form type) and folds in W2.4 questionnaire-fill; bid-domain naming retires in favour of forms naming as one coordinated client-contract break (the bid→forms rename lockstep — code + fixtures + bundle + inventory + evals + client guide, {71.3} TECH). Pass: forms work is served by one generalised surface; no user-facing bid-specific entry persists post-cutover. Fail: bid-specific and forms-specific surfaces coexist, or the rename is not a single coordinated break.

  8. (B-INV-32) One get (one-or-many param), one dedup (scope param), one assign (one-or-many param) replace the single+batch pairs (get_content_item/_items, find_duplicate_candidates/find_all_duplicates, assign_content_owner/bulk_assign_owner). Pass: each pair consolidates to one parameterised entry. Fail: a single+batch pair persists as two entries.

  9. (B-INV-33, ⇐ SYNTHESIS §1.3) Two-step retrieval is preserved — list/preview metadata first, verbatim fetch on accept — for the consolidated find and get entries, identical to the ratified platform pattern. Pass: the consolidated entries expose the list/preview → get/verbatim contract. Fail: a consolidated entry returns verbatim content without the preview step where the pattern applies.

  10. (B-INV-34, ⇐ SYNTHESIS §1.3 / RESEARCH §3) Layer placement holds: tools = ability, skills = expertise, apps = visual density + WS-8 resolution surface, commands = thin orchestrators. The 4 MCP Apps remain the visual-density + resolution layer (“Draft content for X” / “Discuss options for Y”); prompts and /kb:* commands become thin orchestrators over the consolidated entries; plugin skills remain the expertise layer. Pass: each surface element sits in its layer per these rules; duplication across layers exists only where the layer adds genuine value. Fail: a command/prompt re-implements tool ability, or an app duplicates a tool with no density/resolution value.

E. Grounding, eval, and AI-invisibility invariants

Section titled “E. Grounding, eval, and AI-invisibility invariants”

  1. (B-INV-35, ⇐ RESEARCH §5.1) Every AI touchpoint uses exactly one of the three grounding shapes — structured outputs (output_config.format), forced-tool strict extraction (strict: true + recursive additionalProperties: false), or citations over search_result blocks — chosen per touchpoint; citations and structured outputs are never combined in one call (the 3-pass draft.ts split stays forced). Pass: each touchpoint declares and uses one shape; no call combines citations with output_config.format. Fail: a touchpoint mixes citations with structured outputs, or declares no grounding shape.

  2. (B-INV-36, ⇐ RESEARCH §5.1) No silent fallback at structured touchpoints — stop_reason: "refusal" and "max_tokens" are handled explicitly (log + surface), never swallowed by a bare try/catch default; assistant prefills are never used. Pass: every structured touchpoint surfaces refusal/max-tokens explicitly; no silent default-on-error path. Fail: a touchpoint silently substitutes a default on refusal/error.

  3. (B-INV-37, ⇐ RESEARCH §5.2) outputSchema (bl-26) is the forward standard for new entries only — new outcome-shaped entries declare an outputSchema where it fits the use case; it is NOT retrofitted onto retiring/changing tools. Pass: new entries carry outputSchema where applicable; retiring tools are not retrofitted. Fail: a retiring tool is retrofitted, or a new entry omits outputSchema where it clearly fits.

  4. (B-INV-38, ⇐ RESEARCH §5.4) A tooling change forces a skill + eval/fixture update — any change to a tool / prompt / plugin skill / inline touchpoint forces a create-skill/update-skill invocation AND an eval/fixture update, enforced by guard tests (the inventory-parser / fixture-sync / recordAiCall() grep-guard pattern extended to prompts and skills). Pass: a tooling change with no corresponding skill/eval/fixture update fails a guard test. Fail: a tooling change merges without the forced updates.

  5. (B-INV-39, ⇐ SYNTHESIS §1.3 / ai-visibility-policy) AI-invisible-infrastructure holds — AI-driven enrichments (classification, summarisation, intelligence scoring) do not appear as user-facing AI features; the platform behaves as if the data was always there (admin Provenance carve-out aside). Pass: consumption surfaces present enriched data as native, not as “AI generated this”; only the admin Provenance surface exposes the enrichment lineage. Fail: a consumption surface advertises an AI enrichment as a feature.

  6. (B-INV-40, ⇐ RESEARCH §5.1) Schema enforcement is not semantic correctness — a touchpoint passing its schema/strict-decoding constraint is still gated by its ID-104 eval; the eval, not the schema, is the quality gate. Pass: every grounded touchpoint has an ID-104 eval in addition to its schema constraint. Fail: a touchpoint relies on schema enforcement alone as its quality gate.

F. Carried PI-items (acknowledge, not necessarily resolve)

Section titled “F. Carried PI-items (acknowledge, not necessarily resolve)”

  1. (B-INV-41) PI-13/PI-14 (MCP plugin branding / connector-ref rename + runtime/CI sweep + deploy-gate check-name) is a PRODUCT-scope consideration: the rationalised surface MUST NOT inherit stale plugin branding / connector references; there are no live client connectors today, so the rename is a clean break. Pass: the surface-design record acknowledges PI-13/PI-14 as part of the rename lockstep. Fail: stale branding is silently inherited.

  2. (B-INV-42) PI-15 (per-tenant point-of-use derived-artefact generation — taxonomy-sync) is RETIRED (ratified 2026-06-14, OQ-4): verified BROKEN since the {68.23} prompt relocation, it is retired in favour of the kb://taxonomy resource (which already absorbs bl-52) serving grounded taxonomy access — conditional on a one-line confirmation that no live consumer depends on the broken per-tenant path (expected: none). Pass: the surface-design record carries PI-15 as RETIRED with the no-live-consumer confirmation and kb://taxonomy named as the replacement. Fail: PI-15 is treated as a working surface, or retired without the no-consumer check.

G. Deferred-with-anchor outcomes (recorded so they are not lost)

Section titled “G. Deferred-with-anchor outcomes (recorded so they are not lost)”
  1. (B-INV-43, ⇐ WS-3 / strawman O8 rank-8 / RESEARCH §2.5) O8 W8.4 argument-quality checking is a WANTED tooling affordance, recorded DEFERRED-WITH-ANCHOR — not a launch deliverable. WS-3 ratified argument-quality checking (W8.4) as wanted tooling, and the strawman ranks O8 (guides / knowledge-product authoring) at rank 8; RESEARCH §2.5 keeps the existing guide tools (list_guides / get_guide / create_guide / update_guide, plugin skill guide-builder — all O8 W8.1). But the W8.4 argument-quality affordance (an O8-side quality check over a drafted guide/argument) has no current surface and is NOT a launch B-INV: at rank 8 it sits below the O1/O4/O6 launch set and the O5/O9 differentiators. It is recorded here with a numbered anchor so it is not lost — it graduates as an O8 affordance in a later group (own-Task or a guide-tooling Task), born against an ID-104 eval (B-INV-13/40) when it lands. Pass: the surface-design record carries W8.4 argument-quality as a numbered deferred-with-anchor outcome with an own-Task/later-group pointer and the born-evaluable requirement noted. Fail: W8.4 is silently dropped, OR pulled into the ID-71 launch set without a ratified scope change.

Open questions

Section titled “Open questions”

RESOLVED 2026-06-14 (Liam): all four OQs below are ratified — see the per-OQ RESOLVED banner under each heading. The three carried items were the headline ratification items, settled early so {71.3} TECH and the implementation waves proceed without re-litigation. Each states the decision needed, 2–3 concrete options, a recommended default, and the downside/risk of each option. (The two-queue question, Option-C-on-A, and the headless contract are already RESOLVED — RESEARCH §7 / headless-requirement-refinement.md — and are asserted as behaviour above, not re-opened here.)

OQ-1 — create_content_item ingest shape for headless agents

Section titled “OQ-1 — create_content_item ingest shape for headless agents”

RESOLVED 2026-06-14 (Liam): Option A — write-to-canonical-store. The headless create verb is a propose-into-canonical-store affordance (writeBackFileFirst, a sanctioned HC-4 destination); the canonical pipeline then materialises the content_items row. TECH-GATE (binding on {71.3}): re-check the canonical-pipeline cutover state — if file-first ingest is NOT the live path at TECH time, fall back to Option C (defer the create verb to the onboarding Task). Net-new uncontrolled ingestion remains the WS-6 anti-goal regardless.

Decision needed. Given the canonical-pipeline re-ingest cutover state (re-ingest is the cutover gate on the canonical-pipeline theme; ID-71 is parallel pre-launch, NOT a re-ingest gate), what is the ingest contract a headless agent uses to create a content item? The current create_content_item reflects the retired inline classify+embed+chunk model; the canonical reality is external-folder-as-canonical-store (ID-101/ID-45), where ingestion is the pipeline’s job, not an in-request tool’s.

  • Option A — Write-to-canonical-store (recommended default). A headless agent “creates” a content item by writing the source file into the controlled local-fs canonical store (the writeBackFileFirst path, a sanctioned HC-4 destination); the canonical pipeline then picks it up, classifies, embeds, and materialises the content_items row. The MCP entry is a propose-into-canonical-store affordance, not an inline enrichment tool.
    • Downside/risk: introduces pipeline-pickup latency between “agent creates” and “item is queryable”; the agent’s create is eventually-consistent, not immediate. Requires the canonical pipeline to be reliably running for the agent’s create to complete. Depends on the cutover state being far enough along that file-first ingest is the live path.
  • Option B — Propose-row-only (queue-mediated). The agent never writes the canonical store directly; it creates a propose-row describing the intended content item into the WS-8 queue, and a human (or a graduated, ID-104-earned workflow) confirms it into the pipeline. Fully WS-5 propose-only.
    • Downside/risk: always requires a confirm step for net-new items (slower; not zero-human for true net-new content — though net-new ingestion is exactly the WS-6 anti-goal, so this may be correct); does not give headless agents a true “create” verb.
  • Option C — Defer the create verb to the onboarding Task. ID-71 ships no agent-facing create_content_item; all net-new ingestion is owned by the onboarding/O9 Task (local-first, WS-6-gated), and ID-71’s headless agents only read + propose against existing items.
    • Downside/risk: leaves a visible gap in the headless surface (agents can propose resolutions but cannot originate content); may be the cleanest scope boundary but pushes a capability clients may expect into a later Task.

Recommended default: Option A (write-to-canonical-store as a propose-into-store affordance) if the canonical-pipeline cutover state at {71.3} TECH time has file-first ingest live; fall back to Option C (defer to onboarding Task) if cutover is not far enough along, since net-new uncontrolled ingestion is the WS-6 anti-goal regardless. Dependency flag for {71.3} TECH: this choice is gated on the canonical-pipeline cutover state and MUST be re-checked at TECH time, not assumed from this spec.

OQ-2 — Renewal-packs (W2.3): launch horizon + outcome grouping

Section titled “OQ-2 — Renewal-packs (W2.3): launch horizon + outcome grouping”

RESOLVED 2026-06-14 (Liam): Option A — later horizon, grouped with O2 W2.2 proposal-assembly. W2.3 renewal-packs are post-launch (Group 2), grouped with the proposal-assembly Phase-3 build as one O2 revenue-document-assembly family (shared composer/export). Validate the Emma / customer-success persona before investment (WS-3 pattern).

Decision needed. Renewal packs (W2.3) are a confirmed own-Task candidate (net-new product capability: assembly + per-client sector context; Emma / customer-success persona). PRODUCT must confirm (a) horizon — launch-adjacent or later? — and (b) grouping — which outcome family it belongs to, and whether it groups with the O2 proposal-assembly Phase-3 build (W2.2).

  • Option A — Later horizon, grouped with O2 proposal-assembly (recommended default). Treat W2.3 as post-launch, in Group 2 (after the Group 1 differentiators O9 / W5.2), and group it with the O2 W2.2 proposal-assembly Phase-3 build — both are O2 revenue-document assembly + export capabilities sharing the composer/export machinery.
    • Downside/risk: couples two unspecced builds; if the proposal-assembly Phase-3 build slips, renewals slip with it. Emma persona is currently unpersonified, so grouping rests on a not-yet-validated user.
  • Option B — Later horizon, own standalone Task (not grouped with W2.2). Keep W2.3 post-launch but as a standalone Task, because renewal packs carry distinct per-client sector context and a distinct customer-success trigger that proposal assembly does not.
    • Downside/risk: duplicates assembly/export machinery across two Tasks if they do in fact share it; more Tasks to sequence.
  • Option C — Launch-adjacent (Group 1). Pull W2.3 forward to launch-adjacent because renewals are recurring revenue and a concrete near-term client need.
    • Downside/risk: it is entirely unspecced and net-new; pulling it into launch scope inflates launch and contradicts WS-2 (net-new capabilities graduate to own Tasks, not v1).

Recommended default: Option A — later horizon (Group 2), grouped with the O2 W2.2 proposal-assembly Phase-3 build as an O2 revenue-document-assembly family, both own-Task, both post the Group 1 differentiators. Note the Emma persona needs validation before investment (WS-3 pattern).

OQ-3 — O3 trust-trio (fact-check / feature-ingest / case-study-push): grouping + sequence

Section titled “OQ-3 — O3 trust-trio (fact-check / feature-ingest / case-study-push): grouping + sequence”

RESOLVED 2026-06-14 (Liam): Option C — fact-check first, defer the rest (Liam’s call; differs from the recommended Option A). W3.1 fact-check-on-demand is pulled forward to Group-1-adjacent — “answer with citations I trust” (O1/O3) is the #1 ranked outcome and fact-check directly reinforces it. W3.2 feature-ingest/supersession + W3.3 case-study-push are deferred to a later group. This is a roadmap-sequence decision only: W3.1 remains a net-new own-Task (B-INV-20), NOT a member of the headless-complete launch set (B-INV-1 / B-INV-17).

Decision needed. The O3 trust trio — W3.1 fact-check on demand (A17), W3.2 feature-ingest with supersession (A20), W3.3 case-study push — are all client-promised and all unbuilt. PRODUCT must confirm (a) grouping — one “trust maintenance” Task or split into separate Tasks — and (b) sequence — where they sit relative to O5/O9. Priority is lower than O5/O9 because O3 is partly inherited from the pipeline (WS-1: controlled local-fs source + automatic change pickup engineer much of v1 trust at the ingestion point).

  • Option A — Split into two Tasks by mechanism, sequenced in Group 2/3 (recommended default). Split (i) supersession/feature-ingest (W3.2, A20 — a lineage/version capability that rides the existing document-diff/versions substrate) from (ii) fact-check-on-demand + case-study-push (W3.1 + W3.3 — answering/retrieval-shaped affordances). Sequence both after the Group 1 differentiators (O9, W5.2) and the O5 W5.3 marketing build — i.e. Group 2/3.
    • Downside/risk: two Tasks to sequence; the split point (lineage vs answering) is a judgement that could fragment a coherent “trust” story for the client.
  • Option B — One “trust maintenance” Task (all three together), Group 2/3. Keep the trio as a single coherent trust-maintenance Task so the client-facing “we keep your knowledge trustworthy” story ships as one unit.
    • Downside/risk: mixes three quite different mechanisms (on-demand check, ingest+supersede, outbound push) in one Task; larger, harder to decompose, slower to first value.
  • Option C — Fact-check first (Group 1-adjacent), supersession + case-study later. Pull W3.1 fact-check forward because “answer with citations I trust” (O1/O3) is the #1 ranked outcome and fact-check directly reinforces trust; defer W3.2/W3.3.
    • Downside/risk: O3 is explicitly lower priority than O5/O9 (partly pipeline-inherited), so pulling fact-check into Group 1 competes with the differentiators for scarce launch attention.

Recommended default: Option A — split by mechanism into two own-Tasks (supersession/feature-ingest vs fact-check + case-study-push), both sequenced Group 2/3 after the O5/O9 differentiators, on the WS-1 rationale that O3 v1 trust is largely pipeline-inherited so the trio is reinforcement, not launch-critical.

OQ-4 (surfaced, lower-stakes) — PI-15 taxonomy-sync retire-or-repair

Section titled “OQ-4 (surfaced, lower-stakes) — PI-15 taxonomy-sync retire-or-repair”

RESOLVED 2026-06-14 (Liam): Option A — retire. PI-15 per-tenant taxonomy-sync is retired; the kb://taxonomy resource (absorbs bl-52) serves grounded taxonomy access. Conditional on a one-line confirm that no live consumer depends on the broken per-tenant path (expected: none). Folded into B-INV-42.

Decision needed. PI-15 (per-tenant point-of-use derived-artefact generation — taxonomy-sync) is verified BROKEN since the {68.23} prompt relocation. Is it repaired (restore per-tenant taxonomy-sync as a working point-of-use derived artefact) or retired (the canonical pipeline / kb://taxonomy resource absorbs the need, per RESEARCH D5 noting the taxonomy resource absorbs bl-52)?

  • Option A — Retire (recommended default). Retire the broken taxonomy-sync; let kb://taxonomy (which already absorbs the bl-52 taxonomy resource) serve the need. Lowest carrying cost; aligns with outcome-first (the outcome — grounded taxonomy access — is served by the resource).
    • Downside/risk: if any live consumer depends on the per-tenant point-of-use artefact specifically (not the resource), retiring it removes that affordance. Needs a quick check that no live consumer depends on the broken path (likely none, given it’s been broken since {68.23}).
  • Option B — Repair. Restore per-tenant taxonomy-sync as a working derived artefact.
    • Downside/risk: repair cost for a surface that’s been broken without apparent impact; risks re-inheriting a pre-pipeline mechanism the canonical reality has superseded.

Recommended default: Option A — retire, conditional on a one-line confirmation that no live consumer depends on the broken per-tenant path (expected: none).

End of {71.2} PRODUCT. HC-1..HC-6 restated as B-INV-1..16 (1:1, HC-cited); §7 dispositions (one-queue+facet, Option C on A) asserted as B-INV-30 / B-INV-25; scope boundary as B-INV-17..21; outcome-first verdict framing as B-INV-22..24. Three carried items (OQ-1 create_content_item, OQ-2 renewal packs, OQ-3 trust trio) plus OQ-4 (PI-15) collected for Liam’s ratification. Feeds {71.3} TECH (a fresh Planner instance) for the migration plan + per-invariant proposed changes.

AMENDMENT (15/06/2026 — second fix-pass, for re-ratification). Invariant count is now 43 (was 42). New: B-INV-43 (§G deferred-with-anchor) — O8 W8.4 argument-quality checking recorded as a WANTED-but-deferred affordance with an own-Task/later-group anchor. B-INV-20 amended (not renumbered) to record the WS-10 W5.2-home assessment + WS-12 proposal-writer exemplar as carried-forward inputs to the O5/O2 own-Tasks. No behaviour change to B-INV-1..42; the amendment adds one deferred-with-anchor invariant and a carry-forward note. Sections touched: §B (B-INV-20), new §G (B-INV-43). {71.3} TECH §M maps B-INV-43 to a deferred anchor (no launch M-change).

AMENDMENT (17/07/2026 — five-layer → four-layer sync, {71.32} close-out). B-INV-1, B-INV-4, and B-INV-29 amended (not renumbered) to read the four layers (data you have → how you could use it today → the gaps → the opportunities), not five. ID-131.19 deliberately trimmed the former “its quality” layer from where_are_we_exposed: its sole RPC, get_quality_issue_counts, was dropped at M6 and deliberately not re-pointed (lib/mcp/tools/dashboard.ts:1-10), and B-INV-4 now cites this so the trim is not re-litigated. This syncs the spec to already-shipped behaviour — the eval fixture (FOUR_LAYER_ORDER, scripts/mcp-eval/headless-complete-set.ts) and the FC-95 functional-correctness assertion already asserted four layers before this amendment. No other invariant text changes. Sections touched: §A (B-INV-1, B-INV-4), §D (B-INV-29).