docs(readme): correct three transform claims

[michen00]

What changes, and why

Three claims about what the transform does, each recomputed by running both implementations.

Anchoring (README.md:234, and the same sentence at docs/rust-port-design.md:68). The table said a leading / "Anchors the pattern to the directory the ignore file sits in." Both implementations match an anchored pattern from component 0 of the candidate path as it was given — _pattern_matches sets starts = (0,) over _split_components(raw_path) in unwrap.py, pattern_matches does the same in src/ignore.rs, and both build_ignore_rules read the ignore file's text and never its directory. Demonstrated with the ignore file in a subdirectory:

$ printf '/top.md\n' > docs/.unwrapignore     # top.md and docs/top.md both exist
$ ... --json --ignore-file docs/.unwrapignore top.md docs/top.md
  in scope: ['docs/top.md']

The anchored pattern excluded the top-level file and spared the one sitting beside the ignore file — the reverse of the row. It also had no referent for an anchored --exclude glob, where no ignore file exists. corpus/cli/a-leading-slash-anchors-to-the-root already calls this the root, so the row now agrees with the case that specifies it.

"Two of those are about shape" (README.md:304), under a list of twelve bullets introduced by "Every one of these is left exactly as written". A label row and an inline speaker turn are shape-only too — each keeps its own line while a value wrapped underneath joins onto it:

  **Date:** 2026-09-03                       **Date:** 2026-09-03
  **Status:** a value that was          →    **Status:** a value that was wrapped by hand
  wrapped by hand                            **Owner:** someone
  **Owner:** someone

So four are, and a reader relying on a wrapped **Status:** value surviving verbatim loses its break. A file that reads as a whole transcript is skipped untouched — a different claim, and it stays.

The bare pipe (README.md:308). "blocks unwrapping for that paragraph" — it blocks the line. With two prose lines above such a line and two below:

  alpha wrapped                              alpha wrapped beta wrapped
  beta wrapped                          →    a | b bare pipe
  a | b bare pipe                            gamma wrapped delta wrapped
  gamma wrapped
  delta wrapped

Two breaks removed, where the paragraph reading predicts none. Byte-identical from the Rust binary. The trailing clause in the same sentence ("declining to unwrap a paragraph") moves with it, since a line is what is declined.

Corpus

The corpus is the specification, and both implementations answer to it. Tick what applies.

• This changes no behavior the corpus specifies.
• This changes what gets joined, and a case in corpus/ pins the new behavior. The case was written first and failed first.
• The change makes the tool join more than it did. The section above says what it will not eat.

All three behaviours were already what the corpus pins; only the descriptions were wrong. The remaining finding on this section — that the * row of the same table is the one row corpus/cli/ does not pin, against a sentence claiming every row is — is a corpus change and follows separately.

Checks

• make check passes, or make test does and this touches no Rust.

make tidy, plus unwrap-markdown-prose-py --fail-on-change over both files since tidy skips this repository's own hook. Markdown only.

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

Tip of the day

💡 Did you know, you can add REVIEW.md to your repo root and Qodo follows it on every PR

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[qodo-code-review]

PR Summary by Qodo

Correct documentation for anchoring and unwrap boundaries

📝 Documentation 🕐 Less than 10 minutes

AI Description

• Correct leading-slash anchoring to reference the candidate path root.
• Clarify shape preservation for labels, speaker turns, lists, and blockquotes.
• Document that bare pipes preserve only their containing line.

Diagram

graph TD
  A["Python transform"] -->|matches| C["Verified behavior"] -->|documents| D["README guidance"]
  B["Rust transform"] -->|matches| C
  C -->|aligns| E["Port design"]

Loading

High-Level Assessment

Correcting the documentation to match the behavior shared by both implementations and the existing corpus is the appropriate approach. Changing implementation behavior instead was considered implicitly but would contradict established corpus semantics without providing a functional benefit.

Files changed (2) +4 / -4

Documentation (2) +4 / -4

README.mdCorrect three user-facing transform behavior claims +3/-3

Correct three user-facing transform behavior claims

• Clarifies that leading slashes anchor to the supplied candidate path’s top level. It also documents structural preservation for label rows and speaker turns, and explains that a bare pipe preserves only its line while adjacent prose unwraps independently.

README.md

rust-port-design.mdAlign ignore anchoring design with implemented semantics +1/-1

Align ignore anchoring design with implemented semantics

• Revises the ignore-pattern design description so leading slashes anchor to the candidate path rather than the ignore file’s directory. The explanation also connects this behavior to command-line exclusion globs, which have no backing ignore file.

docs/rust-port-design.md

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.37%. Comparing base (1e9ac89) to head (7cae478).

Additional details and impacted files

@@           Coverage Diff           @@
##             main      #36   +/-   ##
=======================================
  Coverage   87.37%   87.37%           
=======================================
  Files           3        3           
  Lines         689      689           
=======================================
  Hits          602      602           
  Misses         87       87           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

🟢 Approval recommended

The changes are documentation-only corrections that are internally consistent and match the described implementation behavior without altering code or corpus-defined behavior.

Pull request overview

This PR corrects three README/design-document claims to match the transform and ignore semantics already implemented (and already pinned by the corpus), aligning user-facing documentation with observed behavior across both Python and Rust implementations.

Changes:

• Fixes the meaning of a leading / in ignore patterns to reflect anchoring to the top level of the candidate path as provided (not the ignore file’s directory).
• Updates the “shape vs. verbatim line breaks” explanation to include label rows and speaker turns as shape-preserving cases.
• Clarifies that a bare | in running prose blocks joining for the line containing it, with surrounding prose joining separately.

File summaries

File	Description
README.md	Corrects three user-facing behavioral descriptions (anchoring, shape-only cases, bare pipe behavior) to match actual transform behavior.
docs/rust-port-design.md	Mirrors the corrected anchored-/ semantics in the Rust port design narrative for consistency with the implementation and CLI semantics.

Review details

• Files reviewed: 2/2 changed files
• Comments generated: 0
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.