v1.34.0

[github-actions[bot]]

Docs — contracts / lifecycle / troubleshooting pages + README audit (#306, #310, #311, #315)

Documentation batch closing the fleet-day knowledge gaps (no code change, no version bump):

• docs/contracts.md (new, #310) — the draft-visibility matrix (status × auto-extracted tag × --include-drafts → recall/render), the --json output shapes (pointing at the #301 Zod schemas) + recall_status semantics, and the FTS sanitization ruleset (what's stripped, what causes fts_unavailable).
• docs/lifecycle.md (new, #311) — the atom status state machine (incl. superseded vs archived vs expired and its recall behaviour), the tiered auto-promotion table (incl. #309 procedure executed-once), tag semantics (reserved auto-extracted, the #262 whitespace rule), and the hand-authored-vs-auto-extracted draft visibility asymmetry.
• docs/troubleshooting.md (new, #315) — five fleet failure modes with symptom/cause/fix/verify: better-sqlite3 node-gyp rebuild, cron PATH/MK_BIN (references the #345 fix), claude login expiry silently no-op'ing mk extract, fts_unavailable punctuation, and the EMBEDDING_API_KEY-vs-OPENAI_API_KEY key-set-but-0-vectors trap.
• README audit (#306) — most items were already current from prior audits (qualified test count, correct --task/--embed distinction, documented key fallback); added a NanoClaw/OpenClaw one-line gloss and links to the three new docs.

Added — --json output contracts as exported Zod schemas (#301)

Every mk --json output is an implicit contract integrators learn by trial-and-error (the seeds_used mis-parse is the canonical cost). Zod is already a runtime dep, so the contracts are now explicit, exported, and test-enforced. New src/schemas.ts exports Zod schemas (+ inferred types) for the four integrator-friction commands, from the package barrel: RecallOutputSchema (ContextBundle), DoctorOutputSchema (healthy/issue_count/issues/checks/fixes), RememberOutputSchema, EvalOutputSchema (fixtures/ok/exit_code), plus the building blocks (AtomOutputSchema, DoctorCheckResultSchema, EvalResultSchema, EvalQueryResultSchema). Derived from the actual output shapes; .passthrough() + optional so additive fields don't break consumers. +5 tests (test/schemas.test.ts) run the real CLI and validate its output against each schema — the schema is the authoritative oracle, so it can't drift. The full human-readable contracts page is the #310 docs batch (it references these). New public exports → MINOR-class (rolls into v1.34.0).

Added — tag-whitespace hygiene: tag-format doctor check + mk remember warning (#262, absorbs #264)

Tags in the mk convention are single hyphen-separated tokens. A space-joined list emitted as one YAML item (tags: ["AIRE peer-review N-version …"] — from an observer LLM, or a quoted mk remember --tags "foo bar") is valid YAML but ONE opaque token that silently breaks FTS tag queries + tag filtering. Two delivery points share one isValidTag() predicate (src/format.ts): (1) a new tag-format mk doctor check (src/doctor/checks/tag-format.ts, warn) flags any atom whose scope.tags[] contains a whitespace token, naming the atom + tag; (2) mk remember warns at write time (non-fatal — still writes) when a --tags value contains whitespace, with a tag_warning field in --json mode. Both sides check the normalized view (normalizeTags) so they agree: a space-joined "foo bar" is flagged, a comma-list "foo, bar" (split cleanly) is not. No fix() (splitting is ambiguous → human review) — note this means a store carrying a legacy whitespace tag now makes mk doctor exit 1 (warn), surfaced by the cron self-canary, until the tag is hand-split. +7 tests (test/tag-whitespace.test.ts). Absorbs #264 (its mk remember half). Internal check + warning, isValidTag exported from format.ts — PATCH-class.

Added — mk lint store-composition skew check + --strict (#316)

Store composition is a retrieval-quality variable, not just hygiene: a belief-dominated store buries facts in recall (Mai's 89%-belief store sat a loud belief in the top-3 of 8/11 golden queries). mk lint (knowledge-health) gains a composition check over active atoms: warns on belief monoculture (beliefs > 80% of active atoms, citing the type histogram + recall-degradation risk) and on a composition gap (a core type — fact/decision/procedure/preference — with 0 active atoms). Only engages at ≥ 20 active atoms so fresh / lifecycle-seed-only / small stores aren't false-flagged. New mk lint --strict exits 1 when any warning is present (default mk lint still always exits 0 — no exit-code change without the flag). Engine findCompositionSkew (src/lint.ts), new LintFinding.category: 'composition'. +7 tests (test/lint-composition.test.ts). New CLI flag, no exported-API change — rolls into the v1.34.0 MINOR.

Fixed — cron wrapper memory-dir validation (host-vs-container) (#347)

mk init --cron bakes the given memory-dir into the wrapper; if generated with a container path while the systemd/cron timer fires on the host, mk render -d "$MEMORY_DIR" fails "Memory directory not found" and the nightly silently goes dark (the other half of the Taj incident; PATH was #345). Two layers: (1) mk init --cron now warns (non-fatal) when the baked memory-dir doesn't exist on the generating host — catching the container-vs-host mistake early; (2) a new wrapper-memory-dir mk doctor check (src/doctor/checks/wrapper-memory-dir.ts, reuses discoverWrappers + parseGeneratedHeader) flags any installed wrapper whose baked # mk:memory-dir doesn't resolve on the host it runs on, so doctor (and the cron self-canary) catch it where it matters. +4 tests. Internal check + a generation warning, no public API change — PATCH-class.

Changed — mk_context_bundle / checkpoint() now embeds the query when a key is set (#323)

mk_context_bundle (the documented primary session-start/handoff retrieval) → checkpoint() used the synchronous FTS-only recall path and never embedded the query, even with EMBEDDING_PROVIDER + EMBEDDING_API_KEY set — only mk_recall took the semantic path, so conceptual queries missed at session start. checkpoint() is now async and routes recall through recallWithEmbeddings / recallIsolatedWithEmbeddings (same embed-then-FTS-fallback as mk recall --embed): with a key + task it embeds the query; with no key or no task it degrades silently to FTS — no regression for offline/no-key/no-task. Callers updated to await (mk_context_bundle MCP handler, mk checkpoint CLI, the openclaw plugin's bundle + pre-compaction hooks). +3 deterministic tests (test/checkpoint.test.ts) asserting the embed path engages with a key + task and is skipped otherwise; the live golden-query improvement is verified operator-side with a real key. Observable behavior change on a public retrieval path → MINOR-class (sets v1.34.0). checkpoint()'s return type changes to Promise<CheckpointResult>.

---

This discussion was created from the release v1.34.0.