Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

Drop index.md prose that strict OKF v0.2 validators reject

Maxsuel Einstein69f4ab4c8526
diff --git a/CHANGELOG.md b/CHANGELOG.md
index c376849a..8114bfd5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -162,6 +162,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
local example listed the page in the target's backlinks, while the web
page rendered neither as a link. A link whose label is code
(`` [`foo`](foo.md) ``) is still indexed. (#968)
+- `export-okf`'s generated `index.md` no longer has a prose sentence outside
+ its list structure. Some strict OKF v0.2 validators read §11.3 as
+ rejecting it. (#960)
## [2.4.1] - 2026-09-25
diff --git a/crates/ai-memory-mcp/src/admin.rs b/crates/ai-memory-mcp/src/admin.rs
index 2051632a..0251b6d5 100644
--- a/crates/ai-memory-mcp/src/admin.rs
+++ b/crates/ai-memory-mcp/src/admin.rs
@@ -982,15 +982,16 @@ async fn build_okf_bundle_file(
let mut tar = tar::Builder::new(encoder);
tar.mode(tar::HeaderMode::Deterministic);
tar.follow_symlinks(false);
- // Fresh bundle-root index.md: okf_version + full listing.
+ // Fresh bundle-root index.md: okf_version + full listing, with no
+ // prose outside the list structure (some strict OKF validators
+ // read §11.3 as rejecting a stray sentence — issue #960 item 1).
families.sort();
let listing: String = families
.iter()
.map(|f| format!("- [{f}/]({f}/)\n"))
.collect();
- let index = format!(
- "---\nokf_version: \"0.2\"\n---\n\n# Bundle index\n\nConcept files live in these directories:\n\n{listing}"
- );
+ let index =
+ format!("---\nokf_version: \"0.2\"\n---\n\n# Bundle index — concept files by directory\n\n{listing}");
let mut header = tar::Header::new_gnu();
header.set_size(index.len() as u64);
header.set_mode(0o644);
@@ -8545,6 +8546,51 @@ mod tests {
assert_eq!(fm["type"], "Gotcha");
}
+ /// Issue #960 item 1: strict OKF validators read §11.3 ("follows the
+ /// structure in §8") as rejecting prose outside the list structure. The
+ /// generated `index.md` body, once its heading line is stripped, must
+ /// consist only of blank lines and `- [...]` list entries.
+ #[tokio::test]
+ async fn export_okf_index_has_no_prose_outside_the_list() {
+ let (_tmp, router) = read_page_test_router();
+ post_write_page(&router, "default", "scratch", "gotchas/build.md", "watch out").await;
+
+ let resp = router
+ .clone()
+ .oneshot(
+ Request::builder()
+ .method("POST")
+ .uri("/admin/export-okf?workspace=default&project=scratch")
+ .body(Body::empty())
+ .unwrap(),
+ )
+ .await
+ .unwrap();
+ assert_eq!(resp.status(), StatusCode::OK);
+ let bytes = axum::body::to_bytes(resp.into_body(), usize::MAX)
+ .await
+ .unwrap();
+ let dec = flate2::read::GzDecoder::new(std::io::Cursor::new(bytes.to_vec()));
+ let mut ar = tar::Archive::new(dec);
+ let mut index_body = String::new();
+ for entry in ar.entries().unwrap() {
+ let mut entry = entry.unwrap();
+ if entry.path().unwrap().display().to_string() == "index.md" {
+ use std::io::Read as _;
+ entry.read_to_string(&mut index_body).unwrap();
+ }
+ }
+ let parsed = ai_memory_wiki::parse(&index_body).unwrap();
+ for line in parsed.body.lines() {
+ let trimmed = line.trim();
+ assert!(
+ trimmed.is_empty() || trimmed.starts_with('#') || trimmed.starts_with("- "),
+ "prose line outside the list structure: {line:?}\nfull body: {}",
+ parsed.body
+ );
+ }
+ }
+
/// Post-audit regression: the things a REAL deployment's tree holds
/// beside concept pages — typed scope manifests and _pending
/// proposal sidecars — must not block the export. Sidecars are