chore(knowledge): migrate specs to OKF#2202
Merged
Merged
Conversation
Co-Authored-By: yolop <yolop@everruns.com>
Deploying with
|
| Status | Name | Latest Commit | Preview URL | Updated (UTC) |
|---|---|---|---|---|
| ✅ Deployment successful! View logs |
bashkit | fb5f417 | Commit Preview URL Branch Preview URL |
Jul 25 2026, 05:11 AM |
Co-Authored-By: yolop <yolop@everruns.com>
2 tasks
chaliy
added a commit
that referenced
this pull request
Jul 26, 2026
…ant (#2206) ## What changed The `specs/` → `knowledge/` migration (#2202) adopted OKF in name only. This makes the bundle conform to [OKF v0.2](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) and adds a gate so it stays that way. Four spec violations, every one of which made the bundle non-conformant: | Violation | Spec | Fix | |---|---|---| | No `type` on any concept — the **only** always-required key, so *zero* documents conformed | §4.1, §11 | `type` on all 31 concepts | | `summary:` — not an OKF field | §4.1 | renamed to `description:` | | Both `index.md` files carried `title`/`summary`/`tags` frontmatter | §8 — index files carry no frontmatter; root may carry only `okf_version` | stripped; root declares `okf_version: "0.2"` | | Index bodies were prose + a table, not directory listings | §8 — `* [Title](url) - description` sections | reshaped | Alongside that: - Maintenance rules moved out of `index.md` (prose does not belong in a reserved index) into `knowledge/knowledge-contract.md`, which also records the OKF rules and the type vocabulary. `AGENTS.md` points there. - `knowledge/status/builtins.json` was an unreferenced blob; it is now described by a `Generated Inventory` concept with `resource:` pointing at it. - Added `knowledge/log.md` (§9 date-grouped history). Enforcement is two checks that cover different things: - **`okf-lint` 0.1.1** (crates.io, pinned) — upstream spec gate. It enforces the reserved `index.md`/`log.md` structures and cites the spec section in every diagnostic. - **`scripts/check_okf.py`** — no dependencies, covers the bundle-local conventions okf-lint does not: `description` (not `summary`), and every concept listed in its directory's `index.md`. Both run in the CI lint job and in `just check-okf` (wired into `just check`). ## Why An OKF bundle that no OKF consumer would accept is worse than not claiming the format: agents and tooling route on `type`, and every document was missing it. Nothing validated the bundle, so the defects shipped silently. ## Before / After Conformance, checked with the upstream linter: ```console # before $ okf-lint knowledge --max-line-length 10000 index.md:1: root index.md frontmatter may only contain 'okf_version' (spec: …#6-index-files) architecture.md:1: frontmatter missing required non-empty 'type' field (spec: …#4.1-frontmatter) … 31 concepts, all missing 'type' exit=1 # after $ just check-okf knowledge: OKF v0.2 conformant (31 concepts, 2 index files, 1 log file) okf-lint 0.1.1: knowledge conforms to OKF v0.2 exit=0 ``` Four OKF implementations were built and run against the bundle and against a fixture per regression class, to pick the gate. `fail` = regression 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 available and is adopted. It does not subsume the local check: the two rows it lets through are bundle-local conventions, and the first is exactly the defect #2202 shipped. The rejected alternatives are recorded with rationale in `knowledge/knowledge-contract.md` — `okftool` treats everything but `type` as advisory, `okf` implements OKF **v0.1** (wrong revision for this bundle), and `okflint` validates against a hand-authored manifest rather than the spec and needs Python 3.12+ against this repo's 3.9 floor. No runtime behavior changes: no `.rs` files are touched. `just pre-pr` green, including `cargo vet`. ## Risk - **Low** - Documentation and CI only — no library, CLI, or binding code changes. - New CI dependency: `cargo install okf-lint --version 0.1.1 --locked` in the lint job. It is a lint tool, not a workspace dependency, so `deny.toml`/`cargo vet` are unaffected. Failure mode is a red lint job; removing the two lines reverts it. The version is pinned in both `ci.yml` and the `justfile` and must be bumped together. - `--max-line-length 10000` effectively disables okf-lint's line-length rule; knowledge docs wrap prose at author discretion, and the rule otherwise fires 183 times. ## Checklist - [x] Tests added or updated — `scripts/tests/test_check_okf.py`, one case per rejection class plus a positive control, as `unittest.TestCase` so `unittest discover` actually executes them - [x] Backward compatibility considered — internal knowledge/tooling only; no public surface --- _Generated by [Claude Code](https://claude.ai/code/session_01VydQA3PQfm442uwHSTrZnN)_
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
specs/corpus to an Open Knowledge Format bundle underknowledge/Why
Bashkit needs one persistent, agent-maintained knowledge base that captures architecture, behavior, constraints, threats, tests, and operational decisions while preserving the automatic-update properties of the former specifications.
How
titleandsummaryfrontmatter to each knowledge documentknowledge/index.mdthe canonical map and maintenance contractknowledge/status/collectionBefore / After
Before: durable engineering memory lived in
specs/without an OKF bundle index or explicit knowledge-maintenance contract.After:
knowledge/is a valid indexed OKF bundle, and agent/contributor workflows require synchronized updates when implementation facts change.Testing
just pre-prProduced by yolop