# OpenClerk v0.2.5

This patch release hardens the v0.2 building-block surface: semantic module registration now rejects surprising command and provider settings, source placement and synthesis candidate planning are tighter, git lifecycle reports stay inside nested vault boundaries, and module release automation can publish embedding module patch releases without changing core lexical retrieval.

## Changed

- Hardened semantic module registration so embedding providers always use `semantic-retrieval-adapter` on `PATH`, `command_args` are rejected, Ollama URLs must stay loopback HTTP, and Gemini configuration must use the canonical `https://generativelanguage.googleapis.com/v1beta` endpoint with `runtime_config:GEMINI_API_KEY`.
- Hardened the bundled `semantic-retrieval-adapter` for the `ollama-embeddings` and `gemini-embeddings` module releases with stricter provider validation, chunk limits, section chunking, retry/backoff handling, and citation-bearing responses while keeping semantic search explicit and module-gated.
- Updated embedding module manifests and module install guidance for `ollama-embeddings/v0.1.1` and `gemini-embeddings/v0.1.1`; `tesseract-ocr` remains at `v0.1.0` because its module behavior did not change.
- Improved source URL placement planning, web search planning, synthesis candidate discovery, duplicate-candidate reporting, artifact candidate planning, and source-sensitive audit behavior without adding browser acquisition, HTTP/MCP bypasses, direct SQLite access, hidden local-file parsing, or approval-free durable writes.
- Hardened git lifecycle reporting for nested vault boundaries, runner error conversion, runtime config handling, URL validation, pagination, projection freshness, and concurrency evidence.
- Added module-only release workflow support, module release bundle building, module installer packaging, module skill validation on module tags, draft asset verification, and module install/upgrade smoke validation.
- Updated maintainer docs and work items workflow guidance for per-work-item review, local commit discipline, repo-relative committed artifacts, and release evidence separation between safety, capability, and UX quality.
- Preserved `ingest_source_url` update mode behavior from the v0.2 line: missing `source.mode` defaults to `create`, duplicate creates reject, `source.mode: "update"` re-ingests an existing `source.url`, and mismatched `path_hint` or `asset_path_hint` values conflict without writing extra docs or assets.
- Preserved same-SHA source URL update behavior: same-SHA updates are no-ops without `source_updated` provenance or projection invalidation churn.
- Preserved changed-PDF source URL update behavior: changed-PDF updates preserve source and asset paths, refresh searchable extracted text and citations, emit previous/new SHA provenance, and expose stale dependent synthesis through `projection_states`.

## Verification

- Local release-doc validation passed for `v0.2.5`.
- Local Agent Skill validation passed for `skills/openclerk/SKILL.md`.
- Local module skill validation passed for `modules/ollama-embeddings/skill/ollama-embeddings/SKILL.md`, `modules/gemini-embeddings/skill/gemini-embeddings/SKILL.md`, and unchanged `modules/tesseract-ocr/skill/tesseract-ocr/SKILL.md`.
- Local committed-artifact validation passed with repo-relative artifact paths and neutral raw-log placeholders.
- Local formatting, linting, and unit-test gates passed with the repository-pinned toolchain.
- Core and embedding module release bundles were built locally for `v0.2.5`, `ollama-embeddings/v0.1.1`, and `gemini-embeddings/v0.1.1`, with checksums verified before tagging.
- The current production OpenClerk AgentOps gate is committed at `docs/evals/results/ockp-agentops-production.md`.
- Expanded repo-docs dogfood evidence is committed at `docs/evals/results/ockp-repo-docs-dogfood.md`, covering installed-runner retrieval, synthesis maintenance, decision-record explainability, release-readiness answers, read-side tag filtering, memory-router recall reports, and release synthesis freshness over this repository's committed public markdown docs.
- Targeted workflow-action evidence is committed at `docs/evals/results/ockp-compile-synthesis-workflow-action.md`, `docs/evals/results/ockp-source-audit-workflow-action.md`, and `docs/evals/results/ockp-evidence-bundle-workflow-action.md`, covering the promoted narrow workflow-action surfaces with acceptable natural-row UX.
- Targeted install, upgrade, and module-agent evidence is committed at `docs/evals/results/ockp-install-upgrade-module-agent-instructions.md`.
- Targeted semantic recall module evidence is committed at `docs/evals/results/ockp-semantic-recall-ollama-module.md` and `docs/evals/results/ockp-semantic-recall-gemini-module.md`.
- Targeted source URL update evidence remains committed at `docs/evals/results/ockp-source-url-update-mode.md`, covering duplicate create rejection, same-SHA no-op behavior, changed-PDF stale synthesis visibility, and path-hint conflict no-write behavior for the shipped runner and skill.
- Targeted supplied-transcript video/YouTube source evidence remains committed at `docs/evals/results/ockp-video-youtube-canonical-source-note.md`, covering create/update behavior, transcript provenance, citation-bearing search, no-op behavior, stale synthesis visibility, and external-tool bypass rejection.
- Live install, upgrade, and module-command smoke evidence is committed at `docs/evals/results/ockp-live-install-upgrade-module-smoke.md`.
