docs(okf-v0.2): the alignment track lands before the contract freezes

Everything built so far targets OKF v0.1. Upstream published v0.2 on
2026-07-25, so the plan records how the library relates to it and, more
importantly, who owns each decision.

Read from the spec itself rather than secondhand, which corrected two
readings that a summary had gotten wrong:

- STRICT_V1's `timestamp` is NOT a defect. Section 13.1 grants consumers a
  documented fallback to legacy `timestamp` precisely when `generated` is
  absent, and STRICT_V1 emits no `generated`. Nothing is asked of the wiki.
- The one measured shape problem is DEFAULT's `generated: "true"`, because
  v0.2 requires `generated.by` within `generated`. That key was not reserved
  in v0.1, so it was legal when written; v0.2 claimed the name. DEFAULT
  states commons' ingest-spec section 5 layer, so the fix is commons' call
  and is raised there as open question V1 rather than patched locally.

Two findings shrink the work. The canonical form for `generated` and a
single `verified` is an inline flow mapping, which the existing scalar
parser already round-trips as an opaque string, so block-list support is
only needed for `sources` and multi-verifier `verified` -- and only if a
named consumer asks. And the collision degrades safely: `_is_ingest_owned`
returns False for a v0.2 mapping, so a foreign concept is refused rather
than overwritten.

The track sits between Phases 3 and 4 because Phase 4 freezes the
cross-runtime contract. Freezing a v0.1 shape into two runtimes would let
the shared fixture suite certify the drift instead of catching it.

Self-imposed rule, since the spec does not require it: conform first, claim
after. Declaring `okf_version: "0.2"` is a MAY with no conformance
checkpoint, so claiming it early would be permitted -- and would be the same
class of true-sounding misleading claim as reporting a 0.2.0 measurement
under a 0.3.1 heading.

Also moves the guard 0.3.1 measurement procedure out of session state and
into execution-order.md, where it belongs.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A2aKJxLejT9S8jYwoZ9fut

docs/plan/execution-order.md

@@ -8,12 +8,14 @@ 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/okf-v0.2-alignment.md` — a policy track, not a phase; slots between
+  Phases 3 and 4 for the reason given below.
 - `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.
+Headline order: **Stage 0 (guard gate) → Phase 2 → Phase 3 → OKF v0.2 alignment
+decisions → 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)
 
@@ -33,6 +35,36 @@ persist-gate design must know now, not at the integration step.
 
 Outcome recorded in STATE before Phase 2 code starts.
 
+### Stage 0 revisited — measuring guard 0.3.1 before widening the pin
+
+The pin held is `>=0.2,<0.3`, which can only ever resolve `v0.2.0`. The guard repo
+gates its own 1.0 on our fixture suite being measured against `v0.3.1`, so this
+measurement is owed outward and is that repo's only named blocker. Order is
+*measure first, widen after*: widening the range before measuring would ship a
+window admitting a version the fixtures never ran against.
+
+Procedure — do not vary it, each step exists because of a specific failure mode:
+
+1. Scratch venv **outside** `.venv`: install the package `--no-deps`, then the
+   guard from the `v0.3.1` tag. Do not touch `pyproject.toml`.
+2. **Assert the resolved version** via `importlib.metadata` *before* running
+   anything, and carry it in the reported result. An unmodified tree resolves
+   `0.2.0` and runs green — a true claim about 0.2.0 published under a heading
+   that says 0.3.1. This step is what makes the result honest.
+3. Run `tests/test_guard_adapter.py` (19 tests, real scanner) and the full suite.
+   Watch percent-escapes specifically: the slugger builds filenames from titles,
+   and the guard has recorded that as its most likely false positive. Report raw
+   URLs, not counts.
+4. **Send the result whichever way it goes**, and state explicitly that 19
+   fixture tests are not a corpus — their gate is "does 0.3.1 change our
+   verdicts", not "how often does the false positive fire".
+5. Green → one release: `>=0.2,<0.4`, uv tag `v0.3.1`, CLAUDE.md and README
+   updated together. Red → no bump, and the finding goes back to the guard.
+
+Until this lands, consumers of v0.4.0 resolve guard 0.2.0 (`pyproject.toml:25`).
+That is a silent under-defend: no build fails, so nothing surfaces it. The
+release in step 5 is what closes it.
+
 ## Phase 2 — Doors B/C (split: guard-independent first)
 
 Internal order follows the phase-2 doc's TDD steps, deliberately:
@@ -68,6 +100,31 @@ 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.
 
+## OKF v0.2 alignment — decisions between 3 and 4, code possibly later
+
+Everything through Phase 3 targets OKF v0.1. Upstream published v0.2 on
+2026-07-25. Detail and open questions: `docs/plan/okf-v0.2-alignment.md`.
+
+**Why the decisions must land before Phase 4 code, even if the code does not.**
+Phase 4 ports a *frozen, explicit* contract and uses the shared fixture suite as
+the cross-runtime conformance oracle. Freezing that contract while its relation
+to upstream v0.2 is undecided means freezing a v0.1 shape into two runtimes
+instead of one, and the fixture suite would then certify the drift rather than
+catch it. The expensive version of this mistake is discovered after the Node half
+exists; the cheap version is a decision recorded now.
+
+**Why it is not a phase.** v0.2's breaking surface is two supersessions, both
+with documented consumer fallbacks, and every new field is optional. The only
+measured shape problem is `DEFAULT`'s `generated` marker, which lives in commons'
+ingest-spec §5 layer and is therefore not this repo's to change. So the work is
+mostly *deciding and routing*, expressed through the Phase 3 profile object —
+not a new implementation stage.
+
+**Order inside the track.** Characterization and audit first (they add tests and
+change no behavior, so they are safe while the central question is still open),
+then the one blocking dependency — commons' answer on `generated` — and only then
+any migration, as its own release.
+
 ## Phase 4 — Node half (two clocks)
 
 **Coordination clock — start early, parallel to Stages 0–3, but only the
@@ -117,6 +174,8 @@ These are the objective checks that a stage is done and the next may begin:
    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.
+   Phase 3 split-table, not before; and the OKF v0.2 open questions V1–V5 are
+   each answered or explicitly deferred *in writing*, so the frozen contract
+   states its relation to upstream on purpose rather than by omission.
 5. **Throughout:** `mypy --strict src/`, `ruff check .`, `ruff format --check .`
    clean; boundary grep-gate empty.