sneak/sfdupes
1
0
Fork 0
Code Issues 23 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

README: remove the AI-tooling line, add the required Entrypoints section, fix stale Build text #21

New Issue
Closed
opened 2026-08-09 03:47:04 +02:00 by clawbot · 1 comment
clawbot commented 2026-08-09 03:47:04 +02:00
Collaborator
Copy Link
Copy Source

Several independent README defects, all docs-only, all worth one pass.

1. AI-tooling attribution. README.md:19-20 reads "This tool was created by @sneak to scratch an itch, using Claude Code/Fable." That naming is not wanted anywhere in this repo's output. Delete the sentence; the Description paragraph above it already carries authorship and licence. This is the only such reference in the tree — the commit history is clean.

2. The required Entrypoints section is missing. House policy requires a README Entrypoints section that opens by stating the repo follows Scripts to Rule Them All, links https://github.com/github/scripts-to-rule-them-all, and documents each script/ entrypoint. grep -n "script/" README.md currently returns nothing, even though all 12 entrypoints exist and .gitea/workflows/check.yml runs script/cibuild.

3. §Build is stale after the STRTA migration. README.md:448 still claims "The Makefile is the single source of truth for all operations", but every target is now a thin shim into script/ (Makefile:20-47). make bootstrap and make setup exist and are undocumented. README.md:461 still describes make clean as removing "any legacy local files.dat", a file nothing produces any more.

4. The summary-line example does not add up. README.md:286 shows:

scan: 123456 files seen (1200 added, 34 updated, 56 removed, 122166 unchanged), 3 skipped

but 1200 + 34 + 122166 = 123400, not 123456. The example only works if removed is counted in the total, which README.md:289-290 explicitly says it is not — and the code follows the prose (scan.go:76 sums added + updated + unchanged). Fix the example's arithmetic.

Definition of done

  1. Lines 19-20 are gone.
  2. An Entrypoints section exists, in the house-standard shape, documenting all 12 entrypoints.
  3. §Build documents make bootstrap and make setup, drops the single-source-of-truth claim in favour of pointing at script/, and drops the files.dat clause.
  4. The summary example sums correctly.
  5. Docs-only: no changes to code, config, scripts, CI or build files. The files.dat references outside the README are #22.
  6. make check green.
Several independent README defects, all docs-only, all worth one pass. **1. AI-tooling attribution.** `README.md:19-20` reads "This tool was created by [@sneak](https://sneak.berlin) to scratch an itch, using Claude Code/Fable." That naming is not wanted anywhere in this repo's output. Delete the sentence; the Description paragraph above it already carries authorship and licence. This is the only such reference in the tree — the commit history is clean. **2. The required Entrypoints section is missing.** House policy requires a README **Entrypoints** section that opens by stating the repo follows Scripts to Rule Them All, links `https://github.com/github/scripts-to-rule-them-all`, and documents each `script/` entrypoint. `grep -n "script/" README.md` currently returns nothing, even though all 12 entrypoints exist and `.gitea/workflows/check.yml` runs `script/cibuild`. **3. §Build is stale after the STRTA migration.** `README.md:448` still claims "The `Makefile` is the single source of truth for all operations", but every target is now a thin shim into `script/` (`Makefile:20-47`). `make bootstrap` and `make setup` exist and are undocumented. `README.md:461` still describes `make clean` as removing "any legacy local `files.dat`", a file nothing produces any more. **4. The summary-line example does not add up.** `README.md:286` shows: scan: 123456 files seen (1200 added, 34 updated, 56 removed, 122166 unchanged), 3 skipped but 1200 + 34 + 122166 = 123400, not 123456. The example only works if `removed` is counted in the total, which `README.md:289-290` explicitly says it is not — and the code follows the prose (`scan.go:76` sums added + updated + unchanged). Fix the example's arithmetic. ## Definition of done 1. Lines 19-20 are gone. 2. An **Entrypoints** section exists, in the house-standard shape, documenting all 12 entrypoints. 3. §Build documents `make bootstrap` and `make setup`, drops the single-source-of-truth claim in favour of pointing at `script/`, and drops the `files.dat` clause. 4. The summary example sums correctly. 5. Docs-only: no changes to code, config, scripts, CI or build files. The `files.dat` references outside the README are #22. 6. `make check` green.
clawbot added this to the 1.0.0 milestone 2026-08-09 03:47:04 +02:00
clawbot commented 2026-08-09 09:49:43 +02:00
Author
Collaborator
Copy Link
Copy Source

Implementation plan

Docs-only. README.md is the only file touched — no code, config,
script/, CI or build files, and no TODO.md entry, because DoD item 5
restricts the change to the README alone. The PR body will say so
explicitly.

Branch readme-entrypoints off main (a102b8f), in a temporary
worktree.

