Target-State Architecture — ID-68 Repo Visibility / IP Separation (Reconciled)

Target-State Architecture — ID-68 Repo Visibility / IP Separation (Reconciled)

Authored S301a-7 (2026-06-05) by Claude + Liam. Forward design — supersedes the conflated relocation corpus and becomes the canonical architecture for the public switch. It resets to the corrected model; it does not reconcile the old docs line-by-line.

Supersedes (topology + routing): RELOCATION-INVESTIGATION.md, RELOCATION-INVESTIGATION-V2.md, RELOCATION-IMPLEMENTATION-PLAN.md (Option S-B), DEPLOY-OVERLAY-DESIGN.md topology, DOCS-RELOCATION-SUBTASK.md. Integrates (still valid): PRE-FLIP-DEID-PLAN.md (de-ID of genuine client content), guard-CI + knip work, the GitHub-App + sibling-checkout bridge pattern. Evidence base: S301a-7 research wave (8 read-only investigations).

---

0. Operating principle — cutover, not big-bang

Build the corrected architecture in parallel with the running canonical track. Canonical continues as-is (on ledger-cli, single-repo) until each new mechanism is integrated + tested, then cut over. No mechanism flips until its replacement is proven.

0.1 Current migration state (updated S301a-8 close — relocation LANDED)

Repo / dir	State (S301a-8)	Pending
knowledge-hub (public code)	docs-site/ + .planning/ deletions COMMITTED on canonical-pipeline-setup (9b1e5aaf, Liam-directed — no other active work on the branch; destinations verified committed first) + docs-site-deploy.yml deleted (CI dangler) + CLAUDE.md repoints + GitNexus count-strip. Tree clean, pushed	Docs subfolders still duplicated here (intentional — until the bridge + ID-20 cutover, PRODUCT Inv 23). AGENTS.md docs-authoring block knowingly stale (Inv-19 sweep)
knowledge-hub-docs-site (private)	Content tracked (f9c92ba2 — gitignore fixed, 627 files, 584 renames); sync model retired + corpus frontmatter-normalised (510 files) + 4 spaces registered; build green 617 pages; vitest 63 pass/1 documented skip (1ad3e1cf); GitHub repo renamed knowledge-hub-docs-site, remote repointed, pushed	Move docs-site → repo root + strip root harness (entangled with the eval-lane split, PRODUCT Inv 7 — post-ratification TECH slice); repoint Vercel (tied to root-move); 47-broken-internal-link debt (IA pass)
knowledge-hub-archive (cold-storage)	git init + initial commit 08c51dd (S301a-7, local)	optional private GitHub remote; optional separate opt-in gitnexus/ccc index

---

1. The correction (why this doc exists)

The prior corpus conflated two distinct private destinations:

1. The docs-site (ID-9, Astro Starlight) — private, dev-team-only, holds ALL docs, kept in sync with code (Warp model). ID-9 PRODUCT: “platform-team-facing… internal-team-facing”; include-by-default over the whole docs/ corpus; always a sibling directory.
2. A separate private repo — an ID-68 invention (S293), driven purely by the public-flip IP-leak gate (docs/ + .planning/ are git-tracked).

Conflation crystallised at S301 (OQ-R12, Option S-B): the docs-site spaces got routed as separate “move to the internal repo” rows, flipping the model from “the docs-site (which holds these) is private” to “these docs are private things we file into the internal repo.” That produced the 3-repo topology, KH_DOCS_DIR routing matrix, cross-repo bridges, and a large de-ID burden — mostly artifacts of the conflation. Corrected model = 2 git repos + cold-storage + external ingestion.

---

2. Target topology

Tier	Repo / location	Holds	Privacy
PUBLIC code	ai-solution-hub/knowledge-hub	App code; eval harness code + operators; synthetic fixtures; metric baselines; sanitised ontology + design; CI gate files (.knip-baseline.json, .type-drift-baseline.json, reference-doc-paths.json)	public (≠ open-source; we keep IP)
PRIVATE docs-site	knowledge-hub-docs-site	ALL documentation + the JSON ledgers + the Astro docs-site (gated Vercel) + the 2 bid-prose eval fixtures	private (you + me)
COLD-STORAGE	knowledge-hub-archive (indexed by nothing by default)	.planning/.archive/ content; docs/workflow-evaluation/ corpus; pruned continuation-prompt history	private, un-indexed (opt-in index ok)
EXTERNAL ingestion	local-fs (dev) → /corpus mount / client file server (prod)	The real client corpus; any real client documents	never in git

One private bridge knob: KH_PRIVATE_DOCS_DIR (renamed from KH_DOCS_DIR) — resolves the private docs-site repo from the public repo (sibling checkout / GitHub-App token). One direction. The per-space routing matrix + KH_PUBLIC_REPO_DIR collapse (except where docubot genuinely reads public code → private docs).

---

3. Per-domain resolution

3.1 Documentation → PRIVATE docs-site repo

reference/ runbooks/ product-functionality/ specs/ design/ continuation-prompts/ cmux-briefs/ live in the private docs-site repo and build into its Starlight site (gated). No de-ID needed — never public. Dissolves the “sanitise the docs spaces” workstream. cmux-briefs consolidate to ONE home (fix the stale handoff pointer + session-driver-cmux example paths). The public-vs-private specs fight dissolves — specs are docs → private.

RESOLVED (S301a-8, ratified + executed): src/content/docs/ is the tracked canonical source — .gitignore fixed, sync-content.ts retired, corpus frontmatter-normalised, site builds directly off the tracked source (617 pages green). Commits f9c92ba2 + 1ad3e1cf.

3.2 Ledgers → PRIVATE, via the patch-server substrate (§4)

task-list / backlog / roadmap / retros + mirrors → private docs-site repo. Rationale (upheld): the S301 security re-examination admitted the ledgers carry the same product-strategy/recon sensitivity it moved the docs spaces private for, then defaulted them public on cost grounds. Attack-vector (a backlog item naming an unfixed vuln) + IP (roadmap) ⇒ private.

3.3 Eval lane → CODE public, DATA private/synthetic

The ID-68 move was data-driven, not code-driven (6506fcf8 bundled clean code with the IP-laden fixtures for convenience). Split:

