chore(knowledge): make the knowledge bundle actually OKF v0.2 conformant

.github/workflows/ci.yml

@@ -44,6 +44,18 @@ jobs:
         env:
           RUSTDOCFLAGS: "-D warnings"
 
+      # OKF v0.2 conformance of the knowledge bundle. okf-lint enforces the
+      # spec; check_okf.py enforces the bundle-local conventions it does not
+      # cover. See knowledge/knowledge-contract.md for why both run.
+      # Keep the version and --max-line-length in lockstep with the justfile.
+      - name: Install okf-lint
+        run: cargo install okf-lint --version 0.1.1 --locked
+
+      - name: Check knowledge bundle (OKF)
+        run: |
+          python3 scripts/check_okf.py knowledge
+          okf-lint knowledge --max-line-length 10000
+
   wasm:
     # std::time panics on wasm32-unknown-unknown, so bashkit routes clock reads
     # through src/time_compat.rs (web-time on wasm32). This job keeps the crate

AGENTS.md

@@ -19,10 +19,11 @@ Fix root cause. Unsure: read more code; if stuck, ask w/ short options. Unrecogn
 
 ### Knowledge
 
-`knowledge/` is the canonical OKF bundle and persistent project memory. Read relevant knowledge before changing behavior, and update it in the same change when decisions, behavior, constraints, threats, tests, or operations change. New durable engineering knowledge belongs there; see `knowledge/index.md` for the maintenance contract.
+`knowledge/` is the canonical OKF bundle and persistent project memory. Read relevant knowledge before changing behavior, and update it in the same change when decisions, behavior, constraints, threats, tests, or operations change. New durable engineering knowledge belongs there; see `knowledge/knowledge-contract.md` for the maintenance contract and the OKF v0.2 rules (`just check-okf` enforces them).
 
 | Knowledge | Description |
 |------|-------------|
+| knowledge-contract | Knowledge maintenance rules + OKF v0.2 conformance rules |
 | architecture | Core interpreter architecture, module structure |
 | parser | Bash syntax parser design |
 | vfs | Virtual filesystem abstraction |

justfile

@@ -2,6 +2,12 @@
 # Install just: ./init-cloud-env.sh (pre-built) or cargo install just
 # Usage: just <recipe>   (or: just --list)
 
+# Upstream OKF spec linter, pinned. Keep in lockstep with .github/workflows/ci.yml.
+okf_lint_version := "0.1.1"
+
+# Knowledge docs wrap prose at author discretion, so the line-length rule is off.
+okf_lint_max_line_length := "10000"
+
 # Default: show available commands
 default:
     @just --list
@@ -38,6 +44,26 @@ check:
     cargo clippy --all-targets -- -D warnings
     cargo test
     python3 -m unittest discover -s scripts/tests -p 'test_*.py'
+    just check-okf
+
+# okf-lint covers the spec rules; check_okf.py covers the bundle-local
+# conventions it does not enforce (see knowledge/knowledge-contract.md).
+# okf-lint is pinned in CI and skipped here when absent: just install-okf-lint
+# Validate the knowledge/ OKF v0.2 bundle
+check-okf:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    python3 scripts/check_okf.py knowledge
+    if command -v okf-lint >/dev/null; then
+        okf-lint knowledge --max-line-length {{ okf_lint_max_line_length }}
+        echo "okf-lint {{ okf_lint_version }}: knowledge conforms to OKF v0.2"
+    else
+        echo "okf-lint not installed — skipping (just install-okf-lint)"
+    fi
+
+# Install the pinned upstream OKF spec linter
+install-okf-lint:
+    cargo install okf-lint --version {{ okf_lint_version }} --locked
 
 # Lint and format-check Python bindings
 python-lint:

knowledge/architecture.md

@@ -1,6 +1,11 @@
 ---
+type: Architecture
 title: Bashkit Architecture
-summary: Core interpreter architecture, module boundaries, execution flow, and design principles.
+description: Core interpreter architecture, module boundaries, execution flow, and design principles.
+tags:
+  - bashkit
+  - architecture
+  - interpreter
 ---
 
 # Architecture

