akm-cli/docs/architecture/testing/okf-v0.2-conformance-runbook.md

akm (Agent Knowledge Manager) — a portable, local-first capability library for AI agents. Discover, load, share, and improve reusable skills, scripts, workflows, and knowledge across any shell-capable coding agent, including Claude Code, OpenCode, and Cur

# OKF v0.2 Conformance Re-Evaluation Runbook

Use this runbook after changing AKM's adapters, indexing, refs, writes, or lint
behavior. It is the acceptance procedure for
[first-class OKF format support](../specs/okf-support.md). It runs without
reading or modifying the host's AKM installation, bundle, configuration, cache,
or index.

The runbook deliberately tests observable behavior in addition to unit tests.
Passing adapter-local tests is not enough: the original failures happened
between recognition, persistence, search output, and command ref parsing.

**v0.2 update (#730):** upstream OKF minor-versioned to v0.2 (trust/provenance
family `generated`/`verified`/`sources`; lifecycle family `status`/
`stale_after`; an actor convention; `timestamp` superseded by `generated.at`
with a permitted fallback). Rules 1-9, Producer, and Lint below are unchanged
and still gate v0.1-only bundles; Rules 10-14 are new v0.2-specific gates. The
`okf` adapter stays **consumer-only** for both spec versions — see
`okf-support.md`'s v0.2 note for why AKM's own provenance *writes* go through
the proposal path onto AKM-native assets instead, and are out of this
runbook's scope (which evaluates the `okf` adapter's read/consumer behavior
against third-party and reference OKF bundles).

## Success Criteria

The evaluation passes only when all applicable statements are true:

| Rule | Required result |
|---|---|
| 1 | Every conformant non-reserved Markdown concept is represented by its path-minus-`.md` identity. Different paths cannot collide even when their titles match. Search emits that identity, and `show` accepts it. |
| 2 | Root and nested `index.md`/`log.md` files never become concepts. |
| 3 | Any non-empty `type` value survives unchanged and receives generic behavior when unknown. |
| 4 | Missing title falls back to the filename without changing identity. |
| 5 | If AKM modifies an existing OKF document, unknown nested frontmatter keys and the body survive unless the requested operation explicitly changes them. If AKM has no OKF write path, record this rule as not applicable rather than satisfied. |
| 6 | Inline, root-relative, relative, reference-style, and dangling concept links survive as durable directed relationships. A dangling target does not reject indexing. |
| 7 | Index synthesis is optional. Record whether it exists; do not fail solely because it does not. |
| 8 | Missing optional fields, unknown type, unknown keys, dangling links, and missing index files do not cause OKF semantics to be abandoned. |
| 9 | An unknown `okf_version` receives best-effort consumption. |
| 10 | `generated.at`, when present, takes precedence over legacy `timestamp` for the freshness/`updated` field; `timestamp` alone remains a fully valid fallback reading; neither present is not an AKM freshness error. |
| 11 | `verified` is read in both its list form and its v0.2-permitted single-mapping (no list dash) form; each entry survives as a durable `{by, at?}` pair; a malformed entry is dropped, never rejecting the document. |
| 12 | `sources` as a v0.2 object list (`resource` required; `id`/`title`/`author`/`usage_count`/`last_modified` optional) survives intact and distinctly from any pre-existing AKM `sources` convention — it must never be silently coerced into a bare string list (which would drop every entry). |
| 13 | `status` (`draft`/`stable`/`deprecated`) and `stale_after` are read verbatim when present; an unrecognized `status` value is ignored rather than guessed at, and neither field's absence is an error. |
| 14 | If AKM's own accepted-proposal writes stamp OKF v0.2 provenance onto AKM-native assets, record what is stamped and confirm it never applies to an OKF-adapter target (Rule 5 / runbook §10's write-rejection contract must stay intact). If AKM has no such write path, record this rule as not applicable. |
| Producer | If AKM claims to produce OKF, every emitted non-reserved Markdown file has parseable mapping frontmatter with a non-empty type, and reserved files have structural content. Otherwise record AKM as consumer-only. |
| Lint | `--fail-on-flagged` does not turn a dangling OKF body link into a failing exit status. |

Type participation in FTS and ranking is not a conformance gate. Record it for
regression awareness, but do not fail the OKF verdict because of it.

## 1. Prerequisites And Subject Capture

Run from the AKM repository root. Required host tools are Docker and Git. Bun,
Node, AKM, SQLite, and the Google checkout run only inside Docker.

Record the exact subject before testing:

```bash
git status --short
git rev-parse HEAD
git diff --stat
```

Uncommitted source changes are included in the Docker build because the local
working tree is the build context. Existing `node_modules`, `dist`, `.git`, and
developer state are excluded by `.dockerignore`.

Set stable names and pin the same upstream OKF snapshot used by the baseline
audit:

