Skip to content

Split the Over-Length Sentences in the Docs, Catalog READMEs, and HISTORY - #3599

Merged
ptr727 merged 13 commits into
developfrom
feature/3531-md-docs-catalog
Oct 29, 2026
Merged

ptr727 merged 13 commits into
developfrom
feature/3531-md-docs-catalog

Conversation

@ptr727

@ptr727 ptr727 commented Oct 29, 2026

Copy link
Copy Markdown
Owner

What was swept

Slice H of the sentence-length sweep: 16 Markdown files under docs/, catalog/, and HISTORY.md, plus the one residue sentence in TODO.md (and its verbatim twin in docs/peer-messaging.md, split identically). Each over-length sentence was split or tightened with its meaning unchanged. No dated fact, version, number, attribution, heading, link target, or code changed.

Hits before and after (prose_lint.py --check sentence-length): 125 before, 0 after, across the 17 files. --diff origin/develop reports nothing new.

Notes:

  • docs/pr-reviewer-evaluation.md Status block: the five backslash-joined field lines read as one 38-word sentence to the gate, so they became a bulleted list with identical wording.
  • Copies: the husky and pre-commit snippet READMEs share sentences and were split identically. GOVERNANCE.md already carries the split form of the markdownlint-severity sentence and the husky/pre-commit snippet description, and the new wording agrees with it. No copies exist in code comments, docstrings, tests, or JSON strings.

Five recorded local review passes at the frontier tier; the last found no drift.

Copies left for the comment sweep

None.

Part of #3531

🤖 Generated with Claude Code

ptr727 and others added 5 commits October 28, 2026 22:02
…TORY

Part of #3531

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Part of #3531

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Part of #3531

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Part of #3531

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Part of #3531

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Copilot AI lite review requested due to automatic review settings October 29, 2026 05:09
@coderabbitai

coderabbitai Bot commented Oct 29, 2026 •

Copy link
Copy Markdown

Important

  • 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

Run configuration
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Two active documentation issues remain: a malformed pin-freshness sentence in the Husky README and an incomplete opening fragment in the reviewer-evaluation guide.

2 open issues
What changed in this PR

This documentation-only pull request completes a sentence-length cleanup across 17 Markdown files in docs/, catalog/, HISTORY.md, and TODO.md.

Changes:

  • Splits or tightens over-length prose while preserving technical meaning, links, identifiers, and documented behavior.
  • Converts the reviewer evaluation status block into a Markdown list.
  • Keeps duplicated Husky and pre-commit documentation aligned.
  • Three nit findings remain: malformed wording in the Husky README (3 votes), an incomplete opening in docs/content-import.md (1 vote), and an opening fragment in docs/pr-reviewer-evaluation.md (3 votes).
File Summary
TODO.md Splits the peer-messaging boundary sentence.
HISTORY.md Splits the Version 2.0 release description.
docs/​token-efficiency-plan.md Splits long planning and phase descriptions.
docs/​token-cost.md Splits measurement and cost-analysis prose.
docs/​ssh-signing.md Splits SSH signing guidance.
docs/​pre-commit-hooks-rollout.md Splits hook rollout and maintenance guidance.
docs/​pr-reviewer-evaluation.md Formats status fields as a list and splits evaluation prose; one opening fragment remains.
docs/​peer-messaging.md Splits peer-messaging rules and rationale.
docs/​homelab-runner-selection-plan.md Splits runner authorization and verification requirements.
docs/​eol-lf-rollout.md Splits line-ending rollout guidance.
docs/​devcontainer.md Splits devcontainer setup and troubleshooting prose.
docs/​content-import.md Splits content-import verification guidance; the opening remains an incomplete sentence.
catalog/​snippets/​workflows/​README.md Splits workflow snippet lifecycle guidance.
catalog/​snippets/​vscode/​README.md Splits workspace composition guidance.
catalog/​snippets/​pre-commit/​README.md Splits pre-commit configuration guidance.
catalog/​snippets/​husky/​README.md Splits Husky hook documentation; one pin sentence is malformed.
catalog/​README.md Splits catalog snippet descriptions.

Review effort: Lite

Comment thread catalog/snippets/husky/README.md Resolved
Comment thread docs/pr-reviewer-evaluation.md Resolved
ptr727 and others added 7 commits October 28, 2026 22:14
## What was swept