knowledge/browser-package.md

@@ -1,6 +1,12 @@
 ---
+type: Package Design
 title: Browser Package
-summary: Slim single-threaded WebAssembly package design for browsers and JavaScript runtimes.
+description: Slim single-threaded WebAssembly package design for browsers and JavaScript runtimes.
+tags:
+  - bashkit
+  - wasm
+  - packaging
+  - npm
 ---
 
 # WebAssembly Package (`@everruns/bashkit-wasm`)

knowledge/builtins.md

@@ -1,6 +1,10 @@
 ---
+type: Subsystem Design
 title: Builtin Commands
-summary: Builtin command trait, execution planning, registration, and implementation conventions.
+description: Builtin command trait, execution planning, registration, and implementation conventions.
+tags:
+  - bashkit
+  - builtins
 ---
 
 # Builtin Commands

knowledge/coreutils-args-port.md

@@ -1,6 +1,11 @@
 ---
+type: Subsystem Design
 title: Coreutils Argument Port
-summary: Code generation design for porting uutils clap arguments and uucore modules.
+description: Code generation design for porting uutils clap arguments and uucore modules.
+tags:
+  - bashkit
+  - builtins
+  - codegen
 ---
 
 # Coreutils argument-surface port

knowledge/credential-injection.md

@@ -1,6 +1,12 @@
 ---
+type: Subsystem Design
 title: Credential Injection
-summary: Per-host HTTP credential injection without exposing secret values to sandboxed scripts.
+description: Per-host HTTP credential injection without exposing secret values to sandboxed scripts.
+tags:
+  - bashkit
+  - security
+  - http
+  - secrets
 ---
 
 # Generic Credential Injection

knowledge/documentation.md

@@ -1,6 +1,10 @@
 ---
+type: Playbook
 title: Documentation Architecture
-summary: User documentation and Rustdoc guide organization, embedding, and maintenance.
+description: User documentation and Rustdoc guide organization, embedding, and maintenance.
+tags:
+  - bashkit
+  - documentation
 ---
 
 # Documentation Approach

knowledge/emscripten-wheels.md

@@ -1,6 +1,12 @@
 ---
+type: Package Design
 title: Emscripten Wheels
-summary: Reduced-feature Pyodide and Emscripten Python wheel design and build constraints.
+description: Reduced-feature Pyodide and Emscripten Python wheel design and build constraints.
+tags:
+  - bashkit
+  - python
+  - packaging
+  - wasm
 ---
 
 # Emscripten / Pyodide Wheels

knowledge/eval.md

@@ -1,6 +1,11 @@
 ---
+type: Subsystem Design
 title: Evaluation Framework
-summary: LLM evaluation study design, dataset format, execution, and scoring.
+description: LLM evaluation study design, dataset format, execution, and scoring.
+tags:
+  - bashkit
+  - eval
+  - llm
 ---
 
 # bashkit-eval: mira Eval Study

knowledge/git-support.md

@@ -1,6 +1,11 @@
 ---
+type: Subsystem Design
 title: Git Support
-summary: Sandboxed Git operations over the virtual filesystem.
+description: Sandboxed Git operations over the virtual filesystem.
+tags:
+  - bashkit
+  - git
+  - sandbox
 ---
 
 # Git Support

knowledge/http-transport.md

@@ -1,6 +1,12 @@
 ---
+type: Subsystem Design
 title: HTTP Transport
-summary: Pluggable host-controlled HTTP transport for curl and wget.
+description: Pluggable host-controlled HTTP transport for curl and wget.
+tags:
+  - bashkit
+  - http
+  - network
+  - embedding
 ---
 
 # Pluggable HTTP Transport

knowledge/index.md

@@ -1,39 +1,56 @@
 ---
-title: Bashkit Knowledge
-summary: Persistent, agent-maintained product and engineering knowledge for Bashkit.
-tags:
-  - bashkit
-  - engineering
-  - product
-  - security
-  - operations
+okf_version: "0.2"
 ---
 
 # Bashkit Knowledge
 
