docs(changelog): lead with user-facing highlights

[steipete]

Summary

Rewrite only the Unreleased section of CHANGELOG.md for readers deciding whether and how to upgrade:

• lead with five user-facing highlights covering file safety, opt-in bounded temp cleanup, archive safety, queue durability, and lock/deadline reliability
• put compatibility and upgrade actions immediately after the highlights, including claim-before-acknowledgement, the new indeterminate cleanup result, canonical pre-strip filters, and stricter limits/error handling
• group the detailed notes by user impact instead of reverse commit order, preserving the POSIX one-entry cleanup residual, compatible fallback, native capability requirements, and weaker opt-in FUSE contract
• leave all dated release sections byte-identical

Version recommendation

Recommend 0.7.0, not 0.6.1, for the eventual release. This batch includes new public options/types and consumer-visible behavior changes rather than only backwards-compatible fixes. A minor-version boundary gives pre-1.0 consumers an intentional upgrade point. This PR does not change package versions, date the Unreleased section, create tags, release, or publish anything.

Verification

• Complete CI=1 pnpm check: 6,086 tests passed, 76 skipped; lint, build, documentation examples, package and public-API validation passed.
• Asserted that every dated release section, including 0.6.0, is byte-identical to main.
• Exercised the real release-note extractor against isolated temporary 0.6.1 and 0.7.0 fixtures; both preserve the complete rewritten highlights, upgrade notes, and details without including the next release.
• git diff --check passes; changed-file scope is CHANGELOG.md only.

After-change generator proof

Exact-head terminal capture from running the real scripts/release-notes.mjs on an isolated temporary copy of the changed changelog. Only the temporary fixture renames Unreleased to a dated 0.7.0 heading so the existing extractor can select it; the repository still has Unreleased and package version 0.6.0. The generated Markdown was compared byte-for-byte with the entire rewritten Unreleased body, not merely searched for headings.

{
  "proof": "changelog-release-note-generator",
  "head": "6af017339b8033bbc2b1fd317ccb564c957ede27",
  "fixture": "temporary dated 0.7.0 section; repository remains Unreleased",
  "sectionsInOrder": [
    "Highlights",
    "Compatibility and upgrade notes",
    "File safety and temp cleanup",
    "Archive extraction and reads",
    "Durable queues, stores, and locks"
  ],
  "highlightCount": 5,
  "completeUnreleasedBodyExtracted": true,
  "historicalReleasesByteIdentical": true,
  "packageVersionUnchanged": "0.6.0",
  "generatedNotesSha256": "147eaadf28a96fcfe7406b0a402519b89a748c2443e5d2a4da1a6fafbf676899"
}

Actual beginning of the generated Markdown:

### Highlights

