docs: changelog for v0.5.1

[dpup]

Summary

Cuts the v0.5.1 patch entry and updates CLAUDE.md to document patch releases in the changelog going forward.

The v0.5.1 entry consolidates the existing Unreleased items (TUI debug shortcuts, gatekeeper extraction, IPv6 firewall, two network.host/ip6tables fixes) and adds the PRs merged since v0.5.0 that weren't yet in the changelog:

• MOAT_HOME (feat(config): honor MOAT_HOME to relocate moat state directory #323)
• Multi-runtime manager (feat: multi-runtime manager for cross-engine CLI commands #311)
• Python 3.13/3.14 + uv bump (feat(deps): add Python 3.13/3.14 and bump uv to 0.11.6 #316)
• Run-state corruption fix (fix(run): stop reconciliation from corrupting persisted run state #309)
• Custom network host reachability (fix(proxy): reach host from custom networks on Docker Desktop #337)
• MCP auth.grant credential loading (fix(run): auto-include MCP auth grants in credential loading #338)
• Multi-line YAML block scalars in build hooks (fix(deps): handle multi-line YAML block scalars in build hooks #339)
• Bounded Close() and orphan network reaping (fix(run): bound network create and reap orphan moat networks #342)
• Capability-mismatch error message (fix: correct error message to suggest command that actually exists #336)

#321 is intentionally excluded — its behavior is already documented under the v0.5.0 network.host bypass entry. CI-only and test-only PRs (#312, #313, #314, #326, #328–#332, #344) are also excluded.

Test plan

• Render the changelog locally and verify PR links resolve
• Confirm date matches the planned tag day for v0.5.1

[claude]

Claude finished @dpup's task in 1m 18s —— View job

---

Code review: PR #347

• Read CHANGELOG.md and style guide
• Check entries against CLAUDE.md changelog conventions
• Verify PR links format and content
• Final review summary

---

Overall

The changelog entries are well-written overall — factual, active voice, and most Fixed entries follow the "Fix X — previously, Y happened when Z" pattern correctly. A few things to flag:

---

Issue 1 — Patch release contradicts CLAUDE.md convention

CLAUDE.md states:

CHANGELOG.md tracks major and minor releases (skip patch releases).

v0.5.1 is a patch release. Given the included security fix and the substantive additions (MOAT_HOME, multi-runtime manager), there's a reasonable argument for documenting it — but this is a deliberate deviation from the stated convention. Worth a conscious decision or a CLAUDE.md update to clarify when patch releases merit a changelog entry (e.g., "skip patch releases unless they include a security fix or user-visible behavior change").

Fix this →

---

Issue 2 — #342 Fix entry doesn't use the em-dash pattern

- Fix E2E service tests intermittently hanging due to orphan `moat-*` Docker networks accumulating without cleanup. `Close()` is now bounded so a stuck monitor goroutine can't deadlock teardown, and orphan networks are reaped on startup. ([#342]...)

CLAUDE.md requires: "Fix X — previously, Y happened when Z". This entry uses "due to Y. Z is now done." instead. Suggested rewrite:

Fix E2E service tests intermittently hanging — previously, orphan moat-* Docker networks accumulated without cleanup and a stuck monitor goroutine could deadlock teardown. Close() is now bounded and orphan networks are reaped on startup. ([#342]...)

---

Issue 3 — #336 Fix entry is missing "previously,"

- Fix capability-mismatch error message pointing at a nonexistent command — error paths suggested `moat proxy restart`...

The em-dash is there but "previously" is missing. Suggested rewrite:

Fix capability-mismatch error message pointing at a nonexistent command — previously, error paths suggested moat proxy restart, but the proxy command only registers start, stop, and status...

---

Issue 4 — Path traversal fix buried in a Fixed entry

In the #338 entry:

FileStore.Get() is hardened against path traversal via crafted provider names.

This is a security fix (path traversal via untrusted input) tucked into a functional Fixed entry. Depending on how strictly you want to apply the ### Security heading rule, this may warrant its own Security entry or at minimum a note about whether user action is required. Low severity since provider names come from moat.yaml (operator-controlled), but worth a conscious decision on placement.

---

Minor nit

The Python 3.13/3.14 entry (line 18) is the only Added entry without a trailing period after the PR link. Existing entries are inconsistent throughout the file, so not blocking — but worth noting if you want consistency within this block.

---

[claude]

Claude finished @dpup's task in 1m 33s —— View job

---

Code review: PR #347 (updated)

• Read CHANGELOG.md and CLAUDE.md
• Check entries against style conventions
• Verify PR links and formatting
• Final review summary

---

What changed in this push

The follow-up commit (3df7f7c) updated CLAUDE.md to match the decision to document patch releases — replacing "skip patch releases" with "tracks every released version, including patch releases" and updating "Each minor release" → "Each release". This cleanly resolves the convention inconsistency flagged in the prior review.

---

Remaining issues

Issue 1 — #342 Fix entry still doesn't use the em-dash pattern

CHANGELOG.md:36:

- Fix E2E service tests intermittently hanging due to orphan `moat-*` Docker networks
  accumulating without cleanup. `Close()` is now bounded so a stuck monitor goroutine
  can't deadlock teardown, and orphan networks are reaped on startup. ([#342]...)

CLAUDE.md requires: "Fix X — previously, Y happened when Z". This entry uses "due to Y. Z is now done." Suggested rewrite:

Fix E2E service tests intermittently hanging — previously, orphan moat-* Docker networks accumulated without cleanup and a stuck monitor goroutine could deadlock teardown. Close() is now bounded and orphan networks are reaped on startup. ([#342]...)

Fix this →

---

Issue 2 — #336 Fix entry missing "previously,"

CHANGELOG.md:37:

- Fix capability-mismatch error message pointing at a nonexistent command — error paths
  suggested `moat proxy restart`, but the proxy command only registers...

The em-dash is there but previously, is missing. Suggested rewrite:

Fix capability-mismatch error message pointing at a nonexistent command — previously, error paths suggested moat proxy restart, but the proxy command only registers start, stop, and status. Messages now point at moat proxy stop followed by re-running moat run. ([#336]...)

Fix this →

---

Issue 3 — Path traversal fix placement

CHANGELOG.md:34: The #338 Fixed entry ends with:

...and `FileStore.Get()` is hardened against path traversal via crafted provider names.

This is a security hardening fix tucked into a functional Fixed entry. Since provider names come from moat.yaml (operator-controlled), severity is low — placement in ### Fixed is defensible. But it's worth a conscious call: if it stays in Fixed, consider promoting the path traversal sentence to its own bullet so it's clearly attributed to a separate concern from the auth credential loading fix.

---

Nit — Python entry missing trailing period

CHANGELOG.md:18:

- Python 3.13 and 3.14 added to supported versions; bundled `uv` updated from 0.5.14 to 0.11.6 to support modern `pyproject.toml` features ([#316]...)

No trailing period after the link. Other entries in this block have periods; this one doesn't. Minor inconsistency, not blocking.

---

Overall

The CLAUDE.md update is a clean fix. The changelog content is well-written — factual, active voice, specific. Issues 1–2 above are direct violations of the CLAUDE.md pattern (Fix X — previously, Y); the other two are judgment calls. Otherwise this looks good to merge once those two entry patterns are corrected.