Skip to content
Canonical

Phase 0.9 — Context Anchor

Phase 0.9 — Context Anchor

Section titled “Phase 0.9 — Context Anchor”

Purpose: durable reference of cross-cutting context that ALL Phase 0.9 documents and any agent doing implementation-phase work MUST read before editing. Captures the North Star, ratified OQ states (post-S228 through S231), graphify-feedback context to preserve, and the Claude-API research URLs for the OQ1 edit-flow investigation.

Status: living anchor. Append, do not replace, when new context anchors emerge. Audit date: 2026-05-11 (S231 refresh) Branch: content-items-investigation Phase status: Phase 0 investigation complete. Phase B core-docs refresh in progress (this doc → decision-graph restructure → collapse-candidates refresh → split intended-architecture into lean sections). Phase C (Taskmaster install + seed) follows.

1. North Star (from ai-strategy doc, ratified by Liam S228)

Section titled “1. North Star (from ai-strategy doc, ratified by Liam S228)”

This is the strategic frame ALL Phase 0.9 architectural choices serve. Anything that contradicts this needs explicit justification.

1.1 Core Proposition

Section titled “1.1 Core Proposition”

The knowledge base IS the product. Bids are the first application; the same structured data will power sales proposals, compliance, training, and other use cases. The navigation and information architecture must lead with the KB.

1.2 “Everyone Ends Up Working Within an LLM”

Section titled “1.2 “Everyone Ends Up Working Within an LLM””

A strategic insight from the product owner (Session 62 brainstorm, §11.2 of State of the Product): most users already work within Claude Desktop, Claude.ai, Cowork, or similar LLM interfaces. Knowledge Hub’s job is to facilitate that — structuring data so AI can access it effectively, not competing for screen time.

This means:

  • Claude is the primary AI interface — where most AI-powered interaction happens day-to-day. Users ask questions, get briefings, draft responses, and analyse coverage from within Claude.
  • The web app is the management layer — where users browse, edit, review, configure, and curate the golden-source knowledge base.
  • We don’t compete, we complement — Knowledge Hub’s value is in the data layer and API surface, not in building Claude’s equivalent inside the web app.
  • We adopt and customise, not reinvent — Anthropic and the ecosystem release plugins, skills, and commands regularly. We leverage existing patterns (enterprise-search, sales, operations) and customise for our domain.

Implications for current architecture work:

  • “AI consumer first” lens — design data structures for LLM tool-use efficiency before web-UX ergonomics.
  • Cocoindex / mempalace / pullmd / skill-seekers adoption is consistent with “adopt and customise, not reinvent.”
  • MCP tool surface is primary product surface; web-app is management layer. Capability gaps in MCP are higher-priority than capability gaps in web-app.
  • “Everyone Ends Up Working Within an LLM” makes external-folder-canonical (Q2.1) compelling — Claude can already read folders, no need for KH to re-host content.

2. OQ ratifications (post-S228 → S231 — locked unless new evidence)

Section titled “2. OQ ratifications (post-S228 → S231 — locked unless new evidence)”

Cumulative state across S228 (principle ratifications) + S229 (spike outcomes) + S230 (spike outcomes) + S231 (Q&A predetermined-shape + budget-terminology-dropped + MCP-actions-pending). These OVERRIDE any “PROVISIONAL” / “OPEN” tags carried forward from earlier sessions.