-This directory is Bashkit's canonical [Open Knowledge Format (OKF)](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) bundle and persistent project memory.
+* [Knowledge Maintenance Contract](knowledge-contract.md) - Rules for maintaining the Bashkit knowledge bundle and its OKF conformance.
+* [Update Log](log.md) - Chronological history of changes to this bundle.
 
-## Contents
+# Foundations
 
-The documents record architecture, behavior, constraints, security decisions, testing strategy, release procedures, and intentional limitations. Generated factual inventories live under [`status/`](status/).
+* [Bashkit Architecture](architecture.md) - Core interpreter architecture, module boundaries, execution flow, and design principles.
+* [Parser](parser.md) - Bash syntax parser and lexer architecture and compatibility decisions.
+* [Virtual Filesystem](vfs.md) - Filesystem abstraction, path safety, implementations, and sandbox invariants.
+* [Builtin Commands](builtins.md) - Builtin command trait, execution planning, registration, and implementation conventions.
+* [Parallel Execution](parallel-execution.md) - Threading model, shared ownership, and concurrency safety requirements.
 
-## Maintenance contract
+# Security
 
-- Treat this knowledge as part of the implementation, not as historical documentation.
-- Before changing behavior, read the relevant knowledge documents and follow their decisions or update them in the same change.
-- When code changes a documented behavior, design decision, invariant, limitation, threat, test strategy, operational process, or generated fact, update the affected knowledge in the same pull request.
-- Record important decisions that are not recoverable from code. Prefer links to source and tests over duplicating volatile implementation details.
-- Keep stable identifiers such as `TM-*` and `L-*`; never renumber them.
-- Add new durable project knowledge here. User-facing guides remain in `docs/`; embedded Rust guides remain in `crates/bashkit/docs/`.
-- Every knowledge subdirectory must contain an OKF `index.md` with `title` and `summary` frontmatter.
-- Run the relevant drift checks and tests after updating generated or machine-validated knowledge.
+* [Threat Model](threat-model.md) - Bashkit assets, trust boundaries, threats, mitigations, and stable threat identifiers.
+* [Security Testing](security-testing.md) - Fail-point injection and layered security regression testing strategy.
+* [Credential Injection](credential-injection.md) - Per-host HTTP credential injection without exposing secret values to sandboxed scripts.
+* [Request Signing](request-signing.md) - Transparent Ed25519 HTTP message signing according to RFC 9421.
+* [HTTP Transport](http-transport.md) - Pluggable host-controlled HTTP transport for curl and wget.
 
-## Knowledge map
+# Runtimes and packages
 