• PUBLIC: lib/eval/* + 5 scripts/eval-*.ts runners (clean); the 4 operators (clean); eval-baselines/*.json (metrics-only); search-evaluation.json + search.baseline.json (0 hits); classification + entity gold-standards after a placeholder name-swap. Fix: parameterise the hardcoded 'telehouse' literal in eval-holder-rule-ts.ts.
• PRIVATE: summarisation + procurement-drafting gold-standards (verbatim client bid prose). OQ-1 → keep private now.
• Mechanism: fixture-path indirection (env knob) so public runners load synthetic-public or real-private fixtures by env. Both suites are already EVAL_*=1-gated out of PR CI.

3.4 Historical archive → COLD-STORAGE (knowledge-hub-archive)

Verified against the live gitnexus graph (correcting a stale mempalace memory): .planning/.archive/ was already invisible to gitnexus (0 nodes, dot-dir skip); the actually- indexed stale content is docs/workflow-evaluation/ (69 nodes) + docs/continuation-prompts/ (112 nodes). gitnexus honours only .gitignore + dot-dir skip — .graphifyignore is vestigial/not consumed → the only reliable way to hide history from gitnexus is to remove it from the indexed tree → a separate repo (done: knowledge-hub-archive). Prune aggressively (Warp philosophy). A separate, opt-in gitnexus/ccc index on the archive repo is supported (each tool indexes the repo/path you point it at) — so history stays queryable on demand, out of the canonical indexes, understood to be point-in-time/possibly-stale. Delete the vestigial .graphifyignore.

3.5 Real client corpus → EXTERNAL (ID-69, already ratified)

Drops out of the repo-topology question. The 33-file bid library was already removed from tree (b6e35683); ID-69 ratified external-folder-canonical (decision-graph Q2.1, CX.28), shipped in code (COCOINDEX_SOURCE_PATH watch; /stage+/walk; bound to /cocoindex-state/corpus on Coolify, S312). Dev = populate local-fs. In-repo test data must be synthetic.

• OQ-2 → the ITT/procurement test templates are public downloads (not client-specific) → keep public as-is.

3.6 Generated files + baselines (Liam Part-1)

Delete docs/generated/codebase-stats.{md,json} + mcp-inventory.{md,json} + their generator scripts + their docs-site sync entries. Keep type-drift-baseline.json → .type-drift-baseline.json at repo root (joins .knip-baseline.json). Then delete .planning/ (done) + docs/generated/ from public. GitNexus churn: strip live counts from the committed <!-- gitnexus:start --> block (check for a config flag first; else static line).

3.7 scripts/ hygiene (pre-flip)

Delete scripts/run-1m-context.ts + scripts/wf-export.py (copied from bid-manager ab97fc4a, zero KH coupling, dead). The 3 phew-named files already triaged. (scripts/ is already public via the ghcr image — hygiene, not new exposure.)

---

4. Ledger mechanism — patch-server substrate (Liam directive)

Build the end-state: task-view’s patch server becomes the ledger write substrate, replacing ledger-cli. Reject the interim agent-applies-update-doc model. Canonical runs on ledger-cli as-is until the substrate is integrated + tested, then cut over.

• task-view provides today: atomic per-record patch server (PATCH /api/ledger/record/:id, mtime collision detection), /task-view command, schema-detection mirror generator.
• Must be ported in: ledger-cli’s write-time gates — delta ({35.16}), budget ({35.17}), two-phase promote, client-name de-ID ({68.13}).
• Dissolves on cutover: hardcoded paths, regen-mirrors.sh coupling, the ~41 skill invocations → “skills call the server”; moving ledgers private = server config.
• Track: ID-20 sub-track, own spec chain (RESEARCH/PRODUCT/TECH/PLAN), runs in parallel cmux terminals (Liam, OQ-3).

---

5. Collapses vs remains

Collapses: 3rd repo as a distinct docs destination → docs-site is the private repo; the per-space routing matrix; de-ID of reference/runbooks/product-functionality/specs; ledger sanitisation-for-public; the bolted-on internal-repo harness; KH_PUBLIC_REPO_DIR retro write-back. Remains: de-ID of genuine client content in public (residual phew literals in scripts/+deploy/); guard-CI; the history purge ({68.10}) — now covers relocated docs + client content; the private repo (repurposed as docs-site home); docubot code→docs sync; the GitHub-App + sibling-checkout bridge.

---

6. Flip-readiness (re-derived; smaller)

1. Docs + ledgers moved to the private repo (no sanitisation — private).
2. Ledgers private via §4 — OQ-3 = A: the public flip waits for the patch-server cutover (ID-20 runs in parallel; timing not pressing).
3. Genuine client content out of public + history (corpus externalised; scrub residual phew literals incl. deploy/coolify/docker-compose.production.yaml:69; the 2 bid-prose fixtures private).
4. guard-CI as a required branch-protection check.
5. History purge ({68.10}) over the genuine-client set + relocated docs.
6. Cold-storage the archive + workflow-evaluation.
7. Re-run the relocation sweep against current canonical (the id68 branch forked 38 commits back, before deploy/, datapath-watch, /walk, scripts/cocoindex_pipeline/).

3 live-tenant items still stand (B cutover, A deploy-overlay, C kb_pipeline prompt) — need tracked subtasks.

---

7. The doc-creation WORKFLOW question (the next major design thread — Liam)

Relocating folders is not enough — the deeper question is what happens to documentation as it is created throughout developing the platform. This is a workflow/process question, and it should drive the docs-site IA, not the other way round.

Liam’s framing (S301a-7):

• The organic folders (research/ audits/ operations/ workflow-evaluation/ continuation-prompts/ testing/) grew ad-hoc; content is periodically hand-moved to the archive.
• We likely don’t need a freestanding research/ folder — research should be a canonical per-task-ID file (RESEARCH.md in the task spec dir), not a loose folder.
• Many operations/ + reference/ docs are now outdated given the canonical-pipeline work.
• Approach: identify what our SDLC process actually needs (which doc classes, created when, by which step, living where, retired/archived how), then use the docs-site to enable that.

This connects directly to the session-start open questions (where do research.md / spec / transitory / continuation-prompt / cmux-brief artefacts land across worktree / non-worktree / cmux contexts). Deliverable: a doc-lifecycle/IA design — the set of canonical doc classes + their creation → canonical → archive flow — which then fixes the final docs-site IA and the relocation set. This likely precedes or co-authors with the ID-68 PRODUCT spec.

Folders Liam deliberately did NOT yet move to the docs-site (pending this design): continuation-prompts/ research/ audits/ workflow-evaluation/ testing/ operations/.

---

8. Spec determination (path back to implementation)

This doc reframes RESEARCH. Recommended chain for the re-scoped ID-68:

• PRODUCT (new — ID-68 never had one): public/private/external invariants + bridge contract + de-ID acceptance criteria + the doc-class/IA model from §7.
• TECH (revise): repo-split mechanics, KH_PRIVATE_DOCS_DIR, docubot repoint, cold-storage, the public de-ID set, the history purge.
• PLAN (revise): re-decomposed against the smaller scope; drop collapsed workstreams.
• Ledger substrate = separate ID-20 sub-track, own spec chain, parallel cmux.

9. OQ resolutions (S301a-7)

• OQ-1 2 bid-prose eval fixtures → private now (synthesise later only if public CI needs them).
• OQ-2 ITT/procurement templates → public downloads, not client-specific → keep public.
• OQ-3 flip vs ledger cutover → A: flip waits for the patch-server cutover; ID-20 parallel cmux, own specs.
• OQ-4 cold-storage form → separate repo (knowledge-hub-archive, created); separate opt-in index supported.
• OQ-5 private repo identity → repurpose (renamed knowledge-hub-docs-site); strip redundant harness; docs-site → repo root; repoint Vercel.