Split over-length sentences (sentence-length gate, 25 words) without
changing meaning in `spec/readme-structure.md`, `spec/section-model.md`,
`spec/fidelity-model.md`, `spec/type-model.md`, `spec/scope-model.md`,
`repo-config/README.md`, `docs/repo-config.md`, plus residue sentences
in `OPERATIONS.md`, `scripts/README.md`, and `STANDUP.md`.

Hits before and after: readme-structure 48 to 0, section-model 26 to 0,
fidelity-model 16 to 0, type-model 13 to 0, scope-model 5 to 0,
repo-config/README 26 to 0, docs/repo-config 14 to 0, OPERATIONS 1 to 0,
scripts/README 2 to 0, STANDUP 1 to 0.

Recorded local strict review: four frontier passes, the last with no new
drift.

## Deviations from the orchestrator wording

- `STANDUP.md`: the ruled sentence was 26 words, one over the gate. It
reads "A **host** misconfiguration shows as a missing `--global` value,
..." instead of "Each of these is a **host** misconfiguration: ...".
- `scripts/README.md` "Layering is tighten-only": adopts STANDUP's
wording with "A local entry", because a bare "An entry" there would
widen the restriction to the hub's own file.

## Copies left for the comment sweep

None identical. `repo-config/configure.sh:33` and
`spec/third-party-tools.json`, `spec/readme-sections.json` carry related
but differently worded sentences.

Part of #3531

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
…TORY

Part of #3531

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Part of #3531

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Part of #3531

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Part of #3531

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Part of #3531

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Part of #3531

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@codecov

codecov Bot commented Oct 29, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (develop@c59f7db). Learn more about missing BASE report.

Additional details and impacted files
@@            Coverage Diff             @@
##             develop    #3599   +/-   ##
==========================================
  Coverage           ?   81.60%           
==========================================
  Files              ?       26           
  Lines              ?     9070           
  Branches           ?        0           
==========================================
  Hits               ?     7402           
  Misses             ?     1668           
  Partials           ?        0           
Flag Coverage Δ
python-3.13 81.60% <ø> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ 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.

…to feature/3531-md-docs-catalog

# Conflicts:
#	catalog/snippets/husky/README.md
@ptr727

ptr727 commented Oct 29, 2026

Copy link
Copy Markdown
Owner Author

Answering the Copilot overview nit on docs/content-import.md ("incomplete opening", 1 vote): the opening "What an agent captures, and how it verifies the capture." is a topic-line fragment carried over from the original, whose own opening was a fragment ("What an agent captures, and how it verifies the capture, when a repo's initial content comes from ..."). The split keeps that fragment form and moves the "when" condition into a full sentence ("This applies when ..."). Declined: converting it to a clause would add a verb the original did not have.

@ptr727

ptr727 commented Oct 29, 2026

Copy link
Copy Markdown
Owner Author

A recorded local strict-review pass covers head b38e084cc672cc7596af1c3002e981efc9f619a8, the content this pull request carries at that commit against develop, and it recorded 0 findings.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues remain, and the documentation-only changes preserve existing meaning while completing the intended sentence cleanup across the affected Markdown files.

No open issues 🎉

2 resolved since last review

Review effort: Lite

@ptr727
ptr727 merged commit 0d4e6f1 into develop Oct 29, 2026
14 checks passed
@ptr727
ptr727 deleted the feature/3531-md-docs-catalog branch October 29, 2026 05:29
ptr727 added a commit that referenced this pull request Oct 29, 2026
…down (#3600)

## Summary

Promotes `develop` to `main`, carrying the sentence-length splits of the
hub-only Markdown:

- #3594: splits them in scripts/README.md.
- #3593: splits them in STANDUP, AUDIT, RESYNC, and OPERATIONS.
- #3591: splits them in TODO.md.
- #3596: splits them in the agent-safety Markdown.
- #3595: splits them in the host setup docs.
- #3592: splits them in reusable-workflows and fleet-map.
- #3598: splits them in the remaining host setup sentences.
- #3597: splits them in the spec and repo-config docs.
- #3599: splits them in the docs, catalog READMEs, and HISTORY.

This is part of #3531, which stays open.

🤖 Generated with [Claude Code](https://claude.com/claude-code)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants