ID-163 {163.2} PLAN — canonical-okf-system baseline bundle decomposition

PLAN — canonical-okf-system baseline bundle (implementation decomposition)

Status: DRAFT — 17/07/2026. Authored by a fresh Planner (Q-PLANNER-2), NOT the TECH author. Decomposes the RATIFIED spec pair — TECH.md (owner-ratified 17/07/2026 after the S488 OQ rulings) + the doctrine PRODUCT substrate (bundle-doctrine.md, DR-079) — into 14 implementation Subtasks {163.3}–{163.16}. The TM-shape Subtask records (load-bearing details, one-line testStrategy, sibling-only deps) are the canonical artefact; the Orchestrator adds them via bun scripts/ledger-cli.ts add-subtasks 163 --file -. This document is the human- readable rationale + dependency graph + sequencing gates.

Owner rulings baked in (S488 — settled, do not reopen): OQ-1 → DR-086 (the canonical repo IS PUBLIC and is the citation base; tool/api/schema pillars cite git-pinned public canonical blob URLs directly; ALL bundle repos PRIVATE, docs-site PRIVATE + never citable). OQ-2 → HC-5 concept round-trip eval cadence = PER RELEASE (ci.yml), not nightly.

Overview

id-163 productionises the class-2 (system baseline) OKF bundle: platform-navigation knowledge for consuming agents (id-71), produced by the same id-132 cocoindex producer via a direct-producer (Path 2) lane. The TECH maps nine proposed changes (PC-1…PC-9) 1:1 against the doctrine’s System-bundle v1 scope (S1–S4) and four key assumptions (KA1–KA4). This plan turns that grid into an ordered build: foundational code slices first, then a gated prototype, then the bulk authoring + born-evaluable gate, then release-lane integration and the final delta-determinism + §9 proofs.

The decomposition is 14 Subtasks, comfortably under the 25-Subtask soft ceiling. All Subtask dependencies are sibling-only (every dep references another 163.N); no cross-Task dependency surfaced — the id-132 producer spine, the {132.35} GLM-5.2 proof, {132.41} derive_concept_confidence, bl-457 IRIs and bl-477 A19 are all DONE/deployed current-state facts the plan builds on, not dependencies to express.

Architecture decisions (carried from the ratified TECH — not re-litigated)

RepoDocsSource is a structural sibling of LRecordsSource (PC-1) — the same local @runtime_checkable Source protocol, constructed over a repo/docs root instead of a pool. Reuse, not re-architecture.
The change signal is the git blob SHA (S4) carried on a new RepoConceptKey (analogue of ConceptKey.content_version), computed via subprocess + the git CLI (reusing the git_sync.py:264 posture — no new git library). BI-18 delta-only regeneration falls out for free.
The provider path is PROVEN, not new (PC-3) — the GLM-5.2/OpenRouter PRODUCER_* slices proven in {132.35} (BI-18, image sha-35e1a9c1, zero Anthropic spend). No agent-loop change.
The type set becomes bundle-class-scoped (PC-4) via EffectiveOntology.base_for_class; base_only() stays the client_business default so every existing call site is byte-identical. The TS concept-schema.ts render is already type-open (no hard gate), so TS parity is a semantic-token/label add, not a gate change.
Citation provenance is generalised, not bypassed (PC-5) — the seen_anchors mint/validate discipline is kept; the git-blob/doc-page scheme is an additive branch keyed on anchor scheme, leaving the canonical:// L-records path untouched. Mint base is PUBLIC only (DR-086); the private docs-site is never a mint source.
The overlay boundary is already enforced (PC-6) — bundle_writer hard-rejects a discovered overlay unless bundle_class == "client_business"; id-163 work is a regression test only.
Composition is already multi-bundle (PC-7) — enumerateOkfBundles() unions/sorts/ never-throws; the system bundle lands as one more sibling subdir. Residual work is a render-side N≥2 check + system concept-type tokens.
The gate is born-evaluable HC-5 (PC-8) with DR-016 override capture as the interim gate until the round-trip is wired; the round-trip set is a net-new additive set on the mcp-eval harness (bounded, not free: a concept→tool resolver + a per-concept machine-extractable behaviour assertion).
A19 confidence stays deterministic (PC-9, DR-081a) — strong|partial only, generalised to the round-trip signal; routing hints reuse existing frontmatter machinery.

