data-olympus 0.4.2__tar.gz → 0.6.0__tar.gz

{data_olympus-0.4.2 → data_olympus-0.6.0}/.gitignore

@@ -6,6 +6,7 @@ __pycache__/
 *.egg-info/
 dist/
 build/
+/to-delete/
 # benchmark index artifact (regenerated by benchmarks/generate_artifacts.py)
 benchmarks/bench.db*
 # secrets hardening — never commit decrypted secrets or keys

{data_olympus-0.4.2 → data_olympus-0.6.0}/CHANGELOG.md

@@ -12,6 +12,158 @@ This project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-07-18
+
+### Added
+
+* **Added searchable MCP discovery.** `tools/list` now exposes seven core tools
+  plus `tool_search` and `call_tool` by default. Operators can set
+  `KB_TOOL_DISCOVERY_MODE=all` for the complete native catalog. Hidden tools
+  remain directly callable and retain the same authorization checks.
+* **Added executable OKF interoperability checks.** CI verifies both Data
+  Olympus consuming the pinned Google Knowledge Orchestration Framework sample
+  and the pinned upstream reference consumer reading the Data Olympus example
+  bundle. The immutable upstream revision and fixture checksums are recorded in
+  the repository.
+* **Added complete release candidates across every public channel.** One exact
+  source SHA now produces a PyPI prerelease wheel and sdist, GHCR image, GitHub
+  prerelease, and `release-provenance.json`. Stable promotion is an explicit
+  human approved dispatch that accepts only the highest complete candidate.
+* **Added deterministic benchmark provenance receipts.** The committed receipt
+  records source, corpus and query hashes, dependency lock, environment,
+  tokenizer and model identities, exact commands, seeds, result hashes, and
+  metric summaries. The documentation drift guard verifies it before checking
+  generated benchmark tables.
+
+### Security
+
+- **Bumped transitive dependency `mcp` 1.28.0 to 1.28.1** to close
+  CVE-2026-59950 / GHSA-vj7q-gjh5-988w (Dependabot #18, high severity).
+  The advisory covers the MCP Python SDK WebSocket server transport, which
+  data-olympus does not use (Streamable HTTP only); the bump is applied as
+  a precaution and to clear the release security gate. No API surface change.
+  (KNA-146)
+- **Bumped transitive benchmark dependency `torch` 2.12.1 to 2.13.0** to
+  close CVE-2025-3000 / GHSA-rrmf-rvhw-rf47 (Dependabot #19, low severity).
+  The affected `torch.jit.script` path is available only through the optional
+  `bench` extra and is not used by the production embedding implementation.
+  The patched dependency remains compatible with `sentence-transformers`.
+
+### Changed
+
+* **Made PyPI the primary installation and onboarding path.** The README and
+  quickstart now lead with `uvx` and `uv tool install`. Every packaging workflow
+  runs clean wheel and source distribution smoke tests at the expected version.
+  They exercise both console entry points, packaged enforcement files, REST
+  health, setup doctor, compact discovery, hidden direct calls, and complete
+  catalog mode.
+* **Hardened candidate to stable provenance.** Candidate and stable Python
+  artifacts are rebuilt from the same exact source, compared with only version
+  metadata normalized, and published through Trusted Publishing with no stored
+  PyPI credential. Stable OCI tags reuse the verified candidate digest and
+  never rebuild the image.
+
+- **Updated the supported runtime and development dependency baseline.**
+  FastMCP is now locked to 3.4.4 and requires `>=3.4.4,<4`, guaranteeing the
+  catalog search transform used by the default MCP tool-discovery mode. Regex
+  is updated to 2026.7.10 with the secret-scanning timeout and false-positive
+  regressions green. Mypy, types-regex, and Ruff were updated to their current
+  Dependabot revisions and pass the strict type and lint gates. (gh #159, #160,
+  #161, #162, #163)
+
+- **Added Glama related server metadata and maintenance notes.** `glama.json`
+  now names adjacent knowledge and memory MCP servers, and `docs/glama.md`
+  records the maintainer response and usage seeding steps for the Glama
+  maintenance profile. (gh #155 / KNA-145)
+
+- **Improved tool definitions for 7 tools (`kb_gate_check`, `kb_onboarding_status`,
+  `kb_compliance`, `kb_cleanup_plan`, `kb_get`, `kb_list`, `kb_outline`).** Each
+  docstring now includes a "Use when / use X instead when Y" guidance sentence.
+  `kb_gate_check` also discloses its audit-log side effect (`readOnlyHint=false`
+  is intentional). (gh #154 / KNA-144)
+
+- **Improved `kb_record_event` tool definition.** The docstring now discloses
+  behavior (durable, non-destructive audit append; requires write capability),
+  documents both event_type values (`gate_bypass`, `gate_degraded`) and all
+  required parameters, and gives explicit usage guidance on when to call vs.
+  when to use `kb_gate_check`, `kb_consult`, `kb_audit`, or `kb_compliance`
+  instead. (gh #153 / KNA-143)
+
+### Fixed
+
+* **Closed the remaining release verification gaps.** Every PyPI publishing
+  path now fails closed and verifies remote file hashes. Candidate provenance
+  validates its source, candidate tag, and image digest before publication.
+  Stable promotion derives its version from the requested complete candidate
+  and verifies that version against the candidate source commit. OKF freshness
+  reports only upstream fixture changes rather than unrelated repository commits.
+
+* **Corrected exact SHA CI readiness for conditional jobs.** Completed skipped
+  jobs are now non-blocking only when they are not required. Missing, pending,
+  failed, neutral, or skipped required checks still fail closed. This lets the
+  release gate accept a fully green pull request whose publishing workflow
+  intentionally skips upload and manual release paths.
+
+- **Hardened read tools against present SQLite indexes without tables.**
+  `kb_search`, `kb_get`, `kb_list`, `kb_outline`, onboarding status, and
+  cleanup planning now degrade to empty results or empty health instead of
+  surfacing raw `sqlite3.Error` failures. The Glama Docker sandbox now serves
+  the bundled `example-bundle` corpus so catalog introspection starts with a
+  populated, safe index. (gh #156 / KNA-142)
+
+## [0.5.0] - 2026-07-12
+
+### Added
+
+- **Version-immutability release guard (`scripts/check_version_free.py`).** A
+  published version (PyPI, the ghcr `:vX.Y.Z` image tag, or a GitHub
+  release/tag) is immutable, so the release process now refuses to republish an
+  existing version. The guard runs as the first step of `tag-release.yml`'s
+  `decide` job (before the tag is pushed, so a duplicate never leaves an
+  orphaned public tag) and in PR CI (to catch a duplicate declared version
+  before merge). A legitimate reconcile (local tag `vX.Y.Z` already at HEAD) is
+  allowed and skips the registry lookups; a registry outage fails closed. The
+  operator can override a stuck registry with `KB_BYPASS_VERSION_CHECK=1`.
+  (gh #148 / KNA-67)
+- **First-class reverse-proxy Host allowlist (`KB_PUBLIC_HOSTNAMES`).** New
+  config knob mapped onto fastmcp's Host-header allowlist when the HTTP app is
+  built, so operators configure data-olympus directly instead of reaching for
+  the dependency's `FASTMCP_HTTP_ALLOWED_HOSTS` env var (both are honoured and
+  merged). The server now emits a startup WARN when Host protection is on, it
+  binds a non-loopback address, and no public hostname is allowed: the exact
+  silent-breakage shape (readiness green, every proxied request 421) behind the
+  2026-07-09 kn-dev outage. A regression test boots the app with a configured
+  public hostname and asserts the good Host reaches the route while a foreign
+  Host is answered 421. (gh #139 / KNA-70)
+- **Prometheus `/metrics` endpoint (optional `metrics` extra).**
+  `prometheus-client` is an OPTIONAL dependency; with it installed, `GET
+  /metrics` serves the standard exposition format (pending/push queue depths,
+  frozen count, push-failure counter, staleness, live sessions, per-tool call
+  counters, index-build duration + last-build timestamp). Without the extra the
+  route returns `501` and every metric update inside the core background loops
+  is a silent no-op, so a standard deployment is unaffected. (gh #69 / KNA-71)
+- **Cached update-available signal.** The server now checks PyPI/GitHub for a
+  newer published `data-olympus` version in a background task and surfaces
+  `latest_version` / `update_available` in `kb_health` and
+  `GET /api/v1/health`. The health request path reads the cache only, and
+  compact health includes `latest_version` only when `update_available` is true.
+  Air-gapped deployments can set `KB_DISABLE_VERSION_CHECK=on` to make zero
+  outbound version-check calls. (gh #146 / KNA-68)
+- **Legacy corpus status migration.** Status-less documents from pre-0.4.0
+  corpora now default to `active` in the SQLite index when
+  `KB_STATUS_AUTOFILL=on` (the default), preserving in-force retrieval without
+  mutating source markdown during index builds. Operators can persist the same
+  default explicitly with the idempotent `data-olympus migrate status --apply`
+  command. (gh #147 / KNA-69)
+
+### Fixed
+
+- **`kb_consult` demoted_writes CTA count.** The maintenance CTA now counts only
+  the session's live pending entries and is omitted once none remain, instead of
+  reporting stale "N write(s) awaiting operator review" after every demoted entry
+  had been resolved (the demoted_writes / pending_actions surface shipped since
+  v0.4.0 via #131). (gh #137 / KNA-72)
+
 ## [0.4.2] - 2026-07-11
 
 ### Added
@@ -1551,7 +1703,9 @@ This project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - `docs/adoption.md`: bring-your-own-KB guide (author, lint, index, serve, wire an agent).
 - `docs/comparison.md`: how data-olympus relates to OKF, enterprise catalogs, markdown KB tools, agent-context conventions, RAG, and ADR tooling.
 
-[Unreleased]: https://github.com/knaisoma/data-olympus/compare/v0.4.1...HEAD
+[Unreleased]: https://github.com/knaisoma/data-olympus/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/knaisoma/data-olympus/compare/v0.5.0...v0.6.0
+[0.5.0]: https://github.com/knaisoma/data-olympus/compare/v0.4.2...v0.5.0
 [0.4.1]: https://github.com/knaisoma/data-olympus/compare/v0.4.0...v0.4.1
 [0.4.0]: https://github.com/knaisoma/data-olympus/compare/v0.3.5...v0.4.0
 [0.3.5]: https://github.com/knaisoma/data-olympus/compare/v0.3.4...v0.3.5

{data_olympus-0.4.2 → data_olympus-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: data-olympus
-Version: 0.4.2
+Version: 0.6.0
 Summary: Governance-grade knowledge-base format (OKF-compatible) plus CLI and single-writer MCP server
 Project-URL: Homepage, https://github.com/knaisoma/data-olympus
 Project-URL: Repository, https://github.com/knaisoma/data-olympus
@@ -21,7 +21,7 @@ Classifier: Topic :: Software Development :: Documentation
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Typing :: Typed
 Requires-Python: >=3.13
-Requires-Dist: fastmcp<4,>=3.2.0
+Requires-Dist: fastmcp<4,>=3.4.4
 Requires-Dist: pydantic>=2.9
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: regex>=2024.5
@@ -33,6 +33,7 @@ Provides-Extra: dev
 Requires-Dist: fastembed<0.9,>=0.8; extra == 'dev'
 Requires-Dist: httpx>=0.27; extra == 'dev'
 Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: prometheus-client>=0.20; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
 Requires-Dist: pytest-cov>=5.0; extra == 'dev'
 Requires-Dist: pytest>=8.3; extra == 'dev'
@@ -41,6 +42,8 @@ Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
 Requires-Dist: types-regex>=2024.5; extra == 'dev'
 Provides-Extra: embeddings
 Requires-Dist: fastembed<0.9,>=0.8; extra == 'embeddings'
+Provides-Extra: metrics
+Requires-Dist: prometheus-client>=0.20; extra == 'metrics'
 Description-Content-Type: text/markdown
 
 # data-olympus
@@ -52,11 +55,11 @@ problem we kept hitting with coding agents, what data-olympus does differently,
 it relates to Google's Open Knowledge Format, and where our benchmarks say it is
 strong and where it is not. The rest of this README is the technical reference.
 
-data-olympus is a governance-grade knowledge-base format and server for agent workforces. It is designed to be readable by [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf) (OKF) consumers: it inherits OKF's directory structure, frontmatter conventions, reserved filenames, and link model, then layers governance extensions on top (stable `id`, controlled `type`/`status`/`tier` fields, `supersedes` chains) plus a single-writer MCP server and a CLI. Formal conformance testing against the OKF reference tooling is not yet in place (tracked in [issue #82](https://github.com/knaisoma/data-olympus/issues/82)). The result is a git-native, version-controlled document graph of engineering standards, architectural decisions, and project knowledge that agents and humans can read, search, and extend without any proprietary service.
+data-olympus is a governance-grade knowledge-base format and server for agent workforces. It is readable by [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf) (OKF) consumers: it inherits OKF's directory structure, frontmatter conventions, reserved filenames, and link model, then layers governance extensions on top (stable `id`, controlled `type`/`status`/`tier` fields, `supersedes` chains) plus a single-writer MCP server and a CLI. CI proves two concrete directions against official Google OKF commit `d44368c15e38e7c92481c5992e4f9b5b421a801d`: its reference visualization consumer reads every concept in `example-bundle`, and data-olympus imports, lints, indexes, searches, and retrieves the pinned official Bitcoin sample. This is fixture-scoped interoperability evidence, not a blanket guarantee for every OKF bundle or future upstream revision. The result is a git-native, version-controlled document graph of engineering standards, architectural decisions, and project knowledge that agents and humans can read, search, and extend without any proprietary service.
 
 It governs *decisions*, not code. When an agent is about to make a choice (a library, a pattern, a migration), data-olympus surfaces the established standard or decision that should govern that choice. It is deliberately **not** a code-search, reference-finding, or "where is X used" tool: LSP, grep, and Sourcegraph already do that well. The retrieval task it targets is coding-intent to governing-rule, and it helps where current model interaction during vibe-coding is weakest: keeping the model aligned to patterns the team has already established as correct.
 
-**Status: pre-1.0 beta. Latest release: v0.4.1.**
+**Status: pre-1.0 beta. Stable releases are distributed through PyPI and GHCR.**
 
 ## Why
 
@@ -65,27 +68,36 @@ It governs *decisions*, not code. When an agent is about to make a choice (a lib
 - **Agent and human readable.** Plain markdown with YAML frontmatter. No SDK required to read or author a document.
 - **Governed multi-agent writes.** The single-writer MCP pipeline (advisory locks, per-session worktrees, durable push queue) prevents concurrent write races without requiring distributed locking infrastructure.
 - **Queryable by status, tier, and type.** Filter by `status: accepted`, `tier: T1`, or `type: decision` without post-processing. The `supersedes` chain makes it possible to trace decision history across the graph.
-- **Designed to be OKF-readable.** Built on OKF's directory structure, frontmatter conventions, reserved filenames, and link model; formal conformance testing against OKF reference tooling is tracked in [issue #82](https://github.com/knaisoma/data-olympus/issues/82), not yet implemented.
+- **Tested with official OKF tooling.** CI pins an exact Google OKF revision and proves both consumption directions over committed fixtures. The pin, fixture checksum, and Apache 2.0 license provenance live in `tests/okf/reference.json`.
 
 ## Quickstart
 
-Requires Python 3.13+ and [`uv`](https://docs.astral.sh/uv/).
+Requires Python 3.13+ and [`uv`](https://docs.astral.sh/uv/). Run the stable CLI
+directly from PyPI:
 
 ```bash
-# Install
-uv venv && uv pip install -e '.[dev]'
+uvx --from data-olympus data-olympus --help
+```
+
+Install it persistently when you are ready to create a bundle and run the
+server:
 
-# Lint the example bundle
-uv run data-olympus lint example-bundle
+```bash
+uv tool install data-olympus
+data-olympus init my-kb
+data-olympus-mcp --help
+```
 
-# ...or scaffold your own bundle instead of copying example-bundle/
-uv run data-olympus init my-kb
+An announced candidate remains opt in through its exact PyPI version:
 
-# Start the MCP server against the example bundle
-./scripts/run-local.sh
+```bash
+uvx --from 'data-olympus==0.6.0rc3' data-olympus --help
 ```
 
-See `docs/quickstart.md` for the full local-run walkthrough, including curl and `kb` CLI queries. See `docs/adoption.md` for the full bundle-authoring guide.
+See `docs/quickstart.md` for bundle initialization, server startup, readiness,
+agent registration, and the contributor source installation.
+
+See `docs/adoption.md` for the full bundle authoring guide.
 
 ## Documentation
 

{data_olympus-0.4.2 → data_olympus-0.6.0}/README.md

@@ -7,11 +7,11 @@ problem we kept hitting with coding agents, what data-olympus does differently,
 it relates to Google's Open Knowledge Format, and where our benchmarks say it is
 strong and where it is not. The rest of this README is the technical reference.
 
-data-olympus is a governance-grade knowledge-base format and server for agent workforces. It is designed to be readable by [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf) (OKF) consumers: it inherits OKF's directory structure, frontmatter conventions, reserved filenames, and link model, then layers governance extensions on top (stable `id`, controlled `type`/`status`/`tier` fields, `supersedes` chains) plus a single-writer MCP server and a CLI. Formal conformance testing against the OKF reference tooling is not yet in place (tracked in [issue #82](https://github.com/knaisoma/data-olympus/issues/82)). The result is a git-native, version-controlled document graph of engineering standards, architectural decisions, and project knowledge that agents and humans can read, search, and extend without any proprietary service.
+data-olympus is a governance-grade knowledge-base format and server for agent workforces. It is readable by [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf) (OKF) consumers: it inherits OKF's directory structure, frontmatter conventions, reserved filenames, and link model, then layers governance extensions on top (stable `id`, controlled `type`/`status`/`tier` fields, `supersedes` chains) plus a single-writer MCP server and a CLI. CI proves two concrete directions against official Google OKF commit `d44368c15e38e7c92481c5992e4f9b5b421a801d`: its reference visualization consumer reads every concept in `example-bundle`, and data-olympus imports, lints, indexes, searches, and retrieves the pinned official Bitcoin sample. This is fixture-scoped interoperability evidence, not a blanket guarantee for every OKF bundle or future upstream revision. The result is a git-native, version-controlled document graph of engineering standards, architectural decisions, and project knowledge that agents and humans can read, search, and extend without any proprietary service.
 
 It governs *decisions*, not code. When an agent is about to make a choice (a library, a pattern, a migration), data-olympus surfaces the established standard or decision that should govern that choice. It is deliberately **not** a code-search, reference-finding, or "where is X used" tool: LSP, grep, and Sourcegraph already do that well. The retrieval task it targets is coding-intent to governing-rule, and it helps where current model interaction during vibe-coding is weakest: keeping the model aligned to patterns the team has already established as correct.
 
-**Status: pre-1.0 beta. Latest release: v0.4.1.**
+**Status: pre-1.0 beta. Stable releases are distributed through PyPI and GHCR.**
 
 ## Why
 
@@ -20,27 +20,36 @@ It governs *decisions*, not code. When an agent is about to make a choice (a lib
 - **Agent and human readable.** Plain markdown with YAML frontmatter. No SDK required to read or author a document.
 - **Governed multi-agent writes.** The single-writer MCP pipeline (advisory locks, per-session worktrees, durable push queue) prevents concurrent write races without requiring distributed locking infrastructure.
 - **Queryable by status, tier, and type.** Filter by `status: accepted`, `tier: T1`, or `type: decision` without post-processing. The `supersedes` chain makes it possible to trace decision history across the graph.
-- **Designed to be OKF-readable.** Built on OKF's directory structure, frontmatter conventions, reserved filenames, and link model; formal conformance testing against OKF reference tooling is tracked in [issue #82](https://github.com/knaisoma/data-olympus/issues/82), not yet implemented.
+- **Tested with official OKF tooling.** CI pins an exact Google OKF revision and proves both consumption directions over committed fixtures. The pin, fixture checksum, and Apache 2.0 license provenance live in `tests/okf/reference.json`.
 
 ## Quickstart
 
-Requires Python 3.13+ and [`uv`](https://docs.astral.sh/uv/).
+Requires Python 3.13+ and [`uv`](https://docs.astral.sh/uv/). Run the stable CLI
+directly from PyPI:
 
 ```bash
-# Install
-uv venv && uv pip install -e '.[dev]'
+uvx --from data-olympus data-olympus --help
+```
+
+Install it persistently when you are ready to create a bundle and run the
+server:
 
-# Lint the example bundle
-uv run data-olympus lint example-bundle
+```bash
+uv tool install data-olympus
+data-olympus init my-kb
+data-olympus-mcp --help
+```
 
-# ...or scaffold your own bundle instead of copying example-bundle/
-uv run data-olympus init my-kb
+An announced candidate remains opt in through its exact PyPI version:
 
-# Start the MCP server against the example bundle
-./scripts/run-local.sh
+```bash
+uvx --from 'data-olympus==0.6.0rc3' data-olympus --help
 ```
 
-See `docs/quickstart.md` for the full local-run walkthrough, including curl and `kb` CLI queries. See `docs/adoption.md` for the full bundle-authoring guide.
+See `docs/quickstart.md` for bundle initialization, server startup, readiness,
+agent registration, and the contributor source installation.
+
+See `docs/adoption.md` for the full bundle authoring guide.
 
 ## Documentation
 

{data_olympus-0.4.2 → data_olympus-0.6.0}/SPEC.md

@@ -10,7 +10,7 @@
 
 Knowledge that lives in plain markdown with YAML frontmatter is version-controllable, portable, and readable by both humans and automated agents without any special runtime. A git repository becomes the primary audit trail: every change is a commit, rollback is `git revert`, and the full history ships with the bundle.
 
-This specification is **designed to be readable by consumers of Google's Open Knowledge Format (OKF)**: it inherits OKF's directory structure, frontmatter conventions, reserved filenames, and link model. Formal conformance testing against the OKF reference tooling is not yet in place ([issue #82](https://github.com/knaisoma/data-olympus/issues/82) tracks it); the claim today rests on shared structure by construction, not on an executable check. On top of that baseline we layer **governance extensions**: a stable `id` field decoupled from path, a controlled type vocabulary, explicit `status` and `tier` fields, ADR chain links, and a single-writer MCP server that enforces propose/review/commit safety across multiple concurrent agents.
+This specification is **readable by consumers of Google's Open Knowledge Format (OKF)**: it inherits OKF's directory structure, frontmatter conventions, reserved filenames, and link model. Executable CI checks pin official Google OKF commit `d44368c15e38e7c92481c5992e4f9b5b421a801d`. The pinned reference visualization consumer reads every concept in the data-olympus example bundle, and data-olympus imports, lints, indexes, searches, and retrieves the pinned official sample bundle. This proves those two fixture-scoped interoperability directions; it does not claim that every possible OKF bundle or future upstream revision has been tested. On top of that baseline we layer **governance extensions**: a stable `id` field decoupled from path, a controlled type vocabulary, explicit `status` and `tier` fields, ADR chain links, and a single-writer MCP server that enforces propose/review/commit safety across multiple concurrent agents.
 
 The result is a format that is portable and human-readable at rest (plain files, no database required) while supporting structured queries, multi-agent write safety, and progressive disclosure when served through the data-olympus MCP.
 
@@ -60,7 +60,7 @@ The bundle may be organized into subdirectories of any depth. Subdirectory names
 
 ### 4.1 Base layer (inherited from OKF)
 
-The following conventions are inherited from OKF for interoperability. They are designed so an OKF consumer can read a data-olympus bundle; this is not yet backed by an executable conformance test against OKF reference tooling (see section 11 and [issue #82](https://github.com/knaisoma/data-olympus/issues/82)).
+The following conventions are inherited from OKF for interoperability. The exact executable evidence and its limits are described in section 11.
 
 - Documents are UTF-8 encoded markdown files.
 - Structured metadata is expressed as a YAML frontmatter block at the top of the file, opened and closed by a bare `---` line.
@@ -281,6 +281,13 @@ The serving transport MUST be streamable HTTP (not stdio). The MCP endpoint is `
 
 **Readiness probes MUST NOT target `/api/v1/health`.** A load balancer or orchestrator readiness check MUST use `GET /readyz` (200 once the process is up and the index is loaded, independent of data staleness). `/api/v1/health` keeps a 503-on-degraded contract for data-freshness alerting; wiring it as a readiness probe would eject a healthy single replica from its Service on a transient git-remote staleness. See [`docs/serving.md`](docs/serving.md).
 
+**Update-available signal.** A server MAY surface cached `latest_version` and
+`update_available` fields in `kb_health` / `GET /api/v1/health` when a newer
+data-olympus package is published. These are informational serving-layer fields
+only: they MUST NOT affect `degraded` or readiness, and the health request path
+MUST read a cache rather than perform outbound registry calls. Deployments MAY
+disable the check entirely for air-gapped operation.
+
 **Enforcement endpoints.** A server MAY expose an enforcement surface that turns the advisory KB into a gated consultation proxy for code and architectural decisions. The endpoints are:
 
 - `POST /api/v1/consult`: record a consultation for a `(source_session, workspace)` pair and return the governing rules for the supplied intent.
@@ -351,11 +358,13 @@ The `spec_version` field is optional in bundles targeting this `0.1` draft. It b
 
 **Issue #114 (write-path `status` enforcement) does NOT bump this version.** `status` has been a required field under section 4.2 — and a `kb lint` error when absent — since the `0.1` draft; no prior version of this document ever described it as recommended, so there is no required-field-semantics change to record here. What issue #114 adds is a reference-implementation write-path check (section 8): a NEWLY created document missing `status` is now rejected at commit time, closing a gap where the write path was more permissive than `kb lint`. This does not affect any already-conformant bundle (which by definition already has `status` on every document) and does not change how an existing bundle is read, parsed, or validated — only how a brand-new document is admitted through the write path. Per the minor/major criteria above, that is neither: it is a reference-implementation enforcement-timing change, not a format change, so it is documented here rather than as a version increment. A bundle that is already non-conformant (missing `status` on one or more legacy documents) is unaffected in how it is READ — those documents keep being served, just never as in-force — see the maintenance ledger migration path in [`docs/operations.md`](docs/operations.md).
 
+**Issue #147 / KNA-69 (legacy status autofill) also does NOT bump this version.** `#147` is a reference-implementation read-side default, not a format change: it does not alter what `status` means, its controlled vocabulary, or the requirement that documents carry it. It changes how the reference implementation treats a legacy document that is missing `status`. Under `#114` such a document was served but never in-force, so a pre-0.4.0 corpus silently lost its in-force guidance on upgrade. Under `#147` the index build treats a missing `status` as `active` by default (`KB_STATUS_AUTOFILL=on`), so the corpus keeps governing exactly as it did before the upgrade. This intentionally reverses the conservative "never guess status" stance `#114` took, and it does so for one deliberate reason: for the narrow legacy-upgrade case, a seamless default that preserves prior in-force behavior is worth more than conservatively flagging every legacy document as not-in-force and blocking it until a manual fix lands. The reversal is bounded and reversible: it applies only to documents with NO `status` (an explicit status is always honored verbatim), never rewrites the markdown source at index time (the build stays a read-only parse; the physical gap is still tracked by the maintenance ledger so the `missing_status` CTA keeps nagging), and is fully disabled by `KB_STATUS_AUTOFILL=off` for a deployment that prefers explicit flagging. Persisting the default into the markdown source is a separate, explicit operator action (`data-olympus migrate status --apply`), never an implicit side effect of indexing. See [`docs/operations.md`](docs/operations.md) section 5.2.
+
 ---
 
 ## 11. Relationship to other formats
 
-**OKF (Open Knowledge Format).** data-olympus is designed to be readable by OKF consumers: our governance extensions (`id`, `status`, `tier`, `supersedes`, `superseded_by`, `contradicts`, `owner`, and the write pipeline) are meant to be invisible to OKF consumers because OKF requires tolerating unknown keys. This is a design intent backed by shared structure (directory layout, frontmatter conventions, reserved filenames, link model), not by an executable conformance test against the OKF reference tooling; [issue #82](https://github.com/knaisoma/data-olympus/issues/82) tracks adding one. The two formats are complementary: OKF defines the interoperable baseline; data-olympus adds the governance layer needed for multi-agent write safety and ADR chain tracking. The relationship is analogous to how OpenAPI is a profile of JSON Schema. See [`docs/okf-profile.md`](docs/okf-profile.md) for the full field-by-field profile: which extensions are stable, which are runtime-only serving fields, and which are experimental candidates tracked against open OKF ecosystem discussions.
+**OKF (Open Knowledge Format).** data-olympus is readable by OKF consumers: our governance extensions (`id`, `status`, `tier`, `supersedes`, `superseded_by`, `contradicts`, `owner`, and the write pipeline) are invisible to a permissive OKF consumer because OKF requires tolerating unknown keys. CI pins official Google OKF commit `d44368c15e38e7c92481c5992e4f9b5b421a801d`, verifies the vendored fixture and Apache 2.0 license checksums, runs the pinned reference visualization consumer over every concept in `example-bundle`, and runs the data-olympus importer, linter, index, search, and retrieval path over the pinned official sample. These checks prove the named fixtures and revision only. The two formats are complementary: OKF defines the interoperable baseline; data-olympus adds the governance layer needed for multi-agent write safety and ADR chain tracking. The relationship is analogous to how OpenAPI is a profile of JSON Schema. See [`docs/okf-profile.md`](docs/okf-profile.md) for the full field-by-field profile and the exact evidence boundary.
 
 **Obsidian and Notion.** Both support markdown files with YAML frontmatter and backlink graphs. data-olympus bundles can be opened in Obsidian as a vault; the frontmatter is visible in properties panels and the body renders normally. The difference is governance: Obsidian and Notion have no concept of propose/pending/resolve write pipelines, controlled-vocabulary enforcement, or tier-based access control. data-olympus complements these tools rather than replacing them: a team may author in Obsidian and commit conformant bundles to git for the MCP server to serve.
 

{data_olympus-0.4.2 → data_olympus-0.6.0}/benchmarks/README.md

@@ -4,6 +4,11 @@ A reproducible, retrieval-only benchmark that measures token cost and retrieval
 accuracy of five methods over a synthetic committed corpus, plus a governance
 ablation and one reproducible run on a real (non-templated) corpus.
 
+**Maintainer-produced; not independently reproduced.** The committed
+[`results/receipt.json`](results/receipt.json) records exact source, inputs,
+dependencies, commands, seeds, environment, and output hashes for independent
+verification.
+
 ## What it measures
 
 For each (method, query) pair the harness records:

{data_olympus-0.4.2 → data_olympus-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "data-olympus"
-version = "0.4.2"
+version = "0.6.0"
 description = "Governance-grade knowledge-base format (OKF-compatible) plus CLI and single-writer MCP server"
 readme = "README.md"
 requires-python = ">=3.13"
@@ -21,7 +21,7 @@ classifiers = [
 ]
 dependencies = [
     "pyyaml>=6.0",
-    "fastmcp>=3.2.0,<4",
+    "fastmcp>=3.4.4,<4",
     "pydantic>=2.9",
     # The secret-scanning gate (issue #71) runs operator-supplied
     # KB_SECRET_SCAN_EXTRA_PATTERNS through the `regex` engine because it
@@ -46,6 +46,14 @@ Changelog = "https://github.com/knaisoma/data-olympus/blob/main/CHANGELOG.md"
 embeddings = [
     "fastembed>=0.8,<0.9",
 ]
+# Optional Prometheus /metrics endpoint (issue #69). NOT a core dependency: the
+# metrics registry is a no-op shim when prometheus-client is absent (its inc/
+# set/observe calls live inside core background loops and tool wrappers, so a
+# bare import must never crash a standard deployment). With the extra installed,
+# /metrics serves the exposition format; without it, /metrics returns 501.
+metrics = [
+    "prometheus-client>=0.20",
+]
 dev = [
     "pytest>=8.3",
     "pytest-asyncio>=0.24",
@@ -59,6 +67,9 @@ dev = [
     # runtime; the tests opt in via KB_EMBEDDINGS_MODE and skip if the model
     # cannot be fetched in the sandbox).
     "fastembed>=0.8,<0.9",
+    # Exercise the Prometheus /metrics path in CI (the exposition-format test
+    # skips when this is absent; the no-op-shim tests run regardless).
+    "prometheus-client>=0.20",
 ]
 bench = [
     "tiktoken>=0.8",

{data_olympus-0.4.2 → data_olympus-0.6.0}/src/data_olympus/cli/main.py

@@ -143,6 +143,8 @@ def build_parser() -> argparse.ArgumentParser:
     add_init_subparser(sub)
     from data_olympus.cli.verify_cmd import add_verify_subparser
     add_verify_subparser(sub)
+    from data_olympus.cli.migrate_cmd import add_migrate_subparser
+    add_migrate_subparser(sub)
     return parser
 
 

data_olympus-0.6.0/src/data_olympus/cli/migrate_cmd.py

@@ -0,0 +1,105 @@
+"""`data-olympus migrate status`: persist the status autofill to disk (#147).
+
+The `status` subcommand writes the `status` field into legacy (pre-0.4.0)
+markdown docs that are missing it, using the default `active` (see
+``data_olympus.status_migrate``). This is the EXPLICIT counterpart to the
+index build's VIRTUAL autofill (KB_STATUS_AUTOFILL): the build never touches
+the markdown source, so an operator runs this once to make the change durable.
+
+Without ``--apply`` the command is a DRY RUN: it reports which files would be
+changed and exits 0, changing nothing. ``--apply`` performs the write and (when
+an audit log path is configured) records one audited event per changed file.
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import argparse
+
+
+def add_migrate_subparser(
+    sub: argparse._SubParsersAction[argparse.ArgumentParser],
+) -> None:
+    """Wire the ``migrate`` command (with its ``status`` subcommand) in."""
+    p_migrate = sub.add_parser(
+        "migrate",
+        help="one-off corpus migrations (e.g. persist the status autofill)",
+    )
+    migrate_sub = p_migrate.add_subparsers(dest="migrate_command", required=True)
+    p_status = migrate_sub.add_parser(
+        "status",
+        help="write a default `status: active` into legacy docs missing it (#147)",
+    )
+    p_status.add_argument(
+        "path", nargs="?", default=".", help="corpus root (default: .)"
+    )
+    p_status.add_argument(
+        "--apply",
+        action="store_true",
+        help="write the change to disk (default: dry run, reports and changes nothing)",
+    )
+    p_status.add_argument(
+        "--audit-log",
+        default=None,
+        help="audit-log path for the applied writes (default: $KB_AUDIT_LOG_PATH; "
+        "omitted entirely if neither is set)",
+    )
+    p_status.set_defaults(func=_cmd_migrate_status)
+
+
+def _cmd_migrate_status(args: argparse.Namespace) -> int:
+    import sys
+
+    from data_olympus.format import discover_bundle_files
+    from data_olympus.format.document import Document
+    from data_olympus.status_migrate import DEFAULT_STATUS, apply_status_autofill
+
+    root = Path(args.path)
+    if not root.is_dir():
+        print(f"error: {root} is not a directory", file=sys.stderr)
+        return 2
+
+    if not args.apply:
+        # Dry run: report the files that WOULD be rewritten, change nothing.
+        would_change: list[str] = []
+        for md in discover_bundle_files(root):
+            try:
+                doc = Document.load(md)
+            except ValueError:
+                continue  # malformed frontmatter: a lint concern, not migrated
+            status = doc.frontmatter.get("status")
+            if not (isinstance(status, str) and status.strip()):
+                would_change.append(str(md.relative_to(root)))
+        for rel in would_change:
+            print(f"would set status: {DEFAULT_STATUS}  {rel}")
+        print(
+            f"dry run: {len(would_change)} document(s) would be updated "
+            f"(re-run with --apply to write)"
+        )
+        return 0
+
+    audit_log = None
+    audit_path = args.audit_log or os.environ.get("KB_AUDIT_LOG_PATH")
+    if audit_path:
+        from data_olympus.audit_log import AuditLog
+
+        audit_log = AuditLog(
+            log_path=audit_path,
+            hmac_key=os.environ.get("KB_AUDIT_HMAC_KEY", ""),
+        )
+
+    result = apply_status_autofill(root, audit_log=audit_log)
+    for rel in result.changed_paths:
+        print(f"set status: {DEFAULT_STATUS}  {rel}")
+    if result.skipped_malformed:
+        for rel in result.skipped_malformed:
+            print(f"skipped (malformed frontmatter, fix with `kb lint`): {rel}")
+    print(
+        f"applied: {result.changed} changed, {result.already_present} already had "
+        f"status, {len(result.skipped_malformed)} skipped "
+        f"({result.scanned} scanned)"
+    )
+    return 0