```bash
export AKM_OKF_IMAGE="akm-okf-eval:local"
export AKM_OKF_CONTAINER="akm-okf-eval"
export KC_REF="3fcbb9f828c2f23d109c855ee403c3a4c81f3a96"
export AKM_SUBJECT="$(git rev-parse HEAD)$(test -n "$(git status --porcelain)" && printf '%s' '-dirty')"
```

If intentionally updating the OKF reference revision, inspect the upstream
`okf/SPEC.md` diff first. Do not silently compare AKM against a changed spec.

**2026-07-30 bump (#730):** `KC_REF` was moved from `d44368c15e38e7c92481c5992e4f9b5b421a801d`
(the v0.1 baseline) to `3fcbb9f828c2f23d109c855ee403c3a4c81f3a96`, obtained via
`git ls-remote https://github.com/GoogleCloudPlatform/knowledge-catalog.git HEAD`
and cross-checked against `git ls-remote ... refs/heads/main` (both resolved to
the same commit) — a real, verified upstream commit, not an invented one. The
`okf/SPEC.md` content at that exact commit was fetched and confirmed to state
"This document specifies OKF version 0.2" with the `generated`/`verified`
field definitions this update implements against. This runbook update was done
without Docker access to actually run the container-based evaluation in
this session; §§2-13 below are updated to describe the v0.2 procedure a
maintainer should run, but have not been re-executed end-to-end against a
live container since this bump. Treat the `KC_REF` bump and the procedural
updates as reviewed-but-unexecuted until a maintainer runs this runbook for
real.

## 2. Build The Isolated AKM Image

This image contains the working tree under test, Bun, Git, and SQLite. It does
not mount the host home directory.

```bash
docker build \
  --build-arg AKM_SUBJECT="$AKM_SUBJECT" \
  --tag "$AKM_OKF_IMAGE" \
  --file - . <<'DOCKERFILE'
FROM oven/bun:1.3.6-debian
ARG AKM_SUBJECT
LABEL org.opencontainers.image.revision="$AKM_SUBJECT"
RUN apt-get update && apt-get install -y --no-install-recommends git ca-certificates sqlite3 && rm -rf /var/lib/apt/lists/*
WORKDIR /app
COPY . .
RUN bun install --frozen-lockfile
RUN bun run build
ENV PATH="/app/dist:${PATH}"
CMD ["sleep", "infinity"]
DOCKERFILE
```

Start a long-lived evaluation container with an isolated home:

```bash
docker rm -f "$AKM_OKF_CONTAINER" 2>/dev/null || true
docker run --detach \
  --name "$AKM_OKF_CONTAINER" \
  --env HOME=/tmp/akm-home \
  --env NO_COLOR=1 \
  "$AKM_OKF_IMAGE"
docker exec "$AKM_OKF_CONTAINER" mkdir -p /tmp/akm-home
docker exec "$AKM_OKF_CONTAINER" akm --version
```

Pass condition: the reported version is the code under test, and no command
references the host's home or XDG directories.

## 3. Clone And Pin Google's OKF Repository

```bash
docker exec "$AKM_OKF_CONTAINER" git clone \
  https://github.com/GoogleCloudPlatform/knowledge-catalog.git /tmp/kc
docker exec "$AKM_OKF_CONTAINER" git -C /tmp/kc checkout "$KC_REF"
docker exec "$AKM_OKF_CONTAINER" git -C /tmp/kc rev-parse HEAD
docker exec "$AKM_OKF_CONTAINER" sh -lc 'nl -ba /tmp/kc/okf/SPEC.md'
```

Pass condition: the printed revision equals `KC_REF`. Retain the numbered spec
output with the evaluation record.

## 4. Run Focused Existing Tests

Run the current adapter, registry, type, dispatch, and reserved-name tests:

```bash
docker exec "$AKM_OKF_CONTAINER" bun test \
  tests/integration/okf-conformance.test.ts \
  tests/core/akm-markdown.test.ts \
  tests/core/adapter/okf-adapter.test.ts \
  tests/core/adapter/conformance.test.ts \
  tests/core/adapter/registry.test.ts \
  tests/indexer/installations.test.ts \
  tests/core/type-token-contract.test.ts \
  tests/integration/indexer/adapter-dispatch.test.ts \
  tests/integration/reserved-filename-conformance.test.ts
```

v0.2 update (#730): also run the promotion-path provenance-stamping coverage
(D2 — write side, AKM-native assets only, not the `okf` adapter itself) and
the OKF format-family golden:

```bash
docker exec "$AKM_OKF_CONTAINER" bun test \
  tests/integration/proposals.test.ts \
  tests/core/adapter/okf-adapter.test.ts
```

After implementing fixes, the repository should also contain focused
end-to-end tests for these behaviors:

| Coverage to require | Minimum assertion |
|---|---|
| Official OKF fixture | Persisted concept count equals all non-reserved `.md` files. |
| Identity | Same type/title at two paths produces two refs and two rows. |
| Search/show | Search ref is `<bundle>//<path-minus-.md>` and `show` accepts it. |
| Missing index | Explicitly configured or otherwise recognized OKF still uses OKF semantics. |
| v0.2 `generated`/`timestamp` | `generated.at` wins when both are present; `timestamp` alone still satisfies freshness; neither present is not an error. |
| v0.2 `verified` | Both the list form and the single-mapping form persist as a non-empty `{by, at?}` array. |
| v0.2 `sources` | An object list survives intact and distinctly from the bare AKM `sources: string[]` convention. |
| v0.2 `status`/`stale_after` | Both read verbatim when present; an unrecognized `status` is ignored, not guessed at. |
| D2 promotion-path stamping | An accepted AKM-native proposal's written frontmatter carries `generated`/`verified` (and `sources` when `evidenceSources` was present); an OKF-adapter target is still rejected before any write (Rule 5 / write-rejection contract unchanged). |
| Links | Root-relative, relative, reference-style, and dangling links survive persistence. |
| Unknown values | Unknown type/version/key never rejects the bundle. |
| Writes | OKF writes are either blocked or produce conformant documents through adapter-owned placement. |
| Reserved names | Concept writers reject `index` and `log` at every depth. |
| Lint | A dangling OKF body link remains non-blocking under `--fail-on-flagged`. |

Run those new files explicitly in addition to the existing suite. Do not rely
only on test names containing `conformance`; the original conformance suite
tested adapter-local folds, not durable behavior.

## 5. Initialize Container-Local AKM State

```bash
docker exec "$AKM_OKF_CONTAINER" akm bundle create \
  --dir /tmp/akm-home/akm \
  --set-default
```

Pass condition: config is written under `/tmp/akm-home`, not a mounted host
path.

## 6. Evaluate Google's GA4 Bundle

Add and fully index the real producer output:

```bash
docker exec "$AKM_OKF_CONTAINER" akm bundle add \
  /tmp/kc/okf/bundles/ga4 \
  --name okf-ga4
docker exec "$AKM_OKF_CONTAINER" akm index --full
docker exec "$AKM_OKF_CONTAINER" akm bundle list
docker exec "$AKM_OKF_CONTAINER" akm search orders \
  --format json --detail full --limit 100
docker exec "$AKM_OKF_CONTAINER" akm search events \
  --format json --detail full --limit 100
docker exec "$AKM_OKF_CONTAINER" akm show \
  okf-ga4//tables/events_ --format json --detail full
```

The `orders` search is informational, not a conformance gate. OKF does not
require a particular search index. The `show` command is a gate because it
tests whether the path identity emitted by the adapter remains usable through
the consumer.

Verify adapter ownership, count, type, and identity directly in the derived
index. These SQL gates target the exact v22 `entries` generation. A managed
index open discards any generation whose version or complete schema fingerprint
does not match v22, then `akm index --full` repopulates the canonical table from
source. Reader-only openers reject an incompatible generation instead of
serving legacy columns.

```bash
docker exec "$AKM_OKF_CONTAINER" sh -lc '
set -eu
db=/tmp/akm-home/.local/share/akm/index.db
root=/tmp/kc/okf/bundles/ga4
version=$(sqlite3 "$db" "SELECT value FROM index_meta WHERE key='"'"'version'"'"';")
columns=$(sqlite3 "$db" "SELECT group_concat(name, '"'"','"'"') FROM (SELECT name FROM pragma_table_xinfo('"'"'entries'"'"') ORDER BY cid);")
expected=$(find "$root" -type f -name "*.md" ! -iname "index.md" ! -iname "log.md" | wc -l)
actual=$(sqlite3 "$db" "SELECT count(*) FROM entries WHERE bundle_id='"'"'okf-ga4'"'"';")
adapter=$(sqlite3 "$db" "SELECT group_concat(DISTINCT adapter_id) FROM entries WHERE bundle_id='"'"'okf-ga4'"'"';")
printf "schema=v%s columns=%s expected_concepts=%s actual_concepts=%s adapter=%s\n" "$version" "$columns" "$expected" "$actual" "$adapter"
test "$version" = "22"
test "$columns" = "id,item_ref,bundle_id,component_id,concept_id,adapter_id,type,file_path,content_hash,document_json,search_text,derived_from"
test "$expected" -eq "$actual"
test "$adapter" = "okf"
sqlite3 -header -column "$db" "SELECT item_ref, concept_id, type, adapter_id, file_path FROM entries WHERE bundle_id='"'"'okf-ga4'"'"' ORDER BY item_ref;"
'
```

Pass conditions:

- `index_meta.version` is `22` and `entries` has exactly the canonical v22
  column sequence shown above.
- Expected and actual counts match.
- Every row has `adapter_id=okf`.
- `item_ref` is `okf-ga4//<concept_id>`.
- `BigQuery Dataset`, `BigQuery Table`, and `Reference` survive unchanged.
- No `index.md` or `log.md` row exists.
- `akm show okf-ga4//tables/events_` succeeds.

Verify that search emits path refs rather than title refs:

```bash
docker exec "$AKM_OKF_CONTAINER" sh -lc '
set -eu
akm search events --format json --detail full --limit 100 > /tmp/ga4-search.json
bun -e '\''import fs from "node:fs"; const r=JSON.parse(fs.readFileSync("/tmp/ga4-search.json","utf8")); const h=r.hits.find((x)=>x.path.endsWith("/tables/events_.md")); if(!h) throw new Error("events_ hit missing"); if(h.ref!=="okf-ga4//tables/events_") throw new Error(`wrong ref: ${h.ref}`);'\''
'
```

## 7. Create Adversarial Bundles Inside Docker

Create all fixtures inside the container. Nothing is written to the host.

```bash
docker exec -i "$AKM_OKF_CONTAINER" sh -lc 'tee /tmp/create-okf-fixtures.mjs >/dev/null' <<'FIXTURE_SCRIPT'
import fs from "node:fs";
import path from "node:path";

function write(root, rel, content) {
  const dest = path.join(root, rel);
  fs.mkdirSync(path.dirname(dest), { recursive: true });
  fs.writeFileSync(dest, content);
}

const root = "/tmp/okf-adversarial";
write(root, "index.md", `---
okf_version: "9.9"
---

# Adversarial bundle
`);
write(root, "log.md", `# Update Log

## 2026-07-23
* **Update**: Created the evaluation bundle.
`);
write(root, "sub/index.md", `# Subdirectory

* [Duplicate](duplicate-b.md)
`);
write(root, "plain.md", `# Plain

No frontmatter. Marker: plain-body-only.
`);
write(root, "notype.md", `---
title: No Type
optional_vendor_key: retained-if-roundtripped
---

Missing type. Marker: no-type-body-only.
`);
write(root, "unknown.md", `---
type: Some Vendor Thing
title: Vendor Item
vendor_meta:
  owner: vendor
  revision: 7
---

# Overview

Marker: vendor-body-only.

[Root](/target.md)
[Relative](./relative.md)
[Dangling](/missing.md)
[Reference style][vendor-reference]

[vendor-reference]: /ref-target.md
`);
write(root, "target.md", `---
type: Known
title: Root Target
---

Target body.
`);
write(root, "relative.md", `---
type: Known
title: Relative Target
---

Relative body.
`);
write(root, "ref-target.md", `---
type: Known
title: Reference Target
---

Reference target body.
`);
write(root, "duplicate-a.md", `---
type: Vendor Duplicate
title: Same Title
---

First concept.
`);
write(root, "sub/duplicate-b.md", `---
type: Vendor Duplicate
title: Same Title
---

Second concept.
`);
write(root, ".hidden/hidden.md", `---
type: Hidden Concept
title: Hidden Concept
---

Hidden directory concept.
`);
write(root, "bin/bin-doc.md", `---
type: Bin Concept
title: Bin Concept
---

Bin directory concept.
`);
write(root, "knowledge/roundtrip.md", `---
type: Some Vendor Thing
title: Round Trip
vendor_meta:
  owner: preserve-me
  nested:
    value: 42
---

Round-trip body marker.
`);
// v0.2 update (#730): the full trust/provenance/lifecycle family in one
// concept — generated (supersedes legacy timestamp), verified (list form),
// object-list sources, status, stale_after.
write(root, "knowledge/v2-full.md", `---
type: Some Vendor Thing
title: V0.2 Full Family
generated:
  by: reference_agent/gemini-2.5-pro
  at: 2026-06-20T22:53:05Z
verified:
  - by: human:ahormati
    at: 2026-06-25T09:00:00Z
  - by: process:finance-nightly
    at: 2026-06-26T03:00:00Z
sources:
  - resource: https://example.com/data/export.csv
    id: main-dataset
    title: Example export
    author: human:jdoe
    usage_count: 3
    last_modified: "2026-06-01"
  - resource: gs://acme-bucket/raw.parquet
status: stable
stale_after: "2026-12-31"
---

V0.2 full-family body marker.
`);
// v0.2 update (#730): verified SINGLE-MAPPING form (no list dash) + draft status.
write(root, "knowledge/v2-verified-single.md", `---
type: Some Vendor Thing
title: V0.2 Verified Single Mapping
generated:
  by: human:ahormati
  at: 2026-06-18T00:00:00Z
verified:
  by: human:ahormati
  at: 2026-06-18T00:05:00Z
status: draft
---

V0.2 single-mapping verified body marker.
`);

const noIndex = "/tmp/okf-no-index";
write(noIndex, "vendor.md", `---
type: Some Vendor Thing
title: No Index Vendor
vendor_key: keep
---

No-index marker.
`);

const overlap = "/tmp/okf-wiki-overlap";
write(overlap, "index.md", "# Root index\n");
write(overlap, "schema.md", "# Wiki schema\n");
write(overlap, "pages/page.md", `---
page_kind: concept
---

# Wiki page
`);

const lintRoot = "/tmp/okf-lint-dangling";
write(lintRoot, "index.md", "# Root index\n");
write(lintRoot, "concepts/source.md", `---
type: Reference
title: Dangling Source
---

[Future concept](/concepts/not-yet-written.md)
`);
FIXTURE_SCRIPT
docker exec "$AKM_OKF_CONTAINER" bun /tmp/create-okf-fixtures.mjs
```

Add the bundles and rebuild:

```bash
docker exec "$AKM_OKF_CONTAINER" akm bundle add \
  /tmp/okf-adversarial --name adversarial
docker exec "$AKM_OKF_CONTAINER" akm bundle add \
  /tmp/okf-no-index --name noindex
docker exec "$AKM_OKF_CONTAINER" akm bundle add \
  /tmp/okf-wiki-overlap --name overlap
docker exec "$AKM_OKF_CONTAINER" akm bundle add \
  /tmp/okf-lint-dangling --name lint-dangling
docker exec "$AKM_OKF_CONTAINER" akm index --full
```

## 8. Assert Recognition And Tolerance

Run the database assertions:

```bash
docker exec "$AKM_OKF_CONTAINER" sh -lc '
set -eu
db=/tmp/akm-home/.local/share/akm/index.db

test "$(sqlite3 "$db" "SELECT group_concat(DISTINCT adapter_id) FROM entries WHERE bundle_id='"'"'adversarial'"'"';")" = "okf"
test "$(sqlite3 "$db" "SELECT group_concat(DISTINCT adapter_id) FROM entries WHERE bundle_id='"'"'noindex'"'"';")" = "okf"
test "$(sqlite3 "$db" "SELECT group_concat(DISTINCT adapter_id) FROM entries WHERE bundle_id='"'"'overlap'"'"';")" = "llm-wiki"

test "$(sqlite3 "$db" "SELECT type FROM entries WHERE item_ref='"'"'adversarial//unknown'"'"';")" = "Some Vendor Thing"
test "$(sqlite3 "$db" "SELECT type FROM entries WHERE item_ref='"'"'noindex//vendor'"'"';")" = "Some Vendor Thing"

test "$(sqlite3 "$db" "SELECT count(*) FROM entries WHERE bundle_id='"'"'adversarial'"'"' AND type='"'"'Vendor Duplicate'"'"';")" -eq 2
test "$(sqlite3 "$db" "SELECT count(*) FROM entries WHERE item_ref IN ('"'"'adversarial//.hidden/hidden'"'"','"'"'adversarial//bin/bin-doc'"'"');")" -eq 2
test "$(sqlite3 "$db" "SELECT count(*) FROM entries WHERE bundle_id='"'"'adversarial'"'"' AND lower(file_path) GLOB '"'"'*/*index.md'"'"';")" -eq 0
test "$(sqlite3 "$db" "SELECT count(*) FROM entries WHERE bundle_id='"'"'adversarial'"'"' AND lower(file_path) GLOB '"'"'*/*log.md'"'"';")" -eq 0

sqlite3 -header -column "$db" "SELECT item_ref,type,adapter_id FROM entries WHERE item_ref IN ('"'"'adversarial//plain'"'"','"'"'adversarial//notype'"'"') ORDER BY item_ref;"
sqlite3 -header -column "$db" "SELECT bundle_id,item_ref,type,adapter_id,file_path FROM entries WHERE bundle_id IN ('"'"'adversarial'"'"','"'"'noindex'"'"','"'"'overlap'"'"') ORDER BY bundle_id,item_ref;"
'
```

These assertions are permanent gates for the no-index source, duplicate title
pair, hidden directory, and `bin` directory. A change is not complete until
each conformant path-defined concept survives independently.
The plain and missing-type rows are printed for observation but are not gates:
those files are nonconformant producers, and OKF does not require a consumer to
accept a concept whose required `type` is absent.

v0.2 update (#730) — assert the trust/provenance/lifecycle family on the two
new fixtures (Rules 10-13):

```bash
docker exec "$AKM_OKF_CONTAINER" sh -lc '
set -eu
db=/tmp/akm-home/.local/share/akm/index.db

full=$(sqlite3 "$db" "SELECT document_json FROM entries WHERE item_ref='"'"'adversarial//knowledge/v2-full'"'"';")
bun -e '\''
const e = JSON.parse(process.argv[1]);
if (e.updated !== "2026-06-20T22:53:05Z") throw new Error(`generated.at not preferred: ${e.updated}`);
if (e.provenance?.generatedBy !== "reference_agent/gemini-2.5-pro") throw new Error("generatedBy missing");
if (!Array.isArray(e.provenance?.verified) || e.provenance.verified.length !== 2) throw new Error("verified list wrong length");
if (!Array.isArray(e.provenance?.sources) || e.provenance.sources.length !== 2) throw new Error("sources object-list wrong length");
if (e.provenance.sources[0].resource !== "https://example.com/data/export.csv") throw new Error("sources[0].resource wrong");
if (e.lifecycleStatus !== "stable") throw new Error(`lifecycleStatus wrong: ${e.lifecycleStatus}`);
if (e.staleAfter !== "2026-12-31") throw new Error(`staleAfter wrong: ${e.staleAfter}`);
// The pre-existing AKM-native sources:string[] field (wiki citations) must
// NEVER be populated by the okf adapter -- it is a completely different field.
if (e.sources !== undefined) throw new Error("bare sources field must stay unset for okf-adapter documents");
'\'' "$full"

single=$(sqlite3 "$db" "SELECT document_json FROM entries WHERE item_ref='"'"'adversarial//knowledge/v2-verified-single'"'"';")
bun -e '\''
const e = JSON.parse(process.argv[1]);
if (!Array.isArray(e.provenance?.verified) || e.provenance.verified.length !== 1) throw new Error("single-mapping verified did not normalize to a one-element array");
if (e.provenance.verified[0].by !== "human:ahormati") throw new Error("verified[0].by wrong");
if (e.lifecycleStatus !== "draft") throw new Error(`lifecycleStatus wrong: ${e.lifecycleStatus}`);
'\'' "$single"
'
```

Pass condition: both `bun -e` checks above exit zero (no thrown error).

Verify unknown type filtering and path-based show:

```bash
docker exec "$AKM_OKF_CONTAINER" akm search Vendor \
  --type 'Some Vendor Thing' \
  --format json --detail full --limit 100
docker exec "$AKM_OKF_CONTAINER" akm show \
  adversarial//unknown --format json --detail full
docker exec "$AKM_OKF_CONTAINER" akm show \
  'adversarial//unknown#overview' --format json --detail full
docker exec "$AKM_OKF_CONTAINER" akm show \
  noindex//vendor --format json --detail full
```

Pass condition: both `show` calls succeed without requiring an AKM type-directory
prefix.

Verify the search ref for the unknown-type document:

```bash
docker exec "$AKM_OKF_CONTAINER" sh -lc '
set -eu
akm search Vendor --format json --detail full --limit 100 > /tmp/vendor-search.json
bun -e '\''import fs from "node:fs"; const r=JSON.parse(fs.readFileSync("/tmp/vendor-search.json","utf8")); const h=r.hits.find((x)=>x.path==="/tmp/okf-adversarial/unknown.md"); if(!h) throw new Error("vendor hit missing"); if(h.ref!=="adversarial//unknown") throw new Error(`wrong ref: ${h.ref}`);'\''
'
```

## 9. Assert Durable Link Semantics

The adversarial `unknown.md` has four distinct concept targets:

- `target` from a bundle-root-relative inline link.
- `relative` from a relative inline link.
- `missing` from a dangling bundle-root-relative inline link.
- `ref-target` from a reference-style Markdown link.

The dangling target must remain represented as an edge even though no target
document exists.

The current `IndexDocument` contract has a first-class `links` field, so the
minimal persistence acceptance test is:

```bash
docker exec "$AKM_OKF_CONTAINER" sh -lc '
set -eu
db=/tmp/akm-home/.local/share/akm/index.db
links=$(sqlite3 "$db" "SELECT json_extract(document_json,'"'"'$.links'"'"') FROM entries WHERE item_ref='"'"'adversarial//unknown'"'"';")
printf "durable_links=%s\n" "$links"
bun -e '\''const links=JSON.parse(process.argv[1]); const want=["target","relative","missing","ref-target"]; for(const x of want) if(!links.includes(x)) throw new Error(`missing link ${x}`); if(links.length!==want.length) throw new Error(`unexpected links ${JSON.stringify(links)}`);'\'' "$links"
'
```

If the implementation intentionally moves links into a dedicated relation
table, replace this assertion with an equivalent query against that table and
retain a test proving all four directed edges. Do not count LLM-extracted entity
relations as OKF concept links.

## 10. Evaluate Writable OKF Targets And Round-Trip Behavior

AKM has two conformant policies for an OKF source. The 0.9.0 `okf` adapter uses
the consumer-only policy:

| Policy | Required behavior |
|---|---|
| Consumer-only/read-only | The write command fails before creating or changing a file. |
| Writable OKF | Placement is adapter-owned, every new concept is conformant, and metadata-only edits preserve unknown keys and body bytes. |

**v0.2 update (#730) — Rule 14 scope note:** the assertions below are entirely
about writes *targeting an OKF-adapter bundle* (`adversarial`), and that
policy is unchanged by the v0.2 update — the write command below must still
fail before touching disk. AKM's new v0.2 provenance-stamping behavior (D2)
is a completely separate code path: accepting a proposal stamps
`generated`/`verified` frontmatter onto an **AKM-native** target through
`promoteProposal`, never through the `okf` adapter — it is orthogonal to
every assertion in this section. This runbook does not script a manual D2
spot-check (the `akm proposal`/`akm remember` CLI surface for driving one
deterministically end-to-end was not re-verified against this container in
this update); `tests/integration/proposals.test.ts`'s `"D2 (#730): ..."`
suite is the authoritative, already-passing coverage for Rule 14 — rerun it
if you need to re-confirm this specific behavior:
`bun test tests/integration/proposals.test.ts -t D2`.

Attempt a superseding write while recording its exit status:

```bash
set +e
docker exec "$AKM_OKF_CONTAINER" akm remember \
  'Correction written during OKF conformance evaluation' \
  --name correction \
  --bundle adversarial \
  --supersedes adversarial//knowledge/roundtrip
export OKF_WRITE_STATUS=$?
set -e
printf 'okf_write_status=%s\n' "$OKF_WRITE_STATUS"
```

If the status is non-zero, verify that no correction was created and record the
source as consumer-only/read-only.

```bash
if test "$OKF_WRITE_STATUS" -ne 0; then
  docker exec "$AKM_OKF_CONTAINER" test ! -e /tmp/okf-adversarial/memories/correction.md
fi
```

If the status is zero, verify the old document's unknown nested key, type, and
body survived, and verify the new document has a non-empty `type`:

```bash
if test "$OKF_WRITE_STATUS" -eq 0; then
  docker exec "$AKM_OKF_CONTAINER" bun -e '
    import fs from "node:fs";
    import { parse } from "yaml";
    function split(raw) {
      const m=raw.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)([\s\S]*)$/);
      if(!m) throw new Error("frontmatter missing");
      return {fm:parse(m[1]),body:m[2]};
    }
    const old=split(fs.readFileSync("/tmp/okf-adversarial/knowledge/roundtrip.md","utf8"));
    if(old.fm.type!=="Some Vendor Thing") throw new Error("type changed");
    if(old.fm.vendor_meta?.owner!=="preserve-me") throw new Error("unknown key lost");
    if(old.fm.vendor_meta?.nested?.value!==42) throw new Error("nested unknown key lost");
    if(!old.body.includes("Round-trip body marker.")) throw new Error("body changed");
    const created=split(fs.readFileSync("/tmp/okf-adversarial/memories/correction.md","utf8"));
    if(typeof created.fm.type!=="string" || !created.fm.type.trim()) throw new Error("new OKF concept has no type");
  '
fi
```

Test that concept writers reject reserved filenames. This must fail whether the
source is generally writable or consumer-only:

```bash
RESERVED_BEFORE=$(docker exec "$AKM_OKF_CONTAINER" sh -lc 'find /tmp/okf-adversarial -type f \( -iname "index.md" -o -iname "log.md" \) -exec sha256sum {} + | sort | sha256sum')
set +e
docker exec "$AKM_OKF_CONTAINER" akm remember \
  'Reserved index payload' --name index --bundle adversarial
INDEX_WRITE_STATUS=$?
docker exec "$AKM_OKF_CONTAINER" akm remember \
  'Reserved log payload' --name log --bundle adversarial
LOG_WRITE_STATUS=$?
set -e
test "$INDEX_WRITE_STATUS" -ne 0
test "$LOG_WRITE_STATUS" -ne 0
RESERVED_AFTER=$(docker exec "$AKM_OKF_CONTAINER" sh -lc 'find /tmp/okf-adversarial -type f \( -iname "index.md" -o -iname "log.md" \) -exec sha256sum {} + | sort | sha256sum')
test "$RESERVED_BEFORE" = "$RESERVED_AFTER"
docker exec "$AKM_OKF_CONTAINER" test ! -e /tmp/okf-adversarial/memories/index.md
docker exec "$AKM_OKF_CONTAINER" test ! -e /tmp/okf-adversarial/memories/log.md
```

A future structural index/log generator is allowed to write those files through
an explicitly structural path. The ban applies to concept writers, not to valid
structural production.

## 11. Evaluate Lint

Run lint against a conformant bundle whose only issue is a dangling body link:

```bash
docker exec "$AKM_OKF_CONTAINER" akm lint \
  --dir /tmp/okf-lint-dangling \
  --fail-on-flagged
```

Also run lint against the official bundle:

```bash
docker exec "$AKM_OKF_CONTAINER" akm lint \
  --dir /tmp/kc/okf/bundles/ga4 \
  --fail-on-flagged
```

Pass condition: both commands exit zero. The adapter-aware OKF lint walk checks
all concept paths, including ordinary dot directories and `bin/`. It may report
the dangling target as informational or non-blocking, but
`--fail-on-flagged` must not turn that spec-tolerated link into CI failure.

## 12. Optional Producer Validation

Skip this section if AKM explicitly remains consumer-only. Do not classify the
absence of a producer as a consumer failure.

If AKM adds a producer, save this checker inside the container:

```bash
docker exec -i "$AKM_OKF_CONTAINER" sh -lc 'tee /tmp/check-okf-producer.mjs >/dev/null' <<'CHECKER'
import fs from "node:fs";
import path from "node:path";
import { parse } from "yaml";

const root = path.resolve(process.argv[2]);
const errors = [];

function frontmatter(raw) {
  const m = raw.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)([\s\S]*)$/);
  if (!m) return null;
  try {
    const data = parse(m[1]);
    return data && typeof data === "object" && !Array.isArray(data)
      ? { data, body: m[2] }
      : null;
  } catch {
    return null;
  }
}

function walk(dir) {
  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
    const abs = path.join(dir, entry.name);
    if (entry.isDirectory()) {
      walk(abs);
      continue;
    }
    if (!entry.isFile() || !entry.name.toLowerCase().endsWith(".md")) continue;
    const rel = path.relative(root, abs).replaceAll(path.sep, "/");
    const lower = entry.name.toLowerCase();
    const raw = fs.readFileSync(abs, "utf8");
    if (lower === "index.md") {
      const fm = frontmatter(raw);
      if (fm && rel !== "index.md") errors.push(`${rel}: nested index has frontmatter`);
      if (fm && Object.keys(fm.data).some((key) => key !== "okf_version")) {
        errors.push(`${rel}: root index frontmatter contains keys other than okf_version`);
      }
      continue;
    }
    if (lower === "log.md") {
      for (const line of raw.split(/\r?\n/)) {
        if (line.startsWith("## ") && !/^## \d{4}-\d{2}-\d{2}$/.test(line)) {
          errors.push(`${rel}: invalid log date heading ${line}`);
        }
      }
      continue;
    }
    const fm = frontmatter(raw);
    if (!fm) {
      errors.push(`${rel}: missing or invalid mapping frontmatter`);
      continue;
    }
    if (typeof fm.data.type !== "string" || !fm.data.type.trim()) {
      errors.push(`${rel}: missing non-empty type`);
    }
  }
}

if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
  throw new Error(`bundle not found: ${root}`);
}
walk(root);
if (errors.length) {
  for (const error of errors) console.error(error);
  process.exit(1);
}
console.log(`OKF producer check passed: ${root}`);
CHECKER
```

Generate a bundle through the public AKM producer command, then run:

```bash
docker exec "$AKM_OKF_CONTAINER" bun \
  /tmp/check-okf-producer.mjs /path/to/generated/bundle
```

The producer check is intentionally independent of AKM's parser. A producer
must not validate itself with the same lenient parser used by its consumer.

## 13. Run Repository Verification

After focused behavior passes, run the repository's normal checks inside the
same image:

```bash
docker exec "$AKM_OKF_CONTAINER" bun run check
docker exec "$AKM_OKF_CONTAINER" bun run build
```

For pre-commit verification, follow repository policy inside Docker:

```bash
docker exec "$AKM_OKF_CONTAINER" bunx biome check --write src/ tests/
docker exec "$AKM_OKF_CONTAINER" bun run check
```

The write-capable Biome command changes only the container copy. If it reports
changes, apply the equivalent formatting to the host working tree deliberately
and rebuild the image before treating the result as final.

## 14. Record The New Verdict

Create a result record containing:

```text
AKM commit and dirty state:
AKM version:
OKF repository commit (KC_REF):
Docker base image:
Focused tests:
Full check:
Official GA4 expected/actual concept count:
Official adapter IDs:
Official type values:
Official show-by-concept-ID result:
Adversarial adapter ID:
Missing-index adapter ID:
Overlap precedence result:
Duplicate-title row count:
Hidden/bin concept result:
Unknown type result:
Unknown version result:
Durable link targets:
Dangling-link indexing result:
Unknown-key round-trip result or N/A:
Reserved concept-write result:
Producer result or consumer-only:
Lint --fail-on-flagged result:
v0.2 generated.at precedence result:
v0.2 verified (list form) result:
v0.2 verified (single-mapping form) result:
v0.2 sources (object list) result:
v0.2 status/stale_after result:
D2 promotion-path provenance-stamping result or N/A:
Rule 1 verdict:
Rule 2 verdict:
Rule 3 verdict:
Rule 4 verdict:
Rule 5 verdict:
Rule 6 verdict:
Rule 7 verdict:
Rule 8 verdict:
Rule 9 verdict:
Rule 10 verdict:
Rule 11 verdict:
Rule 12 verdict:
Rule 13 verdict:
Rule 14 verdict:
Remaining deviations:
Remaining undetermined items:
```

Do not mark a rule satisfied from a direct adapter unit test if the durable or
CLI path still loses the behavior. Do not mark Rule 5 satisfied merely because
unknown keys did not cause a parse error. Likewise, do not mark Rules 10-13
satisfied from `tests/core/adapter/okf-adapter.test.ts` alone if the durable
persist path (`indexer/scan/doc-to-entry.ts`) or the `show`/`search` output
loses a field — this repo has a documented history (D1's own GREEN commit) of
`recognize()` returning a field correctly while a separate persistence-layer
reconstruction step silently dropped it before it ever reached `document_json`.

## 15. Cleanup

Remove all custom containers and images:

```bash
docker rm -f "$AKM_OKF_CONTAINER"
docker image rm "$AKM_OKF_IMAGE"
```

Optional verification that no host AKM state changed:

```bash
git status --short
```

Only intentional source/test/documentation changes should appear. No
`~/.config/akm`, `~/.cache/akm`, or local AKM index should have been read or
modified by this runbook.