llm-ingestion-okf/docs/phase-3-split-table.md

# Phase 3 split table — the proving consumer's 25 gates

Status: **reviewed by the proving consumer and by the operator (2026-07-25);
the port may begin.** Phase 3's plan requires this mapping before any porting.
Nothing in the consumer's repository is modified by this repository.

The proving consumer (`claude-code-llm-wiki`) answered the same questions from
their own code on 2026-07-25, crossing with this draft rather than responding
to it. Two independent readings of the same source agreed on every substantive
point: the required-key set as their code spells it, three reserved basenames,
`summary` as the only nullable key, the index structure, and the closed sets.
Their answer added four refinements, each folded in below and marked. Their
column assignments match this table's, with one wording difference resolved in
gate 5's row. A later round answered the four open questions outright — see
"Answered by the proving consumer" — and moved the required set from what their
code enforces to what their operator ratified.

Read from the consumer's working tree on 2026-07-25:
`tools/wiki_ingest/validate.py` and `tools/wiki_ingest/bundle.py` at commit
`9ee5a8e` (repository HEAD `20bcdd6`). Their `validate.py` is the single
entrypoint for every per-run gate, so this table is exhaustive over the gate
set as it stands at that commit — assumption C2 is satisfied only as long as
that remains true, and a gate added there after this date is not in this table.

## The three columns

| Column | Meaning | Goes where |
|---|---|---|
| Profile | Structural bundle contract: types, frontmatter keys, paths, reserved files, index shape | This phase, `BundleProfile` |
| Guard | Content safety: carriers, secrets, injection, active content | `llm-ingestion-guard` calls — never reimplemented here |
| Consumer | Domain logic: source pipelines, LLM contract, promotion, run accounting | Stays in the consumer's repository |

## Stage A — detection/acquisition

| # | Gate | Default class | Column | Note |
|---|---|---|---|---|
| 1 | `INGEST_LEDGER_DIVERGENCE` | ALERT (halts) | Consumer | Upstream re-poll reconciliation; no bundle structure involved. |
| 2 | `INGEST_CHANGELOG_PARSE` | ERROR | Consumer | Source-format parsing for one specific upstream. |
| 3 | `INGEST_EXPECTED_SET` | ALERT | Consumer | npm/changelog reconciliation against known deltas. |
| 4 | `INGEST_DOCS_CORPUS_SANITY` | ERROR | Consumer | Corpus size/shape thresholds for one named corpus. Its second half — "a concept must not derive from the changelog page" — is a layer-provenance rule expressed as a URL test; see open question Q3. |
| 5 | `INGEST_INPUT_INJECTION_SCAN` | WARN (ERROR when verbatim) | Guard | Carrier scan plus semantic lexicon on fetched input. Guard *column* means the functionality is the guard's and is never reimplemented — not that the call site moves here. The consumer keeps the call, as they state, since it sits in their acquisition stage. The disposition-aware escalation is Consumer policy over a Guard verdict; see Q1. |

## Stage B — LLM-output contract

| # | Gate | Default class | Column | Note |
|---|---|---|---|---|
| 6 | `LLM_STOP_REASON` | ERROR | Consumer | |
| 7 | `LLM_SCHEMA` | ERROR | Consumer | Frozen run-record schema plus summary length caps. |
| 8 | `LLM_OUTPUT_LINT` | ERROR | mixed | Decomposed below. |
| 9 | `LLM_GROUNDING_ANCHOR` | ERROR | Consumer | Anchor resolution against their concepts layer. |
| 10 | `LLM_SOURCE_TRACE` | ERROR | Consumer | Verbatim-quote and dropped-citation detectors. |
| 11 | `LLM_SEAM_LINKS` | ERROR | Consumer | Proposed links restricted to existing concept IDs. |
| 12 | `LLM_BUDGET` | ERROR | Consumer | Per-run call/token/cost caps. |

## Stage C — bundle conformance and publish

