# OpenClerk v0.2.15

This patch release improves existing-document editing ergonomics for the installed JSON runner. It adds an atomic full-document replacement primitive, hardens mutation schemas against ignored fields, makes section replacement heading behavior explicit, and keeps repair inside OpenClerk through write receipts with compact diffs, preimage hashes, and rollback requests.

## Changed

- Added `replace_document` for approved existing-document full-note replacement by `doc_id`, with optional matching `path`, full Markdown body or structured metadata plus body, frontmatter validation before writing, stable id preservation unless explicitly changed, and path/doc_id mismatch rejection.
- Added existing-document update receipts with before/after title, path, and headings, compact diffs, `preimage_sha256`, and runner-visible `replace_document` rollback requests for applied existing-document edits.
- Added dry-run and diff previews for `replace_document` and `replace_section`; unsupported `dry_run` and `diff` fields reject before any durable write.
- Hardened mutation schemas so required fields reject before writing and unknown or ignored fields fail consistently, including rejecting `replace_section` requests that use `body` instead of `content`.
- Improved `replace_section` by documenting that the matched heading is preserved by default, rejecting same-level replacement headings unless `include_heading=true`, supporting `include_heading=true` for section retitles, preserving nested subsections by default, and supporting `include_subsections=false` when callers intentionally want only direct section content.
- Updated `get_document` to accept either `doc_id` or vault-relative `path`, so agents can drill down directly from search/list results without a surprising retry.
- Tightened write workflow handoffs so validation and dry-run results return exact next approved write requests; full-note replacements point to `replace_document`, not `replace_section`, and section-edit handoffs report whether the heading is preserved.
- Scoped `memory_router_recall_report` wording to memory-router policy evidence and points ordinary vault fact recall toward retrieval `search`.
- Updated compact capabilities, CLI help, and `skills/openclerk/SKILL.md` to advertise the new write surfaces while preserving local-first runner-only boundaries.
- 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.15`.
- 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 `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.
- 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 policy evidence 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`; source-audit and evidence-bundle natural rows pass safety, capability, and `workflow_action_acceptable` UX, while compile-synthesis passes safety/capability but remains `taste_debt` tracked by follow-up GitHub issue #30.
- 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.
- Live install, upgrade, and module-command smoke evidence is committed at `docs/evals/results/ockp-live-install-upgrade-module-smoke.md`.
- Optional local release bundle construction passed for `v0.2.15`, including platform archives, skill archive, source archive, SBOM, checksums, and installer generation.