-| Area | Documents |
-|---|---|
-| Foundations | [Architecture](architecture.md), [parser](parser.md), [virtual filesystem](vfs.md), [builtins](builtins.md), [parallel execution](parallel-execution.md) |
-| Security | [Threat model](threat-model.md), [security testing](security-testing.md), [credential injection](credential-injection.md), [request signing](request-signing.md), [HTTP transport](http-transport.md) |
-| Runtimes and packages | [Python builtin](python-builtin.md), [TypeScript runtime](zapcode-runtime.md), [SQLite builtin](sqlite-builtin.md), [Python package](python-package.md), [Emscripten wheels](emscripten-wheels.md), [WebAssembly package](browser-package.md) |
-| Integrations | [Tool contract](tool-contract.md), [scripted orchestration](scripted-tool-orchestration.md), [Git](git-support.md), [SSH](ssh-support.md) |
-| Quality and operations | [Testing](testing.md), [limitations](limitations.md), [documentation](documentation.md), [maintenance](maintenance.md), [release process](release-process.md), [performance results](performance-results.md), [eval](eval.md) |
+* [Python Builtin](python-builtin.md) - Embedded Python execution through Monty with security and resource controls.
+* [ZapCode Runtime](zapcode-runtime.md) - Embedded TypeScript runtime, external functions, VFS bridging, and resource limits.
+* [SQLite Builtin](sqlite-builtin.md) - Embedded SQLite through Turso with memory and virtual filesystem backends.
+* [Coreutils Argument Port](coreutils-args-port.md) - Code generation design for porting uutils clap arguments and uucore modules.
+* [Python Package](python-package.md) - Python bindings, PyPI wheels, ABI strategy, and platform build matrix.
+* [Emscripten Wheels](emscripten-wheels.md) - Reduced-feature Pyodide and Emscripten Python wheel design and build constraints.
+* [Browser Package](browser-package.md) - Slim single-threaded WebAssembly package design for browsers and JavaScript runtimes.
+
+# Integrations
+
+* [Tool Contract](tool-contract.md) - Public LLM tool trait behavior, schemas, callbacks, and error semantics.
+* [Scripted Tool Orchestration](scripted-tool-orchestration.md) - Composition of tool definitions and callbacks into Bash-scripted orchestrators.
+* [Git Support](git-support.md) - Sandboxed Git operations over the virtual filesystem.
+* [SSH Support](ssh-support.md) - Sandboxed SSH, SCP, and SFTP operations and security boundaries.
+* [Interactive Shell](interactive-shell.md) - Interactive REPL design with rustyline-based line editing.
+
+# Quality and operations
+
+* [Testing Strategy](testing.md) - Test organization, patterns, fixtures, differential testing, and CI expectations.
+* [Known Limitations](limitations.md) - Intentional gaps, partial features, and Bash and POSIX compatibility stance.
+* [Documentation Architecture](documentation.md) - User documentation and Rustdoc guide organization, embedding, and maintenance.
+* [Maintenance](maintenance.md) - Pre-release dependency, security, compatibility, and artifact maintenance requirements.
+* [Release Process](release-process.md) - Versioning, validation, tagging, and publication to crates.io, PyPI, and npm.
+* [Performance Results](performance-results.md) - Benchmark harnesses, result locations, naming, and publication contract.
+* [Evaluation Framework](eval.md) - LLM evaluation study design, dataset format, execution, and scoring.
+
+# Subdirectories
+
+* [status/](status/) - Machine-generated inventories that capture the current Bashkit implementation state.

knowledge/interactive-shell.md

@@ -1,6 +1,11 @@
 ---
+type: Subsystem Design
 title: Interactive Shell
-summary: Interactive REPL design with rustyline-based line editing.
+description: Interactive REPL design with rustyline-based line editing.
+tags:
+  - bashkit
+  - cli
+  - repl
 ---
 
 # Interactive Shell Mode

knowledge/knowledge-contract.md

