Guard repository size and document history cleanup

[joeVenner]

Summary

• add a tracked-file size guard with a 2 MiB limit
• reject committed app/package artifacts, including .app, .dSYM, .xcarchive, .xcresult, .ipa, .zip, .delta, .dmg, .pkg, .tar.gz, and .tgz paths
• run the guard from the existing lint pipeline
• remove the duplicate root codexbar.png and point the README at docs/codexbar.png
• document repository-size policy and artifact handling

Regression proof

Scripts/test_repository_size.sh verifies that:

• an untracked oversized file is ignored
• an exactly 2 MiB tracked file is accepted
• a 2 MiB + 1 byte tracked file is rejected
• every blocked artifact suffix is rejected
• an artifact-named symlink is rejected before regular-file filtering

Validation

• ./Scripts/check_repository_size.sh — passes across 1,609 tracked entries
• ./Scripts/test_repository_size.sh — passes
• make check — passes (144 documentation links, zero SwiftFormat changes, zero SwiftLint violations)
• autoreview — clean, no actionable findings (0.86 confidence)

Risk

Low. The guard is lint-only and operates on Git's tracked-file index. The main compatibility risk is intentionally blocking future large binaries or packaged artifacts; the documentation explains how to keep generated outputs outside version control.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed July 3, 2026, 11:18 PM ET / 03:18 UTC.

Summary
The PR adds a tracked-file size guard, blocks common release artifacts, wires the guard into lint, removes the duplicate root README image, and documents repository-size cleanup guidance.

Reproducibility: not applicable. this is a repository tooling and documentation cleanup, not a runtime bug report. The relevant behavior is source-verifiable from the proposed scripts and current tracked-tree checks.

Review metrics: 2 noteworthy metrics.

• Diff scope: 7 files changed, +173/-1 plus 1 image removed. The review surface is limited to repository tooling, docs, ignore rules, and README image pathing.
• New check surface: 2 scripts added; 1 lint pipeline call added. The PR changes the make check/CI lint behavior contributors will hit after merge.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🐚 platinum hermit
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• none.

Risk before merge

• [P1] Merging this PR makes the 2 MiB cap and generated-artifact denylist part of local and CI lint, so future legitimate source fixtures or large assets would need an explicit threshold or allowlist change before they can pass make check.

Maintainer options:

1. Accept the new check policy
   Merge as-is if maintainers want make check to fail on tracked files over 2 MiB and common generated artifacts.
2. Adjust the gate first
   Change the threshold or add a narrow allowlist before merge if legitimate source assets or fixtures above 2 MiB are expected.
3. Keep documentation only
   Narrow or close the PR if maintainers want the history-cleanup runbook without adding a local/CI lint gate.

Next step before merge

• [P2] Maintainer review should decide whether the 2 MiB threshold and artifact denylist belong in make check; there is no narrow automated repair needed.

Security
Cleared: The diff adds local shell checks and documentation only; it does not add dependencies, secrets handling, downloads, publishing changes, or third-party execution paths.

Review details

Best possible solution:

Land the guard and documentation if maintainers accept the repository-size policy, while keeping any actual history rewrite as a separate coordinated maintainer operation.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this is a repository tooling and documentation cleanup, not a runtime bug report. The relevant behavior is source-verifiable from the proposed scripts and current tracked-tree checks.

Is this the best way to solve the issue?

Yes, if maintainers accept the policy threshold: the implementation uses the existing lint/check path, tests the guard in a temporary repository, and clearly separates prevention from any maintainer-only history rewrite.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against a9e47e78c11b.

Label changes

Label justifications:

• P3: This is repository hygiene and documentation cleanup, not a user-facing runtime regression.
• merge-risk: 🚨 automation: The diff intentionally adds a new lint gate that can fail future local checks or CI for large tracked files and generated artifacts.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): The PR body reports after-change terminal validation for the guard, regression script, and make check, which is sufficient proof for this repository-tooling change.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body reports after-change terminal validation for the guard, regression script, and make check, which is sufficient proof for this repository-tooling change.

Evidence reviewed

What I checked:

• Repository policy read: AGENTS.md was present and read fully; its guidance about generated artifacts, scripts, make check, and avoiding unnecessary live validation applies to this tooling review. (AGENTS.md:1, a9e47e78c11b)
• PR diff surface: The PR changes seven files: ignore rules, README image path, two new shell scripts, lint integration, duplicate image removal, and repository-size documentation. (Scripts/lint.sh:48, 1f204c8add4f)
• Guard behavior: The proposed guard iterates git ls-files -z, rejects tracked generated-artifact paths, and fails files larger than 2 MiB. (Scripts/check_repository_size.sh:11, 1f204c8add4f)
• Regression harness: The added test script builds a temporary repository and verifies untracked oversized files, boundary-size tracked files, oversized tracked files, blocked artifact suffixes, and an artifact-named symlink. (Scripts/test_repository_size.sh:14, 1f204c8add4f)
• Current-main gap: Current main has the existing lint pipeline but no check_repository_size or repository-size documentation, so the PR is not obsolete on main. (Scripts/lint.sh:77, a9e47e78c11b)
• Current-tree compatibility: Current main's largest tracked files are below 2 MiB, and no tracked generated app or release artifact matched the proposed denylist. (a9e47e78c11b)

Likely related people:

• steipete: Current-main blame attributes the existing lint pipeline, ignore-rule block, and README image area to 913b1a6, and steipete authored the PR branch hardening commit. (role: recent area contributor; confidence: high; commits: 913b1a6412b5, 1f204c8add4f; files: Scripts/lint.sh, .gitignore, README.md)
• Yuxin-Qiao: Commit 5e38f6b reshaped the Linux lint runner and Scripts/lint.sh, the same check surface this PR extends. (role: recent CI/lint contributor; confidence: medium; commits: 5e38f6beb98d; files: Scripts/lint.sh, .github/workflows/ci.yml)
• kiranmagic7: Commit 2c0f83a added generated-index verification to the lint pipeline, adjacent to this PR's new repository-size check. (role: recent lint-area contributor; confidence: medium; commits: 2c0f83a3b73a; files: Scripts/lint.sh, Scripts/generate-llms.mjs)
• Brandon Charleson: Commit 8e1ef17 removed accidentally committed app bundles and improved .gitignore, directly adjacent to the artifact-prevention policy in this PR. (role: adjacent artifact-prevention contributor; confidence: medium; commits: 8e1ef17e681f; files: .gitignore)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

[steipete]

The hardened follow-up landed in #1875 as f6732bd.

It preserves this PR's intent while validating immutable staged blob OIDs from the Git index, covering empty indexes, submodules, symlinks, staged-vs-working-tree divergence, exact size boundaries, newline paths, and the full release-artifact matrix. Contributor credit is preserved in the changelog and squash commit. Thanks @joeVenner!