feat!: migrate ADRs to the Open Knowledge Format - #9
Conversation
Store ADRs as an OKF v0.1 knowledge bundle instead of arkouda's bespoke frontmatter schema, so any OKF-aware consumer can read them without special-casing arkouda. Frontmatter adopts OKF's vocabulary: a new required `type: Architecture Decision Record`, `abstract` -> `description`, and `date` -> `timestamp` (ISO 8601 date or datetime). `status`, `deciders`, and `superseded_by` are retained as OKF producer extensions. The `id` key is removed: OKF defines a concept's id as its path within the bundle minus the `.md` suffix, which the validator already enforced via "filename stem must match id". Discovery now recurses into subdirectories, and `index.md` / `log.md` are reserved by OKF section 3.1 and never treated as ADRs. Adds `arkouda index`, which generates the bundle-root `index.md` listing every concept under its status heading for progressive disclosure. It declares `okf_version: "0.1"`, the one place OKF permits frontmatter in an index. `arkouda new` refreshes an existing index but never creates one, since OKF makes indexes optional. Validation stacks OKF conformance under arkouda's ADR contract. OKF's permissive-consumption rule decides what is a warning rather than an error: an unimplemented declared OKF version (E013) and a stale `index.md` (E014) are reported but never fail the run. BREAKING CHANGE: the ADR frontmatter schema, `arkouda new --abstract` (now `--description`), and `arkouda list --sort date` (now `--sort timestamp`) all change. No compatibility shim is provided; `arkouda check` fails on the old schema, which is how you find the files to migrate.
|
Warning Review limit reached
Next review available in: 21 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (8)
📝 WalkthroughWalkthroughMigrates ADRs to OKF v0.1 knowledge bundles, adding recursive concept discovery, revised metadata and validation, generated indexes, updated CLI commands, refreshed examples, and corresponding documentation. ChangesOKF knowledge bundle migration
Estimated code review effort: 4 (Complex) | ~60 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@README.md`:
- Line 101: Update the fenced code block containing the bundle layout tree
diagram in the README to specify the text language, changing its opening fence
to ```text while preserving the diagram contents.
In `@skills/use-arkouda/SKILL.md`:
- Line 59: Update the `arkouda list -l` documentation to include the
`DESCRIPTION` column after `TITLE`, matching the actual `TITLE — DESCRIPTION`
output format.
- Line 202: The documentation incorrectly prohibits editing log.md; update the
guidance so only index.md is protected from manual edits, while clarifying that
log.md may be maintained by users but remains reserved from concept discovery
and subject to date-heading validation.
- Line 53: Update the ID terminology in the relevant SKILL.md references,
including the lines around the ADR filename guidance and the additional
occurrences, to describe IDs as bundle-relative paths without the .md suffix
rather than filename stems; retain examples such as security/mtls and ensure
superseded_by values and links use the full relative path.
In `@src/commands/new.rs`:
- Around line 50-73: Make index refresh best-effort after the ADR is created:
update the call to refresh_index in the creation flow to catch failures, emit a
clear warning unless quiet mode is enabled, and still return the successful exit
code. Keep refresh_index unchanged for successful updates, and reference its
existing Result error when reporting the warning.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 51f86e82-0d78-47b0-80f5-de4aabfd2259
📒 Files selected for processing (26)
.arkoudarc.tomlCHANGELOG.mdREADME.mddocs/adr/adopt-okf.mddocs/adr/basic-adr-cli.mddocs/adr/defer-to-unix-tools.mddocs/adr/index.mddocs/adr/ls-style-list-and-decision.mddocs/adr/telemetry-for-agent-command-invocations.mdskills/use-arkouda/SKILL.mdsrc/adr/discovery.rssrc/adr/frontmatter.rssrc/adr/index.rssrc/adr/manifest.rssrc/adr/mod.rssrc/adr/validator.rssrc/cli.rssrc/commands/check.rssrc/commands/decision.rssrc/commands/index.rssrc/commands/list.rssrc/commands/mod.rssrc/commands/new.rssrc/error.rssrc/main.rssrc/telemetry.rs
Refreshing a bundle's `index.md` re-parses every concept in it, so an unrelated malformed ADR made `arkouda new` exit 1 after it had already written the new file and printed success. A script checking the exit code would treat a completed creation as a failure. The refresh is now best-effort: it warns on stderr and the command exits 0. A stale index is only ever a warning (E014), and `arkouda check` reports it. Also correct the docs CodeRabbit flagged: - A concept id is the bundle-relative path without `.md`, not the filename stem — `security/mtls.md` has the id `security/mtls`, so `superseded_by` values and links must carry the full path. - `arkouda list -l` prints `TITLE — DESCRIPTION`; the documented column list stopped at `TITLE`. - `log.md` is hand-maintained: arkouda never generates it, only validates its date headings. Only `index.md` must not be edited by hand. - Tag the README bundle-layout code fence as `text` (markdownlint MD040).
|
Addressed all five CodeRabbit comments in 7007b25.
|
|
@coderabbitai full review |
✅ Action performedFull review finished. Your plan includes PR reviews subject to rate limits. More reviews will be available in 24 minutes. |
Add a verbatim copy of the Open Knowledge Format specification arkouda implements, so the exact text it was built against is pinned in-tree, readable offline, and diffable when upstream moves. `docs/okf/SPEC.md` and `docs/okf/LICENSE.md` are byte-for-byte copies of upstream `okf/SPEC.md` and `okf/LICENSE.md` at commit ee67a5ca. Neither is modified. The spec is Apache 2.0, so its licence travels with it; upstream ships no NOTICE file, and the spec carries no copyright header of its own. `docs/okf/README.md` is arkouda's own provenance note — upstream commit, retrieval date, SHA-256 checksums, a verified refresh procedure, and a map from the spec's sections to the code that implements them. It is flagged as not-upstream, since upstream has a different `okf/README.md` that is deliberately not vendored. `docs/okf/` is outside the `dirs` in `.arkoudarc.toml`, so `arkouda check` does not treat the vendored Markdown as ADR concepts.
1 participant
Description
Migrates arkouda from its bespoke ADR frontmatter schema to the Open Knowledge Format (OKF) v0.1. An ADR directory becomes an OKF knowledge bundle; each ADR becomes a concept.
No backward compatibility is provided, as agreed.
arkouda checkfails loudly on the old schema — that's the intended way to find files to migrate.Motivation
Arkouda's pitch is that ADRs should be machine-readable for AI agents. A schema only one tool can read is machine-readable in the weakest possible sense: an OKF-aware agent looks for
type, finds nothing, and has to special-case arkouda.OKF specifies almost exactly what arkouda already invented — a directory of Markdown files with YAML frontmatter, readable without tooling, diffable in git. Adopting it costs one constant field and buys interoperability. Arkouda is pre-1.0 and the old schema has no external consumers, so this is the cheapest moment to move.
The
idkey was already redundant: OKF defines a concept's id as its path within the bundle minus.md, and the validator'sE005existed only to police the fact thatidduplicated the filename.Rationale recorded in
docs/adr/adopt-okf.md, using arkouda itself.Changes
Frontmatter (BREAKING)
typeArchitecture Decision Record.id.md.abstractdescriptiondatetimestampstatus,deciders,superseded_byCLI (BREAKING)
arkouda new --abstract→--descriptionarkouda list --sort date→--sort timestamp; the-ltable's third column is now the timestamp.Structure
security/mtls.mdis the conceptsecurity/mtls.index.mdandlog.mdare reserved (OKF §3.1) and are never treated as ADRs.New:
arkouda indexGenerates the bundle-root
index.md(OKF §6) — every concept grouped under its status heading with its one-line description, so an agent can read one file instead of opening five. It declaresokf_version: "0.1", the one place OKF §11 permits frontmatter in an index.arkouda newrefreshes an existing index but never creates one, since OKF §9 makes indexes optional.Validation
OKF conformance (§9) is the floor; arkouda's ADR contract stacks on top. OKF's permissive-consumption rule decides what is a warning rather than an error — neither of the new warnings fails CI:
E005now flags atypethat isn'tArchitecture Decision Record(replacing the "stem must match id" check that removingidmade vacuous).E011— anindex.mdcarries frontmatter where OKF doesn't permit it.E012— alog.mdheading isn't an ISO 8601YYYY-MM-DDdate.E013(warning) — the bundle declares an OKF version arkouda doesn't implement.E014(warning) —index.mdis stale; runarkouda index.Also
E010) now validates all configured bundles as one collection. Within a single bundle a concept id is its path, so it can never collide — a duplicate is only ever a cross-bundle problem. Covered by a new regression test.arkouda indexrefuses to run against a single-file--dirrather than truncating the index to the one concept it loaded.[E001]: messageinstead of[E001] : message, and[E012] 3: messagewhen a line number is present.adopt-okfsupersedes the frontmatter schema they describe.Verification
Beyond
cargo test --all(61 tests, up from 56), I drove the CLI end-to-end against scratch bundles to observe each behaviour:E001×3, exit 1newon a bundle with no index → no index creatednewon a bundle with an index → index refreshedsecurity/mtls.md→ discovered, indexed with a bundle-relative link, resolvable bydecision security/mtlsanddecision mtlsokf_version→ warnings, exit 0index.mdwith frontmatter →E011; non-ISOlog.mdheading →E012index.md/log.mdnever appear inarkouda listuse-postgres→E010on both, exit 1Checklist
arkouda checkpassescargo test --all)skills/use-arkouda/SKILL.md,CHANGELOG.md,.arkoudarc.toml)Summary by CodeRabbit
New Features
arkouda index.arkouda self completions.Changed
type,description, andtimestamp.--abstractto--descriptionand--sort dateto--sort timestamp.