@@ -0,0 +1,94 @@
+---
+type: Playbook
+title: Knowledge Maintenance Contract
+description: Rules for maintaining the Bashkit knowledge bundle and its OKF conformance.
+tags:
+  - bashkit
+  - knowledge
+  - okf
+  - process
+---
+
+# Knowledge Maintenance Contract
+
+`knowledge/` is Bashkit's canonical [Open Knowledge Format (OKF) v0.2](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
+bundle and persistent project memory.
+
+## Maintenance rules
+
+- Treat this knowledge as part of the implementation, not as historical documentation.
+- Before changing behavior, read the relevant knowledge documents and follow their decisions or update them in the same change.
+- When code changes a documented behavior, design decision, invariant, limitation, threat, test strategy, operational process, or generated fact, update the affected knowledge in the same pull request.
+- Record important decisions that are not recoverable from code. Prefer links to source and tests over duplicating volatile implementation details.
+- Keep stable identifiers such as `TM-*` and `L-*`; never renumber them.
+- Add new durable project knowledge here. User-facing guides remain in `docs/`; embedded Rust guides remain in `crates/bashkit/docs/`.
+- Run the relevant drift checks and tests after updating generated or machine-validated knowledge.
+
+## OKF conformance rules
+
+The bundle targets OKF v0.2, declared as `okf_version: "0.2"` in the bundle-root [`index.md`](index.md).
+
+- Every `.md` file except the reserved `index.md` and `log.md` is a **concept document** and MUST start with a YAML frontmatter block containing a non-empty `type`.
+- `title`, `description`, and `tags` are recommended and used throughout this bundle; `description` is a single sentence that index entries reuse verbatim.
+- `index.md` files carry **no** frontmatter, except the bundle-root `index.md`, which may carry only `okf_version`.
+- `index.md` bodies are link lists grouped under headings: `* [Title](path) - description`.
+- `log.md` bodies are date-grouped entries (`## YYYY-MM-DD`), newest first.
+- Prose that is not a directory listing belongs in a concept document, not in an `index.md`.
+
+Type values are producer-defined. This bundle uses: `Architecture`, `Subsystem Design`,
+`Interface Contract`, `Package Design`, `Threat Model`, `Test Strategy`, `Limitations`,
+`Playbook`, `Generated Inventory`.
+
+## Enforcement
+
+`scripts/check_okf.py knowledge` validates the rules above. It runs in the CI lint job,
+via `just check-okf`, and from `scripts/tests/test_check_okf.py` (covered by `just check`).
+
+```console
+$ python3 scripts/check_okf.py knowledge
+knowledge: OKF v0.2 conformant (31 concepts, 2 index files, 1 log file)
+```
+
+## Third-party OKF linters (evaluated 2026-07-26)
+
+Four off-the-shelf implementations were built and run against this bundle and
+against a fixture per regression class. All four agree the bundle is conformant;
+they differ in how much they enforce.
+
+| Tool | Language / license | Distribution | Spec | Verdict |
+|---|---|---|---|---|
+| [`okf-lint`](https://github.com/rpmoore/okf-lint) | Rust, Apache-2.0 | crates.io `0.1.1` | v0.2 | **adopted** |
+| [`okftool`](https://github.com/ryansann/okftool) | Rust, Apache-2.0 | source / release binaries | v0.2 | not adopted |
+| [`okf`](https://crates.io/crates/okf) | Rust, Apache-2.0 | crates.io `0.1.0-alpha.1` | **v0.1** | not adopted |
+| [`okflint`](https://github.com/mattdav/okflint) | Python 3.12+, MIT | PyPI `0.3.1` | manifest-driven | not adopted |
+
+Regression coverage (fail = caught, pass = slipped through):
+
+| Regression | `okf` | `okftool` | `okf-lint` | `check_okf.py` |
+|---|---|---|---|---|
+| Concept missing `type` | fail | fail | fail | fail |
+| `summary` instead of `description` | pass | pass | pass | fail |
+| Frontmatter on `index.md` | pass | pass | fail | fail |
+| Concept absent from `index.md` | pass | pass | pass | fail |
+| `log.md` heading not `YYYY-MM-DD` | pass | pass | fail | fail |
+
+`okf-lint` is the strongest of the four: it is the only one that enforces the
+reserved `index.md`/`log.md` structures, it cites the spec section in every
+diagnostic, and it installs from crates.io with a pinned version. It runs in CI
+and in `just check-okf`, with `--max-line-length 10000` because knowledge docs
+wrap prose at author discretion.
+
+It does not subsume `check_okf.py`. The two rows it lets through — `summary`
+instead of `description`, and a concept missing from its `index.md` — are
+bundle-local conventions, and the first is exactly the defect the original
+migration shipped. Both checks therefore run together.
+
+The others were rejected on substance, not maturity: `okftool` treats everything
+but `type` as advisory (0 errors on all five regressions); `okf` implements OKF
+**v0.1**, so it validates this v0.2 bundle against the wrong revision; `okflint`
+validates against a hand-authored `okf-base.yaml` rather than the spec, so
+adopting it means maintaining the rule set anyway, and it requires Python 3.12+
+against this repository's 3.9 floor.
+
+`okftool lint` and `okf graph` remain useful ad hoc for advisory graph checks —
+both report that most concepts here have no cross-links to each other.