llm-ingestion-okf/docs/plan/execution-order.md

Execution order — the full roadmap, sequenced

Status: approved sequencing across all remaining phases. This doc is the connective tissue between the per-phase plans; it owns the order and the reasons, not the phase detail. Each phase's detail and verification live in its own doc:

• docs/plan/phase-1-door-a.md — DONE, shipped at v0.3.2.
• docs/plan/phase-2-doors-b-c.md
• docs/plan/phase-3-configurable-contract.md
• docs/plan/phase-4-node-half.md

Headline order: Stage 0 (guard gate) → Phase 2 → Phase 3 → Phase 4 code, with Phase 2 split guard-independent-first and Phase 4's coordination started in parallel from the beginning. The quality argument for this order is below — it is not merely the roadmap numbering.

Stage 0 — Guard readiness (gate; do first, cheap)

Before any Phase 2 code, confirm llm-ingestion-guard 0.2 exists with the pinned surface (prepare_input, screen_output, okf.import_bundle, disposition enum) and is installable in CI. This is Phase 2's assumptions B1+B2; B2 is explicitly "not yet decided", and the guard is a separate repo (open/llm-ingestion-pipeline-security), so its readiness is partly outside this repo's control.

Why first: it is the single biggest unknown, it is cheap to check (read the guard repo), and its answer decides the shape of Phase 2 — run straight through, or front-load the guard-independent half while readiness is confirmed in parallel. Do not build a bearing dependency into the plan on an unverified foundation. If the surface has drifted from what the plan assumes, the whole persist-gate design must know now, not at the integration step.

Outcome recorded in STATE before Phase 2 code starts.

Phase 2 — Doors B/C (split: guard-independent first)

Internal order follows the phase-2 doc's TDD steps, deliberately:

1. Guard-independent half (steps 1–2): extraction registry (stdlib core types, fail-fast on unknown extension and on [extract] types without the extra) + provenance rendering and filename slugging (pure functions). Zero external dependency, maximal test-determinism, reuses the Phase 1 renderer. Highest-quality-yield work to start with; validates B3 (html.parser adequacy) early while it is cheap to change.
2. Guard seam (steps 3–5): Door B against a stub guard first (nail the disposition control flow deterministically), then integration with the real guard, then Door C. Stub-first means that when the real-guard integration test is the only thing that can newly fail, a failure isolates cleanly to the integration boundary. Door B before Door C: C reuses B's guard-gate pattern and both reuse Phase 1 primitives.

This is where pyproject runtime deps become exactly the guard pin — a semver-worthy event (propose 0.4.0), its own CHANGELOG entry.

Phase 3 — Configurable bundle contract (only after 2)

Extract configurability only once Door A and Door B/C both concretely use the type/layer/frontmatter/reserved-file constants. Phase 3 abstracts a pattern; you need ≥2 real consumers before the right seams are visible. Building the config object first would be speculative abstraction — an explicit anti-pattern. The proving consumer (claude-code-llm-wiki, strict-v1) is the concrete second profile that proves the abstraction is not single-use.

The 2→3 boundary has no painful retrofit: Phase 2 already leaves the seam open — Door C v1 deliberately does NOT persist the guard log "because reserved-file policy differs per consumer and becomes configurable in Phase 3." This is where the contract becomes explicit and frozen — the precondition for a clean Node port.

Phase 4 — Node half (two clocks)

Coordination clock — start early, parallel to Stages 0–3, but only the shape-independent agreements. Phase 4's hard preconditions are agreements, not code: okr's reference-impl lift in principle, catalog as re-pin owner, guard-as-contract at the Node persist seam, and the linkedin-studio non-normalization carve-out can all be initiated early — via coord — so they are settled when code starts. The one agreement that must WAIT is the exact second-brain contract shape: the phase-4 doc ties the catalog-spec expressiveness check to Phase 3's split-table step, so do not freeze the cross-runtime contract before Phase 3 has proven the profile can express it.

Code clock — last. The Node/ESM implementation ports a frozen, explicit contract (Phase 3's output) and uses the shared fixture suite as the cross-runtime conformance oracle. Porting before the contract is frozen means chasing a moving target and guaranteed drift between halves. Halves share contract and fixtures, never code.

Quality spine (holds across every stage)

• TDD iron law throughout: no production code without a failing test first.
• The golden/fixture suite is the backbone — every phase extends it; it is the regression oracle and, in Phase 4, the cross-runtime conformance oracle. It never goes non-byte-exact.
• Determinism invariant every phase (explicit ingested_at, LF-only, byte-exact). Phase 2 adds: the guard version is part of the input surface — pin it.
• Boundary grep-gate green every phase: grep -rn "sanitize\|quarantine\|lexicon" src/ empty (guard imports only).
• One phase = one release with a CHANGELOG entry; the guard dependency landing in Phase 2 is the architectural milestone.

Verification — the gate between each handoff

These are the objective checks that a stage is done and the next may begin:

1. Enter Phase 2: guard readiness recorded in STATE — either "0.2 API matches + installable in CI" or an explicit "front-load guard-independent half; guard integration blocked on ".
2. Phase 2 → Phase 3: Phase 1 golden suite still byte-for-byte; pyproject runtime deps == exactly llm-ingestion-guard>=0.2,<0.3; persist-gate proof test green (a fail-secure fixture yields zero new files).
3. Phase 3 → Phase 4: golden suite byte-identical under DEFAULT (git diff --stat examples/ empty for the phase); STRICT_V1 cross-profile rejection tests pass both directions; split-table artifact under docs/ reviewed with the operator (contract is frozen and expressive enough for the second-brain spec).
4. Phase 4 code start: each shape-independent coordination step has a recorded sign-off; the contract-shape agreement is signed off after the Phase 3 split-table, not before.
5. Throughout: mypy --strict src/, ruff check ., ruff format --check . clean; boundary grep-gate empty.