chore(knowledge): group concepts into domain subfolders

[claude]

What changed

The knowledge bundle root held 29 concepts in one flat list. They are now grouped into domain subdirectories, each with its own index.md:

knowledge/
  index.md              okf_version + root concepts + subdirectory list
  knowledge-contract.md
  log.md
  foundations/    5     architecture, parser, vfs, builtins, parallel-execution
  security/       5     threat-model, security-testing, credential-injection, request-signing, http-transport
  runtimes/       7     python-builtin, zapcode, sqlite, coreutils-port, python-package, emscripten, browser
  integrations/   5     tool-contract, scripted-orchestration, git, ssh, interactive-shell
  operations/     7     testing, limitations, documentation, maintenance, release-process, performance-results, eval
  status/         1     builtin-inventory (+ builtins.json)

The groups mirror the sections the root index.md already used, so nothing is regrouped — only relocated. The root index now enumerates its own contents plus subdirectories rather than every document, which is what OKF §8 progressive disclosure asks for.

Frontmatter type values are unchanged. Directory conveys domain, type conveys kind; the two are independent, so a Subsystem Design in security/ and one in runtimes/ share a type and differ only in placement. Collapsing them to a single Spec type would have cost consumers the routing signal OKF keys on.

scripts/check_okf.py gains a dangling-link check: every bundle-relative link must resolve, with code spans and fenced blocks excluded from link scanning.

Why

Thirty flat files is past the point where a reader can see the shape of the bundle from its root. OKF supports hierarchy for exactly this, and the section groupings already existed in the index — they just were not reflected on disk.

The link check exists because this change proved the need for it. The bulk path rewrite treated ](...) inside code spans as markdown links and silently corrupted two documents: a TM-DOS-025 regex-backtracking payload in the threat model (grep "a](*b)*c" → grep "a](../*b)*c") and a changelog format placeholder in the release process. Both are reverted here, and the check now catches that class of damage.

Before / After

# before — 29 concepts flat at the bundle root
$ ls knowledge/*.md | wc -l
31

# after
$ just check-okf
knowledge: OKF v0.2 conformant (31 concepts, 7 index files, 1 log file)
okf-lint 0.1.1: knowledge conforms to OKF v0.2

References were rewritten repo-wide and verified to resolve:

$ # every knowledge/<doc>.md reference from outside the bundle
$ python3 - <<'PY'   # (dangling-reference scan)
0 dangling
PY

just pre-pr green: fmt, clippy, cargo test, 17 script tests, both OKF gates, and cargo vet (29 fully audited, 6 partially, 592 exempted).

Risk

• Low / Medium — mechanical, but wide: 109 files.
• 155 references from outside the bundle were rewritten (49 .rs, 27 .md, 8 .toml, 5 .yml, 4 .py, justfile), plus intra-bundle links. All verified to resolve; a dangling one now fails CI.
• Mostly comments and docs, with one real code path: crates/bashkit/tests/integration/limitations_doc_tests.rs reads limitations.md at runtime via CARGO_MANIFEST_DIR, so cargo test proves that move rather than assuming it.
• Merge conflicts are the practical risk — anything in flight that cites a knowledge/*.md path will conflict, so this wants merging promptly.

Checklist

• Tests added or updated — three cases for the dangling-link check (rejects a real dangling link; ignores links in code spans and fenced blocks; ignores external and anchor links)
• Backward compatibility considered — internal knowledge/tooling only; no public surface

---

Generated by Claude Code

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	bashkit	d4ab2df	Commit Preview URL Branch Preview URL	Jul 26 2026, 05:23 AM