| # | Gate | Default class | Column | Note |
|---|---|---|---|---|
| 13 | `BUNDLE_FRONTMATTER_PARSEABLE` | ERROR | Profile | Every non-reserved `.md` opens with a complete fence. |
| 14 | `BUNDLE_TYPE_ENUM` | ERROR | Profile | Closed enum `Concept`/`Guide`/`Reference`/`Release`. |
| 15 | `BUNDLE_RESERVED_FILES` | ERROR | Profile | `log.md` required-absent; `index.md` structure. Three reserved basenames, not two — see "What STRICT_V1 must express". |
| 16 | `BUNDLE_YAML_STRICT` | ERROR | Profile | Key allowlist, required keys, and the StrictYAML scalar subset. |
| 17 | `BUNDLE_LAYER_PATH_TYPE` | ERROR | Profile | Path prefix ⇄ `layer` ⇄ `source_tier` ⇄ `type` agreement. |
| 18 | `BUNDLE_LINKS_INTERNAL` | ERROR | Profile | Every relative cross-link resolves inside the bundle. Consumer's caveat, accepted: link resolution assumes their layer layout, so it generalises only because `path_policy` owns the layout too. |
| 19 | `BUNDLE_LINKS_EXTERNAL` | WARN (never blocks) | Consumer | Liveness polling; needs network state this library does not collect. |
| 20 | `BUNDLE_URL_ALLOWLIST` | ERROR | mixed | Decomposed below. |
| 21 | `BUNDLE_INDEX_COMPLETE` | ERROR | Profile | Per-directory index exactness plus root-index metadata keys. |
| 22 | `BUNDLE_HASH_REGISTRY` | ERROR | Consumer | Their page-hash snapshotter must cover the concepts layer exactly. |
| 23 | `BUNDLE_SANITIZATION` | ERROR | Guard | Carrier-freedom of published text. |
| 24 | `BUNDLE_BLAST_RADIUS` | ERROR | Consumer | Per-version diff caps from their run manifest. |
| 25 | `BUNDLE_SECRET_SCAN` | ERROR | Guard | Credential patterns over bundle text and run artifacts. |

## The two mixed gates, decomposed

The plan asks for exactly one column per gate. Two gates do not honour that as
written, because each bundles checks belonging to different columns. Splitting
them is the honest mapping; the alternative — assigning the whole gate to its
dominant column — would quietly move the residue to the wrong side.

**Gate 8, `LLM_OUTPUT_LINT`** runs `_lint_text` over enrichment summaries and
verbatim release bodies:

| Check | Column |
|---|---|
| Off-allowlist URL | Consumer (their editorial pinning; see gate 20) |
| HTML tag in prose | Guard — active content is squarely the guard's territory at v0.3.0 |
| base64-like blob | Guard |
| Credential pattern | Guard |
| Consumer-directed imperative | Guard — this is the injection posture, expressed as their house rule |
| Injection lexicon and hex blob | Guard |

**Gate 20, `BUNDLE_URL_ALLOWLIST`** bundles two unrelated rules:

| Check | Column |
|---|---|
| URL host/prefix on the pinned allowlist | Consumer |
| Domain is new versus the previous bundle state | Consumer (drift detection over their own retained state) |

Neither half is Profile: a URL allowlist is editorial policy about which
sources a bundle may cite, not a statement about bundle structure. It is listed
as mixed only because the checks have different natures, and both land in the
same column — noted rather than merged, so a later reviewer can see it was
considered.

## What STRICT_V1 must express

The phase-3 plan sketched this profile before the validator was read. Two of
its claims did not survive contact and are corrected here; the plan file
carries the same corrections. One of the two was then corrected a second time
by the consumer's operator — the sequence is recorded rather than smoothed
over, because the end state is deliberately neither what the plan drafted nor
what their code says.

1. **Required keys are eight — settled by the consumer, not read off their
   code.** Their `REQUIRED_KEYS` constant is four (`type`, `title`,
   `description`, `timestamp`), and this table first corrected the plan down to
   it. Asked whether four was the contract or an artefact of unfinished triage
   (Q2), they measured the whole bundle and their operator ratified eight:
   `type`, `title`, `description`, `timestamp`, `layer`, `source_tier`,
   `source_url`, `source_sha`, present on 522/522 documents. The four-key
   constant is their *emit-path* minimum, not their contract.

   Two consequences are carried deliberately:

   - **STRICT_V1 is stricter than the consumer's own validator.** Should they
     ever ship a document class that legitimately lacks `source_sha` — a
     hand-written Guide, say — this profile rejects what their validator
     passes. The agreed resolution is to bump the profile, not to bend the
     bundle, and they send the requirement before shipping such a class rather
     than after.
   - **The allowlist remains a different thing from the required set.**
     `FRONTMATTER_KEY_ORDER` is eleven keys — the eight above plus `version`,
     `date`, `summary` — and doubles as canonical emission order. `version` and
     `date` are layer-specific (present on 351/522) and `summary` on 349/522,
     so all three stay optional-when-absent and are validated against closed
     sets **only when present**; a profile that required them would reject
     pages the consumer ships today. So `frontmatter_schema` needs three
     fields, not one: required, allowlisted, and ordered.