OQStatusDetail
OQ1 (Q2.9 write-back)FULLY-RATIFIED S229Principle (S228): one golden record, two-way semantics. Implementation (S229): per-UC Candidate A/B/C set ratified — UC1/UC2/UC4 Candidate A (in-platform + filesystem write); UC3 two-variant (A find-replace + B smart-agent); UC6 AI-suggest Candidate B (Claude API revision draft); UC7+10 cocoindex native; UC8 v1 Candidate A + LLM-reasoning, v1.1 Candidate C upgrade; UC9 KH-native (no candidate). See 0.9-edit-flow-investigation.md §6. §4 below preserved for historical research-material reference.
OQ2 (CX.28 onboarding)RATIFIEDFolder connection REQUIRED at first-run for v1.
OQ3 (CX.29 SMB data-fix)RATIFIEDCritical framing for v1; dedupe-with-temporal as the sole v1 feature; remaining items review post-architecture. Substrate ratified S230 as hybrid (a)+(c) per S10.
OQ4 (Q4.11/DW.4 mempalace)ADOPTION-CONFIRMED (Lens 1)Lens 1 dev workflow confirmed via S3 + S15 (v3.3.5 with mempalace_search FIXED via PR #1396). Lens 2 memory replacement still pending post-launch validation. S231 OQ raised: is the v4-alpha PG backend available to inspect on the mempalace GitHub repo? (Track at S15; PRs #665 + #1337.)
OQ5 (DW.6 mcp-scan)RATIFIED-YESAdopt snyk-agent-scan (package renamed). v1 CI step in inspect mode; v2 cloud deferred. S231 caveat: MCP-action list (across S6 + S15 + intended-arch §12.1) needs Liam refine/remove/extend pass before any tool registrations land.
OQ6 (CX.7 agent-browser)RESOLVED-NO-SWAP S229S11 spike: keep Playwright. agent-browser fails Cloudflare + body-completeness (14/20 vs 20/20). Playwright surface lives in pullmd Tier-3 sidecar.
OQ7 (CX.24 EP8)OPEN-WITH-NOTEEP8 spec likely needs rework after architecture progresses; not yet re-specced.
OQ8 (DW.10 doc-drift)OPEN-PENDING-INVESTIGATIONCheck skill-seekers for ready-made solution before closure.
OQ9 (DW.12 token-reduction)MOVED-TO-PROD-READINESS-TRACKupdate-docs/handoff token reduction handled in production-readiness track.
OQ10 (S16 Q&A canonical shape — NEW S231)RATIFIED-PREDETERMINED-MARKDOWNv1 Q&A ingestion uses a predetermined markdown shape (YAML-frontmatter per pair) that KH defines pre-ingestion. Existing Phew historical shapes (5 catalogued in S16 §4) migrate once via one-shot tooling under scripts/qa-migration/; not a recurring v1 path. Pattern A/B docx extractor + markdown_heading_v1 + LLM-extraction = migration helpers, not v1 ingestion adapters.
OQ11 (S231 — forms question-extraction strategy)OPENHow were Standard Selection Questionnaire + Charnwood ITT Services question sets extracted historically? What’s the intended forward path for forms (Shape F: XLSX/PDF) so they can match against q_a_pairs at bid time? Coupled with Pattern A/B parser post-migration fate (Q3.5 [RATIFY-AT-REVIEW]).
OQ12 (S231 — Q1.13 workspace scoping)DEFERRED-TO-WIDER-SCHEMA-DECISIONWorkspace scoping for q_a_pairs (and broader workspace/multi-tenant decisions) bundled into a single wider schema-design pass, not resolved at the S16 level.
OQ13 (S231 — pre-re-ingest evaluation)NOT-REQUIRED-AS-GATENo further pre-re-ingest evaluation required as a gating step. Re-ingest happens against the refreshed architecture and is observed as it lands. S7 spike reframed as observation rather than gate.

3. Graphify-feedback context (preserve across all rewrites)

Section titled “3. Graphify-feedback context (preserve across all rewrites)”

Liam flagged graphify-evaluation-feedback.md as containing helpful context not to lose. Full preservation list:

  1. Initial Thoughts — Use graphify to identify Phase 0.2.5 gaps + prevent BNW issues; backup full codebase + docs graphs before re-ingestion (already done — 6 baselines committed).
  2. §5.2.A.(i) — “I like the idea of a new ‘Knowledge Map’ user-facing primitive.” → reclassify OPS-G-1 from DEFERRED to PROVISIONAL.
  3. §5.2.A.(ii) — Want client-docs comparison data first before committing → S7 spike (pre-re-ingest evaluation) covers this.
  4. §5.2.B — Graphify MCP evaluation as part of broader MCP audit (which is itself underway).
  5. §5.2.C — “We should be adopting Graphify’s confidence-label taxonomy” — distinct decision separate from Q4.7 KG-provenance enum. Add as new Q4.14.
  6. §5.2.D — Bid library content / bids → markdown DB storage (relates to Q1/Q2). Now is the time to make that change pre-launch.
  7. §5.2.E — Graphify semantic-extractor as Pass1/Pass2 replacement candidate (relates to Q3.4 derivation engine).
  8. Next Steps § — Investigate graphify extract.py + cache.py for direct re-use vs reinvention.
  9. Local LLM eval list — DeepSeek-V4-Pro / openai/privacy-filter / gemma-4-31B-it / NVIDIA-Nemotron-3-Super-120B-A12B-BF16 / Nemotron-3-Nano-Omni-30B-A3B-Reasoning-BF16 (HuggingFace) — for evaluation post-architecture.
  10. Client-provided CSP checklist — now in docs/client-documentation-base/forms/Cloud Security Principles Checklist V5_3 - PHEW.xlsx — the platform should auto-complete most fields with citations. Use as auto-completion eval target in S7 / S8 / future scoring runs.

4. OQ1 edit-flow investigation — research material (historical reference)

Section titled “4. OQ1 edit-flow investigation — research material (historical reference)”

OQ1 implementation is FULLY-RATIFIED S229 per 0.9-edit-flow-investigation.md §6 — the per-UC Candidate A/B/C set is locked. This section is retained as historical reference for the candidate framings + Claude API URLs that informed the investigation.

Investigation mapped:

  1. Use cases for source-file edits — single word fix / date change / sweeping change across many docs / paragraph rewrite / etc.
  2. Data flows — work back from required outputs.
  3. Implementation candidates:
    • In-platform editor + version bump on underlying source file
    • Claude API with tool use to edit underlying files
    • Managed Agents — dedicated documentation agents triggered to update folder content
  4. Conflict + dedup detection — cocoindex pipeline + mempalace / skill-seekers / graphify.

Claude API research URLs:

The text-editor-tool is the most direct enabler for Claude API → underlying-file-edit (UC6 AI-suggest Candidate B per edit-flow §6.6 RATIFIED).

5. Canonical baseline corpus

Section titled “5. Canonical baseline corpus”

docs/client-documentation-base/ is the canonical test corpus for spike phase (replaces ad-hoc /tmp/cocoindex-spike/ fixtures in 0.9-spike-plan.md §S2 + §S8).

Structure:

  • binary/ — 4 final docx + 3 DRAFT docx + 1 PDF (Telehouse fact-sheet). Drafts originally had track-changes; exercise both dedup-with-temporal and docx_utils.open_document_safe() flows.
  • markdown/ — 13 numbered company-context .md (Phew-internal corpus) + 4 final audit .md + 3 DRAFT .md + 4 bid library .md (different shapes for different chunking strategies).
  • forms/ — Cloud Security Principles Checklist V5_3 - PHEW.xlsx + standard-selection-questionnaire-ppn-03-24.pdf — exercise question-extraction + auto-completion for forms a real client would hand us.

Use in spike plan:

  • S2 (cocoindex folder binding) — primary baseline.
  • S7 (pre-re-ingest evaluation) — query the corpus for client-relevant questions (LBBD-CSP context, FUNC-XXX, etc.).
  • S8 (Q&A flow validation) — exercise ingest → q_a_extractions → curation → retrieval → citations on real shapes.

6. Audit findings reference (historical)

Section titled “6. Audit findings reference (historical)”

The S228 decision-graph audit found 8 inaccuracies + 7 gaps; corrections landed S228. The S230 spike outcomes (S1, S10, S14, S15, S16) further updated decision states. The S230 synthesis verification audit + S16 verification audit catalogued additional cleanup items applied in S231. No further audit-driven rewrites are scheduled — Phase B core-docs refresh proceeds from current state, not from audit punch-lists.

For traceability, the prior audit catalogues are preserved in:

  • 0.9-synthesis-verification.md (S230 audit of 0.9-synthesis.md)
  • 0.9-spike-S16-verification.md (S230 audit of S16 spike)
  • 09-synthesis-and-verification-feedback.md (S231 Liam-feedback file, applied)

7. Phase B baseline scope (S231 anchors)

Section titled “7. Phase B baseline scope (S231 anchors)”

Phase 0 investigation work is complete. The codebase is moving to planning / design / implementation phases. The following anchors apply to all Phase B refresh work + downstream specs:

7.1 Budget + timeline + spike-confidence terminology DROPPED

Section titled “7.1 Budget + timeline + spike-confidence terminology DROPPED”

Per S230 (timelines) + S231 (budgets, spike-related confidence figures), Phase B docs and downstream specs drop:

  • Week-count Phase 2 effort estimates (e.g. “6-8 weeks architecture-impl”).
  • Day-count work-item estimates (e.g. “~5-7 days hybrid”, “~19-27 days impl”).
  • “Wall-clock concurrent” framing.
  • Per-spike “Spike confidence: X%” claims.
  • “Overall confidence: X%” rollups.

We are not under time-pressure; AI-paired velocity invalidates the dev-week / dev-day terminology that the inherited spike-plan and 0.8.2-cocoindex-evaluation used. Ordering and dependencies between sub-streams ARE retained; concrete day-counts are not.

7.2 Q&A ingestion = predetermined markdown shape

Section titled “7.2 Q&A ingestion = predetermined markdown shape”

KH defines the v1 canonical Q&A wire format pre-ingestion (YAML-frontmatter per pair). All future Q&A authoring (Phew + future clients) lands in canonical shape from day 1. Existing Phew content (5 historical shapes) migrates once via one-shot tooling under scripts/qa-migration/; not a recurring v1 path. The “5 adapter codepaths” / “hybrid template + accept-any” framing in earlier S16 drafts has been retracted; see S16 §7.

7.3 Three-column entity_relationships extension (S3 + S12 reconciliation)

Section titled “7.3 Three-column entity_relationships extension (S3 + S12 reconciliation)”

Per S3 §5 line 502: three columns, three distinct semantics, no collision —

  1. confidence numeric(3,2) (numeric signal — retained from existing schema).
  2. provenance enum (EXTRACTED / INFERRED / AMBIGUOUS — graphify confidence-label taxonomy, Q4.14).
  3. adapter_name text (extractor identity).

Pass 2’s classification_confidence + graphify’s provenance + mempalace’s kg_confidence are converging-but-distinct; the three columns keep them isolated.

Section titled “7.4 MCP-related actions NOT-YET-APPROVED”

Across S6 (snyk-agent-scan CI), S15 (mempalace MCP changes), and intended-arch §12.1 (check_content_duplicates + other new tools), the MCP-tool surface has accumulated proposed registrations + revoke-execute migrations + scope changes. None of these is approved. Phase B includes a Liam review pass on the MCP action list with refine/remove/extend dispositions; no MCP-tool migrations land until that pass completes.

7.5 Architecture coupling references

Section titled “7.5 Architecture coupling references”

These cross-doc dependencies are load-bearing for any Phase B sub-doc:

  • UC8 v1 cross-record dedup substrate = HYBRID (a)+(c) per S10 §9 — cocoindex @coco.fn chunk-embedding + skill-seekers-inspired keyword co-confirmer. Per-tenant rules via WP-DEDUP-RULES coordinated with OPS-X-SCOPE-TAGS.
  • Cocoindex Cloud Run topology = single-orchestrator + ephemeral per-instance LMDB per S14. No queue infra.
  • pullmd HTML/CF/GN/Reddit + skill-seekers pdf_scraper for PDF (S231 framing — replaces Jina-PDF). Drop Firecrawl.
  • Mempalace Shape A + B + C confirmed; miner = wrong tool for KH Q&A; KH retains Pass 2.
  • Bulk operations, content CRUD, soft delete → NOT COLLAPSING (S231 feedback). 3rd-party tool for source-document explorer (TBD which). Knowledge Map = Cocoindex, not Graphify.

7.6 What’s coming in Phase B

Section titled “7.6 What’s coming in Phase B”

Phase B sequential refresh, each doc lean (drop “X was discounted” historical context):

  1. This doc (0.9-context.md) — frame-setter, just landed.
  2. 0.9-decision-graph.md restructure into 3 certainty tiers (CERTAIN / VERIFY-AGAINST-RECENT-DOCS / OUTSTANDING-OR-AMBIGUOUS).
  3. 0.9-collapse-candidates.md refresh per §7.5 (with Graphify dev-workflow verification of “not collapsing” items).
  4. Split 0.9-intended-architecture.md into lean sections under architecture/: vision-mission, data-flow, tech-stack, workspace-types, qa-flow, mcp-tooling, collapse-list, new-features, diagrams.

Phase C: install Taskmaster + seed task tree from the lean architecture docs.

8. Anti-patterns to avoid (inherited from S227 lessons; still binding)

Section titled “8. Anti-patterns to avoid (inherited from S227 lessons; still binding)”
  • Synthesis-in-isolation — never run multiple parallel sub-agents on cross-dependent rewrites. Sequential only, with main session reviewing between each.
  • Carrying forward “RESOLVED” without re-reading source — every “RESOLVED” tag must remain traceable to a verbatim quote (spike report, edit-flow ratification, or S228-S231 feedback file).
  • Cross-doc drift — every cross-doc reference must be checked bidirectionally during refresh. After decision-graph restructure, architecture-split sub-docs re-verify; after architecture-split, spec-derivation re-verifies.
  • Provisional decisions silently becoming load-bearing — [RATIFY-AT-REVIEW] tags must remain visible in refreshes. Don’t drop them just because they look settled.
  • Re-introducing budget / day-count terminology (S231) — drop on sight. Sub-stream ordering and dependencies are the load-bearing facts.

End of context anchor. Required reading for any agent doing Phase B refresh or downstream implementation work.