- **Safer reads and writes:** extend exact identity checks and retained-descriptor publication to reject substituted inputs and detect publication mismatches, including rounded-equal Windows file IDs.
- **Opt into bounded temp cleanup:** `cleanupSafety: "require-bounded"` prevents recursive traversal of substituted workspace trees, while the compatible default remains available without native support. See the [cleanup guarantees and POSIX limits](https://fs-safe.io/temp.html#private-temp-workspaces).
- **Harden untrusted archive handling:** reject hidden path aliases, ambiguous TAR metadata, corrupt gzip streams, and excessive decoded data before publication; align filtering and entry reads across JavaScript and native backends.
- **Preserve queued work and durability:** generation-bound claims protect newer same-ID entries from acknowledgement or quarantine, and queue transitions and synchronous store writes sync their filesystem changes.
- **Make lock handoffs and timeouts reliable:** recover from ownership records unlinked during contention, surface release failures, and finish in-flight archive publication or rollback before returning a timeout.

The real generated artifact is the relevant changed behavior for this documentation PR. Runtime code, package metadata, dated release notes, and publication state are unchanged. Exact-head CI and coverage passed on all configured platforms. Codex autoreview is scoped-clean with no actionable findings.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

[steipete]

@clawsweeper automerge

Special instructions:
Review and land exact head 6af017339b8033bbc2b1fd317ccb564c957ede27 after its normal exact-head checks pass. This is CHANGELOG.md only: rewrite Unreleased with five user-facing highlights, prioritize upgrade actions and user impact, and group detailed notes. All dated release sections remain byte-identical.

Verify preservation of material security qualifiers: compatible versus require-bounded cleanup, the POSIX leaf/empty-directory residual, native-only codec support, FUSE's weaker cooperating-writer contract, canonical pre-strip filter names, separate TAR decoded/manifest/output budgets, and queue claim/durability requirements. 0.7.0 is a recommendation, not a release instruction: keep Unreleased and all package versions/tags unchanged; do not release or publish.

Local proof: complete pnpm check passed (6,086 tests; 76 skipped), historical section byte comparisons passed, and the real release-note extractor preserved the full rewritten body in isolated temporary dated-version fixtures. Codex autoreview found no actionable P0/P1 findings. This is a prose edit with no runtime change; no new runtime or screenshot proof is warranted. Stop rather than broadening into unrelated implementation or dependency work.

[clawsweeper]

🦞✅
ClawSweeper merged this PR after the passing review.

Source: clawsweeper[bot]
Feedback: structured ClawSweeper verdict: pass (sha=6af017339b8033bbc2b1fd317ccb564c957ede27)
Merge status: merged by ClawSweeper automerge
Merged at: 2026-08-31T15:39:11Z
Merge commit: b83b339c0cb6

What merged:

• The PR reorganizes the Unreleased changelog into user-facing highlights, upgrade guidance, and topic-based details while leaving dated releases unchanged.

Automerge notes:

• No ClawSweeper repair was needed after automerge opt-in.

The automerge loop is complete.

Automerge progress:

• 2026-08-31 15:13:11 UTC active review reused 6af017339b80 (waiting)

• 2026-08-31 15:17:23 UTC review queued 6af017339b80 (queued)

• 2026-08-31 15:33:00 UTC review queued 6af017339b80 (queued)

• 2026-08-31 15:37:44 UTC review passed 6af017339b80 (structured ClawSweeper verdict: pass (sha=6af017339b8033bbc2b1fd317ccb564c957ed...)

• 2026-08-31 15:39:13 UTC merged 6af017339b80 (merged by ClawSweeper automerge)

[clawsweeper]

Codex review: passed. Reviewed August 31, 2026, 11:36 AM ET / 15:36 UTC.

ClawSweeper review

What this changes

The PR reorganizes the Unreleased changelog into user-facing highlights, upgrade guidance, and topic-based details while leaving dated releases unchanged.

Merge readiness

⚠️ Ready for maintainer review - 1 item remains

This focused documentation PR remains necessary because current main still has the prior Unreleased organization. The exact-head diff is accurate, preserves every dated release section, and has sufficient release-note extraction evidence; no actionable findings remain.

Priority: P3
Reviewed head: 6af017339b8033bbc2b1fd317ccb564c957ede27

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A narrowly scoped, source-aligned documentation rewrite with direct generated-artifact evidence and no correctness findings.
Proof confidence	🐚 platinum hermit (4/6)	Sufficient (live_output): The changed production-facing artifact is the root changelog consumed by the release-note extractor; the exact-head PR body includes generated output, ordered sections, and a complete-body comparison from that extractor after applying the rewrite.
Patch quality	🦞 diamond lobster (5/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Verified	Sufficient (live_output): The changed production-facing artifact is the root changelog consumed by the release-note extractor; the exact-head PR body includes generated output, ordered sections, and a complete-body comparison from that extractor after applying the rewrite.
Evidence reviewed	5 items	Exact introduced scope: The verified merge-base-to-head diff changes only the Unreleased section; the next dated section, 0.6.0, remains immediately after it and is untouched. Release-note consumer: The extractor validates a dated semver heading then emits the complete section body through the next release heading, so the PR's added subheadings remain part of the generated notes. Current contract alignment: The new upgrade notes agree with current documentation for compatible versus require-bounded cleanup, claimed durable-queue acknowledgement, and canonical pre-strip archive filters.
Findings	None	None.
Security	None	None.

How this fits together

The Unreleased changelog section records pending package changes for upgrade decisions. The release-note extractor selects a dated changelog section and emits its body for release consumers.

flowchart LR
A[Pending changelog] --> B[Release-note extractor]
B --> C[Selected release section]
C --> D[Published release notes]

Loading

Before merge

• Complete next step (P2) - No repair work is indicated: the exact head has no actionable findings and can proceed through normal automerge gates.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Changelog scope	1 file affected; 46 added, 28 removed	The patch is limited to reorganizing pending release documentation and does not alter package code, versions, or dated releases.

Technical review

Best possible solution:

Land the focused Unreleased rewrite so release readers see the upgrade actions before the detailed security and operational notes.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this is a documentation-only change, and the relevant behavior is release-note extraction rather than a reported product defect.

Is this the best way to solve the issue?

Yes. Reorganizing the existing Unreleased content is the narrowest maintainable way to foreground upgrade actions, and the extractor accepts the resulting section structure.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against a80d8f64d939.

Labels

Label changes:

• add proof: sufficient: Contributor real behavior proof is sufficient. The changed production-facing artifact is the root changelog consumed by the release-note extractor; the exact-head PR body includes generated output, ordered sections, and a complete-body comparison from that extractor after applying the rewrite.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🦞 diamond lobster.
• add status: 🚀 automerge armed: This PR is in ClawSweeper's automerge lane. Sufficient (live_output): The changed production-facing artifact is the root changelog consumed by the release-note extractor; the exact-head PR body includes generated output, ordered sections, and a complete-body comparison from that extractor after applying the rewrite.
• remove rating: 🦪 silver shellfish: Current PR rating is rating: 🐚 platinum hermit, so this older rating label is no longer current.

Label justifications:

• P3: This is a low-risk documentation and release-note readability improvement.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🦞 diamond lobster.
• status: 🚀 automerge armed: This PR is in ClawSweeper's automerge lane. Sufficient (live_output): The changed production-facing artifact is the root changelog consumed by the release-note extractor; the exact-head PR body includes generated output, ordered sections, and a complete-body comparison from that extractor after applying the rewrite.
• proof: sufficient: Contributor real behavior proof is sufficient. The changed production-facing artifact is the root changelog consumed by the release-note extractor; the exact-head PR body includes generated output, ordered sections, and a complete-body comparison from that extractor after applying the rewrite.

Evidence

What I checked:

• Exact introduced scope: The verified merge-base-to-head diff changes only the Unreleased section; the next dated section, 0.6.0, remains immediately after it and is untouched. (CHANGELOG.md:5, 6af017339b80)
• Release-note consumer: The extractor validates a dated semver heading then emits the complete section body through the next release heading, so the PR's added subheadings remain part of the generated notes. (scripts/release-notes.mjs:10, 6af017339b80)
• Current contract alignment: The new upgrade notes agree with current documentation for compatible versus require-bounded cleanup, claimed durable-queue acknowledgement, and canonical pre-strip archive filters. (docs/temp.md:67, 6af017339b80)
• After-change artifact proof: The PR body supplies exact-head release-note-generator output with the five new sections in order and records a complete-body byte comparison; this directly exercises the changed documentation artifact. (6af017339b80)
• Area history: Recent mainline changelog work since v0.6 includes the lock, temp-cleanup, archive, queue, limit, and read changes summarized here, all attributed to Peter Steinberger. (CHANGELOG.md:3, a80d8f64d939)

Likely related people:

• steipete: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

History

Review history (2 earlier review cycles)

• reviewed 2026-08-31T15:14:29.381Z sha 6af0173 :: needs real behavior proof before merge. :: none
• reviewed 2026-08-31T15:20:42.771Z sha 6af0173 :: needs real behavior proof before merge. :: none

[clawsweeper]

🦞✅
ClawSweeper is pausing this repair loop for human review.

Source: clawsweeper[bot]
Reason: - [ ] Add real behavior proof - Needs stronger real behavior proof before merge: The production-facing artifact changed is root CHANGELOG.md, whose dated sections are consumed by the release-note extractor. The PR d... (sha=6af017339b8033bbc2b1fd317ccb564c957ede27)

Why human review is needed:
ClawSweeper found a blocker that should be resolved or accepted by a maintainer before the repair or automerge loop continues.

What the maintainer can do as a next step:
If the maintainer accepts the current risk and wants ClawSweeper to continue merge gates, comment @clawsweeper approve. If more work is needed, resolve the blocker first, then comment @clawsweeper automerge to re-review and continue. If automation should stay paused, leave clawsweeper:human-review in place or comment @clawsweeper stop.

I added clawsweeper:human-review and left the final call with a maintainer.

[steipete]

@clawsweeper automerge

Special instructions:
Re-review exact head 6af017339b8033bbc2b1fd317ccb564c957ede27 with the updated main PR body. It now contains actual after-change terminal output from the production release-note generator, the generated Highlights Markdown, ordered section list, complete-body byte comparison, SHA-256 of the generated notes, and historical-release preservation proof. The temporary fixture only supplies the dated heading required by the generator; the repository remains Unreleased at package version 0.6.0.

This is inspectable real generated-artifact proof for the changed documentation surface, not a claim about new runtime behavior. CI and coverage are now fully green on this unchanged head. Confirm the content/qualifiers remain accurate, accept the generator evidence for this docs-only edit, and land the PR through normal gates. Do not modify runtime code, bump any version, tag, release, or publish.

[steipete]

Landed as b83b339c0cb6871ba1d14c5e1b270a8ce250a037 from exact reviewed head 6af017339b8033bbc2b1fd317ccb564c957ede27.

Verified the merged commit changes only CHANGELOG.md and matches the reviewed changelog byte-for-byte. Every dated release section is unchanged. Local CI=1 pnpm check passed (6,086 tests; 76 skipped), git diff --check passed, and the real release-note generator retained the complete rewritten highlights, upgrade notes, and details in isolated dated fixtures. Exact-head CI and coverage passed on all configured platforms. Codex autoreview and ClawSweeper review found no actionable issues; the initial documentation proof-policy blocker cleared after adding actual generator output to the PR body.

The task worktree is clean on synchronized main. The unrelated user checkout was preserved. Recommend 0.7.0 for the eventual API/behavior upgrade; no version bump, tag, release, or package publication was performed.