2. **Three reserved basenames, not two.** `index.md`, `log.md`, and
   `README.md`. README is bundle documentation, reserved like `index.md`: it
   carries no frontmatter, is skipped by the per-document gates, is never
   listed in a generated index, and is still subject to the link, URL,
   sanitization and secret gates. A two-value reserved-file policy
   (required-present / required-absent) cannot express it; the third value is
   "present-and-exempt-from-document-gates".

Beyond the frontmatter set, `BundleProfile` must carry:

- **Type policy:** closed enum, four values.
- **Nullable keys:** `summary` alone may be `null` — the single deliberate
  escape from strings-only frontmatter.
- **Value shapes:** a string scalar, **or a non-empty list of strings**. This
  is the same block-list shape Door C already refuses to round-trip through
  this library's line-oriented parser, which is why an imported concept is
  written verbatim. A profile that assumes scalars-only rejects the consumer's
  own `Release` pages, and a parser that assumes scalars-only would silently
  destroy them.
- **Key-name grammar:** `^[a-z_]+$`.
- **Scalar encoding:** the StrictYAML subset (JSON-double-quoted scalars), so
  a regeneration over the same data is byte-identical.
- **Emission order — carry this over intact:** the ordered prefix above,
  followed by any remaining keys **sorted**. This is the door-A model settled
  by commons decision D1, and it is what makes regeneration byte-identical.
  A profile that normalises key order any other way breaks the consumer's
  `BUNDLE_HASH_REGISTRY` gate, which is what made that decision matter.
- **Layer/path policy:** `concepts/` ⇄ layer `concepts`, source_tier
  `official-docs`, any type except `Release`; `releases/` ⇄ layer `releases`,
  source_tier `changelog-derived`, type `Release` exactly. Their constants
  spell these `bundle/concepts` and `bundle/releases` because their validator
  walks a repository whose bundle lives in `bundle/`. That prefix is where
  *they* keep the bundle, not part of the contract — see "No placement field"
  below.
- **Index policy**, which differs from this library's default in four ways:
  one index per *directory* rather than one per bundle; entries formatted
  `* [Title](link) - description` rather than `- [label](target)`; index
  contents must match the directory exactly, both directions; and the root
  index carries frontmatter pinning `okf_version`, `bundle_profile`,
  `okf_spec_commit`.
## No placement field — a field the profile must NOT grow

The catalog reported on 2026-07-25 (their commit `3ccb5f6`,
`docs/okf-second-brain/spec.md` §1 and §8) that bundle placement is
**unmandated**, measured against four consumers rather than taken on report:
exactly one installs a bundle anywhere; for the other three the bundle
directory is a caller-supplied argument per run, with no default, no discovery
and no `$HOME` expansion. Discovery, where it happens, keys on the §3 root
marker (`index.md` plus `okf_version`), never on a path.

Three consequences for `BundleProfile`, recorded here because this phase's
non-goal is precisely "do not make the profile too narrow for the Node-world
conventions in phase 4":

- No root-location or install-path field. There is no path form to express.
- "No installation root" is a conforming consumer shape, so a profile that
  assumes every consumer has one would be too narrow in exactly the warned way.
- Installing and writing are separate axes: a consumer may write into a bundle
  it never placed, so write policy must not be tied to a placement concept.

Every path in this document is therefore bundle-relative, and the bundle
directory stays what it is today in both doors — an argument.

The index-policy divergence is the largest single item. Under the default
profile the observable output must stay byte-identical (assumption C1, proven
by the golden suite), so `index_policy` has to express both shapes rather than
generalising one into the other.

## Answered by the proving consumer

All four questions were answered on 2026-07-25, each measured or read out of
their code that day rather than recalled. **No row in the mapping moved**; the
reasons under three of the four are sharper than the ones this table drafted.

- **Q1 — gate tiers stay Consumer/Guard.** This repository's position was
  accepted, and the escalation turns out not to be a document-class rule at
  all: gate 5 escalates WARN to ERROR when the per-version *record* carries
  `disposition == "verbatim"` (`validate.py:528-540`), i.e. when the LLM
  rewrite layer was skipped and the input lint is the only filter left. That is
  run state, not bundle shape — a profile could not see it even if it wanted
  to. A profile describes structure; it does not set security tiers.
- **Q2 — eight, ratified by their operator.** Folded into "What STRICT_V1 must
  express" above, together with the consequence both sides accepted.