Two load-bearing sequencing gates (forcing functions)

These are the two constraints the whole build sequences around. They are encoded as Subtask dependencies, not just prose.

KA3 prototype-before-scale gate. The tool-pillar + ONE doc-pillar prototype ({163.4} code, {163.10} authoring, {163.11} eval) must land and be judged before the other three pillars are built. If any pillar needs a bespoke concept model (a 3rd extractor FAMILY, not merely a locator resolver), the Executor STOPs and escalates — it does not author past the prototype. Encoded: {163.13} (remaining pillars) depends on {163.10} + {163.11}, which transitively depend on the {163.4} KA3 judged gate.
Born-evaluable gate with an interim. The HC-5 concept-roundtrip eval-set is net-new and additive on scripts/mcp-eval/; until it is wired, DR-016 override capture ({163.9}) is the interim human-sign-off gate. Encoded: {163.9} → {163.10} → {163.11} (prototype) → {163.15} (scale + ci.yml per-release, DR-086/OQ-2).

Dependency graph

1
{163.3} per-class validator type set (PC-4) ─────────┐
2
                                                      ▼
3
{163.7} overlay-rejection regression (PC-6) [indep]   {163.4} RepoDocsSource + RepoConceptKey
4
{163.8} multi-bundle render check (PC-7c)   [indep]        + KA3 two-extractor PROTOTYPE (PC-1)
5
                                                      │        [KA3 JUDGED GATE + 3rd-family STOP]
6
                            ┌─────────────────────────┼───────────────┐
7
                            ▼                          ▼               ▼
8
              {163.5} source selection (PC-2)  {163.6} citation      (feeds authoring)
9
                            │                    provenance (PC-5)
10
              ┌─────────────┼──────────────┐          │
11
              ▼             ▼               │          │
12
   {163.9} interim    {163.14} repo mint +  │          │
13
   override capture   promote lane (PC-7ab) │          │
14
   (PC-8 interim)                           │          │
15
              │                             │          │
16
              └──────────────┬──────────────┴──────────┘
17
                             ▼
18
        {163.10} first authoring wave: prototype pillars + KA2 first-5 gate
19
                             │
20
                             ▼
21
        {163.11} HC-5 concept-roundtrip: KA1 one-tool prototype (PC-8 target gate)
22
                             │
23
              ┌──────────────┼───────────────────────┐
24
              ▼              ▼                         ▼
25
   {163.12} A19 +   {163.13} remaining-pillar   (prototype judged →
26
   routing hints    authoring waves (~63)        other pillars unlocked)
27
   (PC-9, KA4)              │
28
                           ┌┴───────────────┐
29
                           ▼                ▼
30
              {163.15} scale eval-set   {163.16} BI-18 delta re-run
31
              + ci.yml per-release      + §9 conformance (S4 + §9)
32
              (PC-8 productionise)      (needs {163.14} deployed lane)

Sibling-only dependency table (all deps are 163.N siblings — no cross-Task deps):

Subtask	Title (short)	Deps	Est
{163.3}	Per-class validator type set (PC-4)	—	S/M
{163.4}	RepoDocsSource + RepoConceptKey + KA3 prototype (PC-1)	3	L
{163.5}	Class-gated source selection (PC-2)	4	S
{163.6}	Citation provenance → git-blob URLs (PC-5)	4	M
{163.7}	Overlay-rejection regression (PC-6)	—	XS
{163.8}	Multi-bundle render check + tokens (PC-7c)	—	S
{163.9}	Interim DR-016 override capture (PC-8 interim)	5	M
{163.10}	First authoring wave + KA2 first-5 gate	4,5,6,9	M
{163.11}	HC-5 KA1 one-tool round-trip prototype (PC-8)	10	M
{163.12}	A19 confidence + routing hints (PC-9, KA4)	11	S
{163.13}	Remaining-pillar authoring waves (~63)	10,11	L
{163.14}	Repo mint + promote lane + deploy config (PC-7ab)	5	M
{163.15}	Scale eval-set + ci.yml per-release (PC-8)	11,13	M
{163.16}	BI-18 delta re-run + §9 conformance (S4+§9)	13,14	S

Phased task list + checkpoints

Phase 1 — Foundation (code, no authoring)

