v1.7.1

Highlights

v1.7.1 closes every follow-up item the v1.7.0 release notes flagged for a patch release, plus six rounds of automated-review hardening. No new commands, no breaking changes — quality + concurrency-safety + scanner-precision pass.

Lock-scope reduction

• Writer decorators short-circuit <cmd> -h / <cmd> --help (anywhere in argv) to print usage and return 0 without acquiring the activities / files lock. No more lockfile materialization on --help against a fresh data home.
• cmd_create inline-refactored: stdin read, schema-block validation, fuzzy-similarity scan, indent detection, and YAML rendering all happen OUTSIDE the lock. The lock now wraps only the re-load + id-uniqueness recheck + write.
• cmd_file_rehash inline-refactored: SHA-256 hashing runs OUTSIDE the lock. The lock wraps only the apply-deltas + save phase. A multi-gigabyte --all rehash no longer blocks concurrent file-* writers.

Atomic writes

• New shared atomic_replace helper: temp + os.replace with mode-bit preservation (chmod 600 survives round-trips), orphan-tmp cleanup on failure (including KeyboardInterrupt), symlink target honoring (the link is preserved instead of destroyed), and symlink-target-parent mkdir for not-yet-mounted destinations.
• write_lines, save_files, and cmd_create's bootstrap all route through it.
• write_lock sidecar anchored to the resolved symlink target so two aliases to the same file share one mutex.

Merge polish

• Dry-run preview total now equals the post-confirm ledger refs= count: preview counts steps 1, 1b, 2, and 5 instead of just step 1.
• Description-shape gates (missing / empty / inline / folded >) hoisted to run BEFORE the dry-run return so the preview accurately reflects whether --confirm will commit.
• Folded-scalar (description: >) targets are rejected when --append-sources is on (YAML would fold the appended bodies into one paragraph). Provenance-only is still permitted.
• opt_out_advice joiner is and (not or) when both flags trigger the shape check.

cmd_file_rehash correctness

• Phase 2 captures (id, path_snapshot, sha256) so phase 3 can verify the record's path didn't change underneath us via a concurrent file-move.
• Empty / whitespace ids and empty / non-string paths are filtered with clear notices.
• TOCTOU mid-hash (FileNotFoundError / OSError) is trapped; the rid lands in missing and the rehash continues for everything else.
• --help (anywhere in argv) short-circuits to usage instead of falling through to id-lookup.
• Concurrent file-add / file-delete between phases produce added_during_hash / removed_during_hash / scope_id_vanished notices.

Dangling-ref scanner

• _HISTORICAL_PHRASES_RE regex tightened: consolidat(?:e|es|ed|ing)\s+from and consolidat...\s+(?:into|under) with list-continuation lookahead; merged\s+from and merged\s+into with list-continuation lookahead; originally\s+(?:tracked|...stored as|...) with completers; named\s+as (not bare named); was named / old id / former id dropped.
• Backtick-pair scoping (vs raw rfind) so an unmatched stray backtick doesn't misroute the clause boundary.
• Multi-line continuation lists handled (\r\n in the strip set).
• Sentence-break lookback requires 3+ alphabetic chars before the period AND an uppercase letter starting the next word; decimals, abbreviations, and version numbers don't false-trigger.
• Semicolon recognized as a list-continuation separator.

--label UX

• Accepts the equals-form --label=foo.
• Rejects duplicate --label flags.
• Rejects flag-shaped values (--label --dry-run typo no longer silently swallows the next flag).
• Rejects trailing --label with no value.

Test plan

• 30+ new tests cover the new behaviors
• Full pytest suite green on 3.10 / 3.11 / 3.12
• Six rounds of automated review on PR #20

Upgrade notes

No breaking changes. Existing entries, schemas, and ledger files are forward-compatible.

Known issues (v1.7.2 candidates)

• --label=--dry-run (equals-form) bypasses the flag-shape value guard; the space-form is still guarded. Rare typo.
• description : (space before colon) raises IndexError in the merge dry-run shape gate. Rare hand-edit pattern.
• A 0-byte pre-existing activities.yaml (e.g. touch'd but never written) produces an unparseable root-list file on first cmd_create. Rare bootstrap pattern; pre-existing pre-PR.

Review trajectory

HIGHs found per review round on PR #20 = 2, 1, 2, 1, 2, 4. The round-6 cluster was mostly trivial edge cases plus one data-loss bug (write_lock symlink alias mutex). The data-loss bug is fixed; the rare-edge bugs are documented above. Review loop paused per ~/.claude/methodology/handling_claude_pr_reviews.md's symmetric-gap-chasing guidance.