1. AI-tooling attribution (DoD 1). Delete lines 19-20 in full,
including the blank line that separated them from the following
paragraph. The Description paragraph already names
[@sneak](https://sneak.berlin) and the MIT licence, so nothing is
lost.

2. Entrypoints section (DoD 2). New ## Entrypoints section in the
house-standard shape: opens by stating the repo adheres to
Scripts to Rule Them All,
notes that the script/ entrypoints are the development workflow and
the Makefile targets are thin shims onto them, then one entry per
script. All twelve get documented from having read each one, not from
the name: bootstrap, setup, projectname, test, lint, fmt,
fmt-check, check, docker, cibuild, precommit,
install-precommit. Two get the extra sentence their behaviour
warrants:

  • bootstrap version-checks golangci-lint against the pinned version
    rather than merely checking presence, reinstalls on any mismatch, and
    then verifies the pinned copy is the one PATH actually resolves,
    failing with both paths named when something shadows it.
  • cibuild and docker both pass a fresh CHECK_EPOCH build argument
    so the Dockerfile's gate layers cannot be served from cache; without
    it a build can exit 0 having run neither the tests nor the lint.

Placement: after ## Getting Started would interrupt the specification
flow, so the section goes immediately before ## Build, which is the
adjacent topic and what it hands off to.

3. §Build (DoD 3). Replace "The Makefile is the single source of
truth for all operations" with prose pointing at script/ as the
implementation and the Makefile targets as shims. Add the undocumented
make bootstrap and make setup. Reduce the make clean line to
removing the binary — the files.dat clause goes, and the remaining
files.dat references in Makefile, .gitignore and .dockerignore
stay untouched as #22.

4. Summary-line arithmetic (DoD 4). README.md:286. removed is
correctly excluded from the total per lines 289-290 and per
scan.go, so the fix is the total, not the semantics: 1200 + 34 +
122166 = 123400, so 123456 files seen becomes 123400 files seen.
56 removed and 3 skipped are unchanged.

Verification. make check (green), plus a
git diff --stat main..HEAD confirming README.md is the sole changed
file.

## Implementation plan Docs-only. `README.md` is the only file touched — no code, config, `script/`, CI or build files, and no `TODO.md` entry, because DoD item 5 restricts the change to the README alone. The PR body will say so explicitly. Branch `readme-entrypoints` off `main` (`a102b8f`), in a temporary worktree. **1. AI-tooling attribution (DoD 1).** Delete lines 19-20 in full, including the blank line that separated them from the following paragraph. The Description paragraph already names `[@sneak](https://sneak.berlin)` and the MIT licence, so nothing is lost. **2. Entrypoints section (DoD 2).** New `## Entrypoints` section in the house-standard shape: opens by stating the repo adheres to [Scripts to Rule Them All](https://github.com/github/scripts-to-rule-them-all), notes that the `script/` entrypoints are the development workflow and the `Makefile` targets are thin shims onto them, then one entry per script. All twelve get documented from having read each one, not from the name: `bootstrap`, `setup`, `projectname`, `test`, `lint`, `fmt`, `fmt-check`, `check`, `docker`, `cibuild`, `precommit`, `install-precommit`. Two get the extra sentence their behaviour warrants: - `bootstrap` version-checks `golangci-lint` against the pinned version rather than merely checking presence, reinstalls on any mismatch, and then verifies the pinned copy is the one `PATH` actually resolves, failing with both paths named when something shadows it. - `cibuild` and `docker` both pass a fresh `CHECK_EPOCH` build argument so the `Dockerfile`'s gate layers cannot be served from cache; without it a build can exit 0 having run neither the tests nor the lint. Placement: after `## Getting Started` would interrupt the specification flow, so the section goes immediately before `## Build`, which is the adjacent topic and what it hands off to. **3. §Build (DoD 3).** Replace "The `Makefile` is the single source of truth for all operations" with prose pointing at `script/` as the implementation and the `Makefile` targets as shims. Add the undocumented `make bootstrap` and `make setup`. Reduce the `make clean` line to removing the binary — the `files.dat` clause goes, and the remaining `files.dat` references in `Makefile`, `.gitignore` and `.dockerignore` stay untouched as #22. **4. Summary-line arithmetic (DoD 4).** `README.md:286`. `removed` is correctly excluded from the total per lines 289-290 and per `scan.go`, so the fix is the total, not the semantics: 1200 + 34 + 122166 = 123400, so `123456 files seen` becomes `123400 files seen`. `56 removed` and `3 skipped` are unchanged. **Verification.** `make check` (green), plus a `git diff --stat main..HEAD` confirming `README.md` is the sole changed file.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
merge-ready
Review passed; ready to merge
 needs-checks
CI checks failing or not yet green
 needs-rebase
Branch conflicts with main; rebase required
 needs-review
PR awaiting independent adversarial review
 needs-rework
Review found blocking problems; author must rework
No labels
Milestone
No items
No Milestone 1.0.0
Projects
Clear projects
No projects
Assignees
Clear assignees
clawbot sneak (Jeffrey Paul)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: sneak/sfdupes#21