docs: weekly review 2026-07-09#137
Open
vasylenko wants to merge 1 commit into
Open
Conversation
The entry stated 'No way to confirm Bear processed a URL action' but OCC polling has partially addressed this for writes that bump Z_OPT. The OCC section already notes the partial lift; this brings the Intentional Exclusions entry in sync with it.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Owner
Author
✅ Snyk checks have passed. No issues have been found so far.
💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse. |
|
Contributor
There was a problem hiding this comment.
Pull request overview
Updates maintainer documentation to reflect the current “write verification” guarantees after the introduction of OCC polling, aligning the “Intentional Exclusions” section with the existing OCC documentation in the same spec.
Changes:
- Update
docs/dev/SPECIFICATION.md“Intentional Exclusions → Write verification” to describe the partial lift provided by OCC polling. - Clarify remaining limitations (unverified write paths) and add an internal cross-reference to the OCC “Inform” section.
| - **Encrypted notes**: Bear encrypts content in the DB. Excluded from all queries. | ||
| - **Per-tag pinning**: Bear's URL scheme supports `pin=yes` for global pinning but has no action for pinning within a specific tag. | ||
| - **Write verification**: No way to confirm Bear processed a URL action. Exit code 0 from `open` only means macOS accepted the URL, not that Bear acted on it. | ||
| - **Write verification** _(partially lifted)_: For writes that bump `ZSFNOTE.Z_OPT`, OCC polling confirms the write landed — see _Safety Gates → Optimistic Concurrency Control → Inform half_. The constraint persists for writes that do not bump `Z_OPT` (global tag operations: `bear-rename-tag`, `bear-delete-tag`): exit code 0 from `open` only means macOS accepted the URL, not that Bear acted on it. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Reviewed all user-facing and maintainer-facing documentation against the current codebase (v3.0.1 + Unreleased OCC work). Found one factual inaccuracy: the "Intentional Exclusions" section of
SPECIFICATION.mdcontained a stale "Write verification" entry that no longer accurately described the system — OCC polling, which ships in the Unreleased branch and is already documented in the OCC section of the same file, partially lifts that constraint for writes that bumpZ_OPT.Changes
docs/dev/SPECIFICATION.md— "Write verification" Intentional Exclusion is stale → updated to reflect the partial lift: The entry read "No way to confirm Bear processed a URL action. Exit code 0 fromopenonly means macOS accepted the URL, not that Bear acted on it." The OCC section of the same document already notes "Constraint partially lifted: write verification" and cross-references this entry, but the entry itself was never updated. Fixed: the entry now states the constraint is partially lifted for writes that bumpZ_OPT, names the remaining scope (global tag ops), and links to the OCC section.No Issues Found
The following checklist areas were checked and found accurate:
REVISION_POLL_TARGET_MS,REVISION_POLL_INTERVAL_MS,POLL_TIMEOUT_MS,busy_timeout), and cross-references verified against the source.UI_DEBUG_TOGGLE,UI_ENABLE_NEW_NOTE_CONVENTION,UI_ENABLE_CONTENT_REPLACEMENTconsistent across README, NPM.md, manifest.json, config.ts, SPECIFICATION.md, and website components.open -g, schema discovery at runtime, and test constraints all accurate.Generated by Claude Code