chore(knowledge): migrate specs to OKF

.agents/skills/process-issues/SKILL.md

@@ -43,8 +43,8 @@ For each qualifying issue (ordered by issue number), achieve ALL of these before
 
 - Minimal, focused changes
 - Positive and negative tests pass
-- Security tests added if change touches parser, interpreter, VFS, network, git, or user input (per `specs/security-testing.md`)
-- Threat model updated if new attack surface (per `specs/threat-model.md`)
+- Security tests added if change touches parser, interpreter, VFS, network, git, or user input (per `knowledge/security-testing.md`)
+- Threat model updated if new attack surface (per `knowledge/threat-model.md`)
 
 ### 4. Ship via `/ship`
 

.agents/skills/ship/SKILL.md

@@ -33,7 +33,7 @@ Review the changes on this branch (use `git diff origin/main...HEAD` and `git lo
 3. **Write missing tests** for any uncovered code paths:
    - **Positive tests**: happy path, valid inputs, expected state transitions
    - **Negative tests**: invalid inputs, error conditions, boundary cases, permission failures, missing resources
-   - **Security tests**: if change touches parser, interpreter, VFS, network, git, or user input — add tests per `specs/security-testing.md`
+   - **Security tests**: if change touches parser, interpreter, VFS, network, git, or user input — add tests per `knowledge/security-testing.md`
    - **Compatibility tests**: if change affects Bash behavior parity — add differential tests comparing against real Bash
 4. **Run all tests** to confirm green: `just test`
 5. If any test fails, fix the code or test until green
@@ -42,10 +42,10 @@ Review the changes on this branch (use `git diff origin/main...HEAD` and `git lo
 
 Review the changes and update project artifacts where applicable. Skip items that aren't affected.
 
-1. **Specs** (`specs/`): if the change adds/modifies behavior covered by a spec, update the relevant spec file to stay in sync
-2. **Threat model** (`specs/threat-model.md`): if the change introduces new attack surfaces, external inputs, authentication/authorization changes, or data handling — add or update threat entries using the `TM-<CATEGORY>-<NNN>` format and add `// THREAT[TM-XXX-NNN]` code comments at mitigation points
-3. **AGENTS.md**: if the change adds new specs, commands, or modifies development workflows — update the relevant section
-4. **Limitations** (`specs/limitations.md`): if a limitation was added or lifted, update the table; if builtins changed, run `just regen-builtins` and commit the JSON
+1. **Knowledge** (`knowledge/`): if the change affects durable behavior, decisions, constraints, threats, tests, or operations, update the relevant OKF knowledge in the same change
+2. **Threat model** (`knowledge/threat-model.md`): if the change introduces new attack surfaces, external inputs, authentication/authorization changes, or data handling — add or update threat entries using the `TM-<CATEGORY>-<NNN>` format and add `// THREAT[TM-XXX-NNN]` code comments at mitigation points
+3. **AGENTS.md**: if the change adds new knowledge, commands, or modifies development workflows — update the relevant section
+4. **Limitations** (`knowledge/limitations.md`): if a limitation was added or lifted, update the table; if builtins changed, run `just regen-builtins` and commit the JSON
 5. **Documentation** (`crates/bashkit/docs/`): if the change affects public APIs, tools, or features — update the relevant guide markdown files
 
 ### Phase 3b: Code Simplification
@@ -66,12 +66,12 @@ Analyze all changed code for security vulnerabilities:
 
 1. **Input validation** — check that user-supplied data (script input, file paths, environment variables, command arguments) is validated before use
 2. **Injection risks** — look for command injection, path traversal, environment variable injection, or shell metacharacter issues
-3. **Sandbox escapes** — if changes touch VFS, builtins, or process execution, verify they cannot escape the sandbox (see `specs/threat-model.md`)
+3. **Sandbox escapes** — if changes touch VFS, builtins, or process execution, verify they cannot escape the sandbox (see `knowledge/threat-model.md`)
 4. **Resource exhaustion** — check for unbounded loops, unbounded allocations, or missing limits on user-controlled sizes
 5. **Error handling** — ensure errors don't leak internal state, file paths, or sensitive information
 6. **Unsafe code** — review any `unsafe` blocks for soundness; prefer safe alternatives
 
-If security issues are found, fix them, add regression tests, and update `specs/threat-model.md` if a new threat category is identified.
+If security issues are found, fix them, add regression tests, and update `knowledge/threat-model.md` if a new threat category is identified.
 
 ### Phase 3d: Design Quality Review
 

.claude/commands/maintain.md

@@ -1,4 +1,4 @@
-Run the pre-release maintenance checklist from `specs/maintenance.md`. Find and fix all issues before reporting.
+Run the pre-release maintenance checklist from `knowledge/maintenance.md`. Find and fix all issues before reporting.
 
 ## Arguments
 
@@ -28,7 +28,7 @@ Key tools: `cargo update`, `cargo outdated`, `cargo audit`, `cargo deny check`,
 
 Ensure the threat model covers all features, security tests exist for all mitigated threats, and no OWASP-style issues exist in the codebase.
 
-Key references: `specs/threat-model.md`, `specs/security-testing.md`, `crates/bashkit/docs/threat-model.md`
+Key references: `knowledge/threat-model.md`, `knowledge/security-testing.md`, `crates/bashkit/docs/threat-model.md`
 
 ### 3. Tests are comprehensive and green
 
@@ -94,7 +94,7 @@ Key tools:
 - `gh run list --workflow=fuzz.yml --limit 7` (fuzz)
 - `gh api repos/OWNER/REPO/actions/runs/RUN_ID/jobs` (inspect failed jobs)
 
-If failures persist >2 days, escalate per `specs/maintenance.md`.
+If failures persist >2 days, escalate per `knowledge/maintenance.md`.
 If the agent cannot fix a failure, it MUST open a GitHub issue and report the
 pass as blocked — never silently skip.
 
@@ -108,6 +108,6 @@ pass as blocked — never silently skip.
 
 ## Notes
 
-- This is a goal-based checklist. The spec (`specs/maintenance.md`) defines *what* must be true. This skill defines *how* to verify and fix.
+- This is a goal-based checklist. The spec (`knowledge/maintenance.md`) defines *what* must be true. This skill defines *how* to verify and fix.
 - Use parallel agents for independent sections when possible.
 - For scoped runs, still verify that fixes don't break other areas (`just test` at minimum).

.deepsec/data/bashkit/INFO.md

@@ -54,7 +54,7 @@ shown directly to LLMs or users.
 - Tests and fuzz targets intentionally contain hostile scripts, fake secrets,
   host canaries, traversal strings, malformed archives, and allowlist bypass
   attempts.
-- `specs/` and `crates/bashkit/docs/` describe vulnerabilities and mitigations;
+- `knowledge/` and `crates/bashkit/docs/` describe vulnerabilities and mitigations;
   treat them as design docs unless the same pattern appears in executable code.
 - Optional features named `realfs`, `http_client`, `ssh`, `git`, `python`,
   `typescript`, `sqlite`, and `bot-auth` are intended capability gates, not

.github/workflows/apidocs-drift.yml

@@ -5,7 +5,7 @@ name: API Reference Drift
 # site/src/content/apidocs/*.md and feeds the /api/{python,typescript} pages;
 # the node-only site build just renders it, so it must be regenerated and
 # committed on release — fix drift by running `just apidocs` and committing.
-# See specs/documentation.md ("API reference hosting").
+# See knowledge/documentation.md ("API reference hosting").
 #
 # Per AGENTS.md commit-attribution rules this workflow never auto-commits; it
 # only fails so a human regenerates and commits under a real identity.

.github/workflows/builtins-drift.yml

@@ -1,6 +1,6 @@
 name: Builtins Inventory Drift
 
-# Fails when specs/status/builtins.json no longer matches what the code
+# Fails when knowledge/status/builtins.json no longer matches what the code
 # registers (see `Bash::builtin_names`). The JSON is generated by
 # `just regen-builtins` and is the data source for the site's builtins
 # page and homepage counts — fix drift by regenerating and committing.
@@ -15,7 +15,7 @@ on:
       - 'crates/bashkit/src/builtins/**'
       - 'crates/bashkit/src/lib.rs'
       - 'crates/bashkit/examples/dump_builtins.rs'
-      - 'specs/status/builtins.json'
+      - 'knowledge/status/builtins.json'
       - '.github/workflows/builtins-drift.yml'
   schedule:
     # Weekly Mondays 05:30 UTC, after the coreutils drift run.
@@ -49,11 +49,11 @@ jobs:
         run: |
           cargo run -q --example dump_builtins \
             --features jq,git,ssh,http_client,python,typescript,sqlite \
-            > specs/status/builtins.json
+            > knowledge/status/builtins.json
 
       - name: Fail on drift
         run: |
-          if ! git diff --exit-code -- specs/status/builtins.json; then
-            echo "::error::specs/status/builtins.json is stale — run 'just regen-builtins' and commit the result"
+          if ! git diff --exit-code -- knowledge/status/builtins.json; then
+            echo "::error::knowledge/status/builtins.json is stale — run 'just regen-builtins' and commit the result"
             exit 1
           fi

.github/workflows/ci.yml

@@ -72,7 +72,7 @@ jobs:
     # Build the browser package (@everruns/bashkit-wasm) and run its headless
     # integration tests, proving the single-threaded bundle loads with no
     # COOP/COEP headers and that sync + async execution both work. See
-    # specs/browser-package.md. Keep wasm-bindgen-cli in lockstep with the
+    # knowledge/browser-package.md. Keep wasm-bindgen-cli in lockstep with the
     # wasm-bindgen version in Cargo.lock.
     name: WASM web package
     runs-on: ubuntu-latest

.github/workflows/coreutils-args-drift.yml

@@ -2,7 +2,7 @@ name: Coreutils Args Drift
 
 # Detects upstream uutils/coreutils argument-surface AND vendored-module
 # drift, and proposes both as a single PR. See
-# specs/coreutils-args-port.md for the design (args mode + module mode).
+# knowledge/coreutils-args-port.md for the design (args mode + module mode).
 #
 # Module set is read from `crates/bashkit-coreutils-port/vendored.toml`;
 # adding a vendored module is one TOML stanza there and the drift run
@@ -324,7 +324,7 @@ jobs:
           correctly per \`AGENTS.md\`. Intermediate bot commits in this PR
           are discarded by squash.
 
-          Design: [\`specs/coreutils-args-port.md\`](../tree/main/specs/coreutils-args-port.md).
+          Design: [\`knowledge/coreutils-args-port.md\`](../tree/main/knowledge/coreutils-args-port.md).
           EOF
 
           if gh pr view "$branch" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then

.github/workflows/publish-python.yml

@@ -21,7 +21,7 @@ env:
   CARGO_TERM_COLOR: always
   # abi3 (stable ABI): one interpreter builds a single cp39-abi3 wheel per
   # platform that runs on Python 3.9+. No per-minor-version matrix. See
-  # specs/python-package.md § abi3.
+  # knowledge/python-package.md § abi3.
   BUILD_PYTHON: "3.12"
 
 jobs:
@@ -119,22 +119,22 @@ jobs:
   # Reduced-feature Pyodide/Emscripten wheel (browser / JupyterLite).
   # Separate job: distinct toolchain (nightly Rust + emsdk + pyodide-build) and a
   # single Python version dictated by the pyodide-build ABI lockstep.
-  # See specs/emscripten-wheels.md.
+  # See knowledge/emscripten-wheels.md.
   build-emscripten:
     name: Build wheel - emscripten (Pyodide)
     runs-on: ubuntu-latest
     env:
       # Keep in lockstep with the `wasm` job in python.yml: the nightly's LLVM,
       # pyodide-build's Emscripten/binaryen, and Pyodide's EH ABI must agree.
-      # See specs/emscripten-wheels.md "version triangle". Bump together.
+      # See knowledge/emscripten-wheels.md "version triangle". Bump together.
       RUST_NIGHTLY: "nightly-2026-05-29"
       PYODIDE_BUILD_VERSION: "0.34.4"
     steps:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       # Python 3.13 -> pyodide-build's modern config (Pyodide 0.29.x, Emscripten
       # 4.0.9), whose binaryen understands modern LLVM's wasm target-features and
-      # whose runtime supports wasm exception handling. See specs/emscripten-wheels.md.
+      # whose runtime supports wasm exception handling. See knowledge/emscripten-wheels.md.
       - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: "3.13"

.github/workflows/python.yml

@@ -193,14 +193,14 @@ jobs:
           retention-days: 5
 
   # Build the reduced-feature Pyodide/Emscripten wheel and smoke-test it in a
-  # Pyodide venv. See specs/emscripten-wheels.md for the feature matrix and the
+  # Pyodide venv. See knowledge/emscripten-wheels.md for the feature matrix and the
   # pyodide-build <-> Emscripten <-> Python <-> Rust version lockstep.
   wasm:
     name: Build wheel (Pyodide/Emscripten)
     runs-on: ubuntu-latest
     env:
       # Pinned for reproducibility: this trio must stay aligned on the wasm
-      # feature set + exception-handling ABI (see specs/emscripten-wheels.md
+      # feature set + exception-handling ABI (see knowledge/emscripten-wheels.md
       # "version triangle"). pyodide-build 0.34.x (under Python 3.13) selects
       # Pyodide 0.29.x / Emscripten 4.0.9; the nightly's LLVM must match that
       # binaryen. Bump all three together and re-verify the wheel imports.
@@ -220,7 +220,7 @@ jobs:
       # must satisfy our deps' MSRV (monty needs rustc 1.95) and edition 2024,
       # so it has to be recent; its LLVM (19+) matches Emscripten 4.0.9's
       # binaryen, which is what avoids the wasm-opt target-feature skew that
-      # older Emscripten (3.1.x) hit. See specs/emscripten-wheels.md.
+      # older Emscripten (3.1.x) hit. See knowledge/emscripten-wheels.md.
       - name: Install nightly Rust with the Emscripten target
         # @nightly matches the repo's other nightly jobs (fuzz.yml, nightly.yml,
         # ci.yml); the exact nightly is pinned via the toolchain: input below.

AGENTS.md

@@ -17,11 +17,11 @@ Fix root cause. Unsure: read more code; if stuck, ask w/ short options. Unrecogn
 - No backward compat needed (internal code)
 - Write failing test before fixing bug
 
-### Specs
+### Knowledge
 
-`specs/` contains feature specifications. New code should comply with these or propose changes.
+`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.
 
-| Spec | Description |
+| Knowledge | Description |
 |------|-------------|
 | architecture | Core interpreter architecture, module structure |
 | parser | Bash syntax parser design |
@@ -57,14 +57,14 @@ Fix root cause. Unsure: read more code; if stuck, ask w/ short options. Unrecogn
 
 - **Public docs** live in `docs/` — user-facing articles (security, guides, etc.)
 - **Rustdoc guides** live in `crates/bashkit/docs/` as markdown files
-- Rustdoc guides embedded via `include_str!` (see `specs/documentation.md`)
+- Rustdoc guides embedded via `include_str!` (see `knowledge/documentation.md`)
 - Edit `crates/bashkit/docs/*.md`, not the doc modules in `lib.rs`
 - Add "See also" cross-links when creating new guides
 - Run `cargo doc --open` to preview rustdoc changes
 
 ### Bashkit Principles
 
-- All design decisions in `specs/` - no undocumented choices
+- All design decisions in `knowledge/` - no undocumented choices
 - Everything runnable and testable - no theoretical code
 - Don't stop until e2e works - verify before declaring done
 - Examples tested in CI - must pass
@@ -130,7 +130,7 @@ and are aggregated by `crates/bashkit/tests/integration/main.rs` into a single b
 New behavioral tests go there. A small number of files stay as top-level
 `tests/*.rs` because they need their own binary (process-global env
 mutation, `--test-threads=1`, ssh-only feature isolation) — the list and
-criteria live in `specs/testing.md`.
+criteria live in `knowledge/testing.md`.
 
 ### Rust
 
@@ -142,7 +142,7 @@ criteria live in `specs/testing.md`.
 
 ### Stderr from builtins must not leak internal Debug shapes
 
-**TM-INF-022** in `specs/threat-model.md`. No `{:?}`/`{:#?}` in
+**TM-INF-022** in `knowledge/threat-model.md`. No `{:?}`/`{:#?}` in
 `crates/bashkit/src/builtins/`; use `Display` or a domain formatter
 (reference: `format_compile_errors` in `builtins/jq/errors.rs`); cap
 diagnostics ≤ 1 KB; test-only Debug needs `// debug-ok: <reason>`.
@@ -184,14 +184,14 @@ Do not mix criterion `.md` files into `crates/bashkit-bench/results/`.
 3. `cargo clippy --all-targets --all-features -- -D warnings`
 4. `just test` (feature-sliced; never `cargo test --all-features` in one invocation — see Local Dev)
 5. Unit tests cover both positive (expected behavior) and negative (error handling, edge cases) scenarios
-6. Security tests if change touches user input, parsing, sandboxing, or permissions (see `specs/security-testing.md`)
+6. Security tests if change touches user input, parsing, sandboxing, or permissions (see `knowledge/security-testing.md`)
 7. Compatibility/differential tests if change affects Bash behavior parity (compare against real Bash)
 8. Rebase on main: `git fetch origin main && git rebase origin/main` (for worktrees: verify the worktree `HEAD` is on latest `origin/main` before editing)
-9. Update specs if behavior changes
+9. Update knowledge if behavior or durable project facts change
 10. CI green before merge
 11. Resolve all PR comments
-12. `cargo bench --bench parallel_execution` if touching Arc/async/Interpreter/builtins (see `specs/parallel-execution.md`)
-13. `just bench-sqlite` if touching the sqlite builtin or its VFS/IO bridge (see `specs/sqlite-builtin.md`)
+12. `cargo bench --bench parallel_execution` if touching Arc/async/Interpreter/builtins (see `knowledge/parallel-execution.md`)
+13. `just bench-sqlite` if touching the sqlite builtin or its VFS/IO bridge (see `knowledge/sqlite-builtin.md`)
 14. `just bench` if changes might impact performance (interpreter, builtins, tools)
 15. `ruff check crates/bashkit-python && ruff format --check crates/bashkit-python` if touching Python code
 
@@ -206,7 +206,7 @@ Do not mix criterion `.md` files into `crates/bashkit-bench/results/`.
 
 Types: feat, fix, docs, refactor, test, chore
 
-- Updates to `specs/` and `AGENTS.md`: use `chore` type
+- Updates to `knowledge/` and `AGENTS.md`: use `chore` type
 - NEVER add links to Claude sessions in PR body or commits
 
 ### Commit Attribution

CHANGELOG.md

@@ -113,7 +113,7 @@
   addresses, and the response size cap, and returns typed errors
   (`Denied`/`Timeout`/`TooLarge`/`Transport`) that map onto curl exit codes
   (7/28/63/1). Mirrors fetchkit's transport injection so one host egress
-  implementation can back both libraries. See `specs/http-transport.md`
+  implementation can back both libraries. See `knowledge/http-transport.md`
   ([#2147](https://github.com/everruns/bashkit/pull/2147)).
 - **`xargs -P` parallel execution** — `-P/--max-procs` runs command batches
   concurrently, with `--process-slot-var` exposing the slot index to each child

CONTRIBUTING.md

@@ -63,11 +63,11 @@ test: add array edge case tests
 
 ## Adding Features
 
-1. Check if the feature is documented in `specs/`
+1. Check if the feature is documented in `knowledge/`
 2. Add spec tests in `crates/bashkit/tests/spec_cases/`
 3. Implement the feature
 4. Update `crates/bashkit/docs/compatibility.md` if applicable
-5. Update `specs/limitations.md` if removing a limitation
+5. Update `knowledge/limitations.md` if removing a limitation
 
 ## Spec Test Format
 
@@ -93,12 +93,12 @@ expected
 
 - [ ] `just pre-pr` passes
 - [ ] Rebased on main
-- [ ] Specs updated if behavior changes
+- [ ] Knowledge updated if behavior changes
 - [ ] CI green
 
 ## Architecture
 
-See `specs/` for design documents:
+See `knowledge/` for persistent design and engineering knowledge:
 
 - `architecture.md` - Overall design
 - `parser.md` - Parser/lexer details