docs(corpus): state the CLI tier symlink rule

[michen00]

What changes, and why

corpus/cli/README.md is what a second harness gets written from, so a rule it omits is a rule the second harness invents.

The symlink rule was omitted. The reference harness copies tree/ with symlinks=True and snapshots a symlink as its target string, and _snapshot's own docstring gives the reason: "A regular file maps to its bytes. A symlink maps to its target string… through one would compare a symlink against a regular copy of its target and call them equal. That is precisely the rewrite the symlink case exists" to catch. The obvious implementation — read through the link — is the wrong one, and the tier ships a case that depends on the answer. So the rule now sits beside the others in "The rules that make it unambiguous", which is the section whose stated purpose is exactly this: "each of these is a question the format would otherwise leave to whoever writes the second harness."

The program name was stale. The section on --help named unwrap-markdown-prose as the Python program. There is no such console script:

$ grep -A2 'project.scripts' pyproject.toml
unwrap-markdown-prose-py = 'markdown_prose_hooks.unwrap:main'
$ ls .venv/bin | grep unwrap
unwrap-markdown-prose-py

And the parse-error claim was true of one implementation. "Usage goes to stdout on --help and to stderr on a parse error" — the Python prints the diagnostic and the usage block; the Rust prints the diagnostic alone:

$ unwrap-markdown-prose-rs --nope z.md
error: unrecognized arguments: --nope

That difference is itself part of why the tier does not compare stderr, so the sentence now says which half is which rather than describing one implementation as though it were both.

Note

This file sits inside corpus/cli/, which .unwrapignore excludes as a subtree and .pre-commit-config.yaml excludes with ^corpus/[^/]+/, so no tidying hook reaches it. The new rule was written as a single line by hand to match the file's existing style.

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.

Documentation of the tier's format. No case, answer key or harness changes — the symlink rule describes what the harness already does.

Checks

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

make tidy. One Markdown file, no Rust and no Python.

[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

Document CLI tier symlink and usage rules

📝 Documentation 🕐 Less than 10 minutes

AI Description

• Documents symlink identity checks to prevent dereferenced files passing corpus comparisons.
• Corrects the Python console script name in help-message guidance.
• Clarifies implementation-specific parse-error output and stderr exclusions.

Diagram

graph TD
  A["CLI tier spec"] -->|defines| B["Harness implementation"] -->|copies| C["Preserved symlinks"] -->|snapshots| D["Target strings"] -->|compares| E["Expected tree"]

Loading

High-Level Assessment

Documenting the existing behavior in the corpus format specification is the appropriate approach because independent harness authors rely on this file. Leaving the rule only in the reference harness was considered but would not prevent other implementations from incorrectly dereferencing symlinks.

Files changed (1) +3 / -1

Documentation (1) +3 / -1

README.mdClarify symlink comparisons and implementation-specific usage output +3/-1

Clarify symlink comparisons and implementation-specific usage output

• Documents that harnesses must preserve symlinks and compare their target strings rather than dereferenced bytes. Corrects the Python executable name and distinguishes Python and Rust parse-error usage behavior while reaffirming that stderr is not compared.

corpus/cli/README.md

[codecov-commenter]

Codecov Report

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

Additional details and impacted files

@@           Coverage Diff           @@
##             main      #44   +/-   ##
=======================================
  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 change is documentation-only and correct in substance; the only feedback is a minor punctuation consistency fix with an inline suggestion.

Pull request overview

This PR updates the CLI corpus documentation (corpus/cli/README.md) to make the CLI-tier rules unambiguous for anyone implementing an independent harness, specifically capturing the symlink comparison behavior and clarifying implementation differences in help/parse-error output.

Changes:

• Document that expected/ symlinks are asserted as symlinks (by target string), not compared via their dereferenced file contents.
• Update the documented Python CLI program name and clarify that parse errors differ between Python and Rust regarding whether usage text is also printed.

File summaries

File	Description
corpus/cli/README.md	Adds the missing symlink rule and clarifies CLI output expectations/differences to prevent harness drift.

Review details

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

---

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