- **Q3 — Consumer, for a sharper reason than "URL predicate".** The check is
  `is_changelog_url()` (`docs_corpus.py:181-184`): it lowercases the last URL
  segment and tests membership in `("changelog", "release-notes")` — a
  vendor-specific slug list for one upstream. Two details worth carrying: the
  gate is **not** scoped to `concepts/` at all (it walks every non-reserved
  document across both layers, `validate.py:480-492`, despite a rationale
  string that says "concepts layer"), and it spares their own release pages
  only because their `source_url` ends in `CHANGELOG.md`, whose last segment is
  `changelog.md` rather than `changelog`. That is a coupling, not a design. A
  structural profile could express "layer X may not carry source_tier Y"; it
  could not express this.
- **Q4 — both stay Consumer.** Gate 19 sits in their `NEVER_BLOCKING_GATES`
  (`validate.py:86-88`) by construction, precisely because liveness is a flake
  magnet: a profile that owned it would inherit a gate that can never block.
  Gate 22 is their provenance model, the one commons decision D1 settled in
  their favour, and it is why the ordered-prefix emission matters. The profile
  gets no notion of external state from either.

Two confirmations arrived unasked and are recorded because later work leans on
them:

- **Assumption C2 holds.** `validate.py` is still the single entrypoint for
  every per-run gate, and the registry at lines 50-78 is the whole set — 5
  `INGEST_*`, 7 `LLM_*`, 13 `BUNDLE_*` = 25. A change reaches this repository
  as a message before it can be read out of their code.
- **The index shape is not negotiable downward**, which makes "express both
  shapes rather than generalise one into the other" the right call: one index
  per directory, exactly one `# ` heading, entries
  `* [Title](link) - description` and nothing else, directory and index
  matching in both directions, and a root index carrying `okf_version` /
  `bundle_profile` / `okf_spec_commit` frontmatter in that key order.

## The index policy, and the conflict that shaped it

The convention owner reported on 2026-07-25 that the second-brain spec's §3
mandates an `index.md` at every directory level, that `IndexPolicy` as it then
stood could not express that, and — the load-bearing part — that an index is an
**authored** count of a directory's children and never a filesystem lookup. On
their reading, an index reader or validator that enumerates a directory to
build or check an index has implemented the wrong contract, with a silent
failure mode: code written to the wrong reading passes every test one would
think to write.

That was checked against the proving consumer before it was adopted, and the
two consumers turn out to be **directly opposed on exactly this point**:

- `validate.py:1081-1120`, gate `BUNDLE_INDEX_COMPLETE` (severity ERROR),
  builds its expected set by enumerating the directory and fails unless the
  index matches it exactly in both directions.
- `bundle.py:498-567` writes every index from what a tree walk finds, and its
  own docstring calls `index.md` machine-generated.

So one consumer mandates the derivation the other calls the wrong contract.
Neither is incoherent inside its own spec, and this repository is not the venue
to adjudicate between them. What it settles is narrower and sufficient:
**authored-versus-derived cannot be a library invariant in either direction.**
It is a policy field (`entries_match_directory`), as are per-directory scope,
the heading requirement, whether prose is admitted, and the root-index key set.

Three consequences that outlive this phase:

1. **Nothing in this library enumerates a directory.** The caller supplies the
   listing; `IndexPolicy.violations` refuses one when the profile's index is
   authored, and refuses to run without one when it is derived. The
   convention owner's construction rule is enforced at the call site rather
   than documented and hoped for.
2. **Root and nested indexes are asymmetric**, confirmed independently in both
   consumers: the root carries frontmatter (`okf_version`/`bundle_profile`/
   `okf_spec_commit` for the wiki, `okf_version`/`okf_layout` for the catalog)
   and nested indexes carry none. Different key sets, same shape — which is
   why it is a profile field and not a constant.
3. **A per-entry description is template-level, not a separate requirement.**
   The wiki requires `* [Title](link) - description`; the catalog requires
   prose in the index and no per-entry description. A profile that wants none
   simply does not name `{description}` in its template.

`DEFAULT` keeps upstream's root-only index and judges nothing, for the same
measured reason it carries no required frontmatter key set: upstream OKF binds
`index.md` to the bundle root alone, so a default demanding one per level would
declare upstream-conforming bundles invalid.

## What this table does not do

It does not port anything. Per the plan, porting starts only after this
mapping is reviewed, and the Guard column must contain no rows implemented in
this repository — the phase-2 grep gate over guard functionality still applies
unchanged.

Both reviews are in as of 2026-07-25 — the proving consumer's (above) and the
operator's — so the port may begin. The Guard-column constraint is unaffected
by either.