{163.3} per-class validator type set · {163.4} RepoDocsSource + RepoConceptKey + the KA3 two-extractor prototype · {163.5} class-gated source selection · {163.6} git-blob citation provenance. Independent guards {163.7} (overlay rejection) and {163.8} (multi-bundle render + tokens) can run in parallel anytime.

Checkpoint — KA3 verdict (HARD GATE): {163.4} must prove the tool + one-doc-pillar split covers both identity models without a 3rd concept model. A 3rd family → STOP and escalate; do not proceed to Phase 3 authoring. python3 -m pytest scripts/tests/ green.

Phase 2 — Interim gate + first draft

{163.9} interim DR-016 override capture · {163.10} first authoring wave (prototype pillars) with the KA2/S3 first-5-concepts citation-discipline gate.

Checkpoint — KA2/S3: every citation on the 5 drafted concepts is a seen_anchors PUBLIC git-blob/doc-page URL (zero hallucinated), none references the private docs-site, and each tool concept carries a machine-extractable expected-behaviour assertion (the convention {163.11} consumes). okf:validate --strict passes.

Phase 3 — Born-evaluable gate + scale

{163.11} HC-5 KA1 one-tool round-trip prototype · {163.12} A19 confidence + routing hints · {163.13} remaining-pillar authoring waves (unlocked only after the prototype is judged) · {163.15} scale the eval-set + wire ci.yml per-release.

Checkpoint — KA1 + productionise: the round-trip passes for one tool concept, per- concept wiring cost recorded; then the full set passes for all tool/api concepts and runs per-release in CI (DR-086/OQ-2). The born-evaluable gate replaces the interim sign-off.

Phase 4 — Release + final proofs

{163.14} repo mint + prove→pin→promote lane + deployment config · {163.16} BI-18 delta-only re-run proof + §9 conformance.

Checkpoint — production-ready: a pure-unchanged re-run yields zero drafting calls + zero churn; a single git-blob-SHA touch redrafts exactly one concept; okf:validate --strict passes on the full ~68-concept bundle; the promote lane publishes to the PRIVATE canonical-okf-system without cross-writing the client bundle-dir.

Risks and mitigations (from TECH, sequenced)

Risk	Impact	Mitigation (Subtask)
A pillar needs a 3rd extractor family (“Path A balloons”)	High	KA3 judged gate + STOP-escalate trigger armed in `{163.4}`/`{163.13}`
`seen_anchors` generalisation regresses the proven L-records enrich path	Med	Additive branch keyed on anchor scheme; `canonical://` untouched; `TestCitationValidationProxy` must stay green (`{163.6}`)
Second bundle class contends with a single `OKF_BUNDLE_DIR` on one VPS	Med	Recommend a separate bundle-dir+class config (env is read-once-at-import); memo namespaces are per-`coco.App` (`{163.14}`)
Concepts lack a machine-extractable behaviour claim → round-trip can’t assert	Med	Force the assertion convention from concept 1; the one-tool prototype shapes it early (`{163.10}`/`{163.11}`)
`concept-schema.ts` per-class parity drift	Low	TS render is already type-open (no hard gate); parity = token/label add + parity note + schema-parity side-workflow (`{163.3}`)
bl-513: `sync_bundle` flags staged-in-place producer output as human edits when bundle-dir == repo-path	Med	Watch-item on `{163.9}` (override capture must distinguish sign-off from staged output) + `{163.14}` (verify bundle-dir vs repo-path benign on `publish.py` touch); no scope-creep fix

Open questions

None blocking. OQ-1 (citation base) and OQ-2 (eval cadence) are settled by DR-086 / S488 and baked into {163.6}, {163.10}, {163.11}, {163.15}. The internal_dev class (bl-478, parked) is a named future extension — the {163.3} class registry and {163.5} source selector are built to admit it (its type set deferred).

Notes for the Orchestrator

{163.13} (remaining ~63 concepts) is the largest slice; it MAY be fanned into per-pillar Executor dispatches (api / schema / playbook / remaining-tool), each a locator-resolver add + an authoring wave, without changing the dependency graph — the 3rd-family STOP trigger applies to each.
{163.14} mixes owner/ops actions (repo creation, deploy key, Coolify env) with code (promote-lane parameterisation); dispatch the code portion to an Executor and route the ops portion to the owner/Orchestrator.
No DR-intent to write: the two OQ rulings already landed as DR-086 on main.