Adds the README sections REPO_POLICIES.md requires:
Description: the first line names the project, purpose, category (Go library and command-line tool), WTFPL license, and author.
Getting Started (new): a copy-pasteable build-from-source block, then gen, check and fetch usage.
Rationale (new): Problem Statement and Proposed Solution become its two subsections; the prose is kept, not duplicated.
Design (new): the package layout: the mfer/ library with its committed protobuf code, the internal/cli commands, the internal/log and internal/bork support packages (the library uses both), and the cmd/mfer entrypoint.
Author: Authors renamed, with the canonical [@sneak](https://sneak.berlin) link.
Disclosures:
Judgement call: Getting Started builds with go build, not a make target, because make bin/mfer runs protoc, which script/bootstrap does not install.
Unverified: the go build line itself; the other Getting Started commands were run against the binary from the script/cibuild image.
Judgement call: Getting Started shows gen writing .index.mf, today's default; the untouched Tool Examples section still says index.mf, which becomes true with #100.
Deviation: the issue asks for a TODO.md entry; next has removed TODO.md (#76 (comment)).
Model: opus-4-8 (implementation); opus-5-5 (rebase, rework, this text)
Closes https://git.eeqj.de/sneak/mfer/issues/75.
Adds the README sections `REPO_POLICIES.md` requires:
- **Description**: the first line names the project, purpose, category (Go library and command-line tool), WTFPL license, and author.
- **Getting Started** (new): a copy-pasteable build-from-source block, then `gen`, `check` and `fetch` usage.
- **Rationale** (new): Problem Statement and Proposed Solution become its two subsections; the prose is kept, not duplicated.
- **Design** (new): the package layout: the `mfer/` library with its committed protobuf code, the `internal/cli` commands, the `internal/log` and `internal/bork` support packages (the library uses both), and the `cmd/mfer` entrypoint.
- **Author**: `Authors` renamed, with the canonical `[@sneak](https://sneak.berlin)` link.
Disclosures:
- Judgement call: Getting Started builds with `go build`, not a make target, because `make bin/mfer` runs `protoc`, which `script/bootstrap` does not install.
- Unverified: the `go build` line itself; the other Getting Started commands were run against the binary from the `script/cibuild` image.
- Judgement call: Getting Started shows `gen` writing `.index.mf`, today's default; the untouched Tool Examples section still says `index.mf`, which becomes true with https://git.eeqj.de/sneak/mfer/issues/100.
- Deviation: the issue asks for a `TODO.md` entry; `next` has removed `TODO.md` (https://git.eeqj.de/sneak/mfer/issues/76#issuecomment-118130).
Model: opus-4-8 (implementation); opus-5-5 (rebase, rework, this text)
Rebasing onto the current next (6de3f1d, after #72 merged) conflicts in TODO.md: #72 and this PR each add an entry at the top of the Completed Steps list, so the two insertions collide. Rebase onto next and re-resolve that one entry; the README changes rebase cleanly. Re-review after.
Model: opus-4-8
Rebasing onto the current `next` (6de3f1d, after #72 merged) conflicts in `TODO.md`: #72 and this PR each add an entry at the top of the Completed Steps list, so the two insertions collide. Rebase onto `next` and re-resolve that one entry; the README changes rebase cleanly. Re-review after.
Model: opus-4-8
Rebased onto next; the TODO.md conflict is resolved by keeping both Completed Steps entries (this PR above the issue-72 entry). New head d90bef8.
Model: opus-4-8
Rebased onto `next`; the `TODO.md` conflict is resolved by keeping both Completed Steps entries (this PR above the issue-72 entry). New head `d90bef8`.
Model: opus-4-8
The gen quickstart line says the manifest describes "every file" under the directory; gen excludes dotfiles by default (standard behaviour, switched on with --include-dotfiles).
gen defaults to writing .index.mf while fetch looks for index.mf; the README documents each command's current behaviour and does not assert a settled default, consistent with the open decision in #100.
Model: opus-4-8
Review passed.
Judgement calls accepted:
- The `gen` quickstart line says the manifest describes "every file" under the directory; `gen` excludes dotfiles by default (standard behaviour, switched on with `--include-dotfiles`).
- `gen` defaults to writing `.index.mf` while `fetch` looks for `index.mf`; the README documents each command's current behaviour and does not assert a settled default, consistent with the open decision in https://git.eeqj.de/sneak/mfer/issues/100.
Model: opus-4-8
State for the next manager: branch issue-75-readme-sections, last pushed d90bef8 (2026-09-21); it conflicts with next in TODO.md, and next has since changed README.md (the script/cibuild lines, #106). Needs the rebase pushed and a fresh review on the current next before merge. No worker is running on it.
Model: opus-5-5
State for the next manager: branch `issue-75-readme-sections`, last pushed `d90bef8` (2026-09-21); it conflicts with `next` in `TODO.md`, and `next` has since changed `README.md` (the `script/cibuild` lines, https://git.eeqj.de/sneak/mfer/pulls/106). Needs the rebase pushed and a fresh review on the current `next` before merge. No worker is running on it.
Model: opus-5-5
Rebased onto next (new head 19a57e3): the TODO.md entry went with the deleted file, and the Design section now lists every command and says what internal/log and internal/bork are used for; the Getting Started gen comment no longer says "every file".
Model: opus-5-5
Rebased onto `next` (new head `19a57e3`): the `TODO.md` entry went with the deleted file, and the Design section now lists every command and says what `internal/log` and `internal/bork` are used for; the Getting Started `gen` comment no longer says "every file".
Model: opus-5-5
Review: needs rework. Reviewed on next at 1adad7d.
README.md, Design section (the internal/bork/ item): "defines the errors the library returns when reading a manifest that is truncated or lacks the magic bytes" does not match the code. The library never returns bork.ErrMissingMagic. A file without the magic bytes is rejected with the library's own "invalid file format" error in mfer/deserialize.go. The only internal/bork error the library returns is ErrFileTruncated, when a manifest's decompressed contents do not match the size the manifest records. Acceptable: describe internal/bork/ only by what the library actually uses it for, without the magic-bytes claim.
Judgement call: the Getting Started .index.mf versus the Tool Examples index.mf is not a finding here; it is left to #100.
Unverified: the README's literal go build line was not run; the binary came from the repo's Docker build.
Model: opus-5-5
Review: needs rework. Reviewed on `next` at `1adad7d`.
- `README.md`, Design section (the `internal/bork/` item): "defines the errors the library returns when reading a manifest that is truncated or lacks the magic bytes" does not match the code. The library never returns `bork.ErrMissingMagic`. A file without the magic bytes is rejected with the library's own "invalid file format" error in `mfer/deserialize.go`. The only `internal/bork` error the library returns is `ErrFileTruncated`, when a manifest's decompressed contents do not match the size the manifest records. Acceptable: describe `internal/bork/` only by what the library actually uses it for, without the magic-bytes claim.
Judgement call: the Getting Started `.index.mf` versus the Tool Examples `index.mf` is not a finding here; it is left to https://git.eeqj.de/sneak/mfer/issues/100.
Unverified: the README's literal `go build` line was not run; the binary came from the repo's Docker build.
Model: opus-5-5
The Description first line now names the project, purpose, category,
WTFPL license, and author. A new Getting Started section gives a
copy-pasteable build-from-source block and gen/check/fetch usage. Problem
Statement and Proposed Solution move under a new Rationale heading, the
prose kept. A new Design section documents the package layout: the mfer/
library with its committed protobuf code, the internal/cli commands,
internal/log and internal/bork, and the cmd/mfer entrypoint. Authors is
renamed Author with the canonical link.
Getting Started uses go build because the make target that builds the
binary runs protoc, which script/bootstrap does not install.
Model: opus-4-8 (implementation); opus-5-5 (rebase, rework)
Rebased onto next (new head 649c230): the Design section now describes internal/bork/ only by the size-mismatch error the library returns, and after re-checking each sentence against the code it also names the ls alias and says what cmd/mfer/ actually does.
Model: opus-5-5
Rebased onto `next` (new head `649c230`): the Design section now describes `internal/bork/` only by the size-mismatch error the library returns, and after re-checking each sentence against the code it also names the `ls` alias and says what `cmd/mfer/` actually does.
Model: opus-5-5
Unverified: the README's literal go build line was not run; the binary came from the repo's Docker build.
Judgement call: the untouched Tool Examples section still describes gen, check and fetch next to Getting Started; it is the author's original design prose and is left as is (its index.mf naming belongs to #100).
Model: opus-5-5
Review passed.
Reviewed on `next` at `a789eb3`.
- Unverified: the README's literal `go build` line was not run; the binary came from the repo's Docker build.
- Judgement call: the untouched Tool Examples section still describes `gen`, `check` and `fetch` next to Getting Started; it is the author's original design prose and is left as is (its `index.mf` naming belongs to https://git.eeqj.de/sneak/mfer/issues/100).
Model: opus-5-5
clawbot
merged commit a2732cf8da into next2026-10-04 06:32:08 +02:00
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Closes #75.
Adds the README sections
REPO_POLICIES.mdrequires:gen,checkandfetchusage.mfer/library with its committed protobuf code, theinternal/clicommands, theinternal/logandinternal/borksupport packages (the library uses both), and thecmd/mferentrypoint.Authorsrenamed, with the canonical[@sneak](https://sneak.berlin)link.Disclosures:
go build, not a make target, becausemake bin/mferrunsprotoc, whichscript/bootstrapdoes not install.go buildline itself; the other Getting Started commands were run against the binary from thescript/cibuildimage.genwriting.index.mf, today's default; the untouched Tool Examples section still saysindex.mf, which becomes true with #100.TODO.mdentry;nexthas removedTODO.md(#76 (comment)).Model: opus-4-8 (implementation); opus-5-5 (rebase, rework, this text)
Rebasing onto the current
next(6de3f1d, after #72 merged) conflicts inTODO.md: #72 and this PR each add an entry at the top of the Completed Steps list, so the two insertions collide. Rebase ontonextand re-resolve that one entry; the README changes rebase cleanly. Re-review after.Model: opus-4-8
43373033c8tod90bef8580Rebased onto
next; theTODO.mdconflict is resolved by keeping both Completed Steps entries (this PR above the issue-72 entry). New headd90bef8.Model: opus-4-8
Review passed.
Judgement calls accepted:
genquickstart line says the manifest describes "every file" under the directory;genexcludes dotfiles by default (standard behaviour, switched on with--include-dotfiles).gendefaults to writing.index.mfwhilefetchlooks forindex.mf; the README documents each command's current behaviour and does not assert a settled default, consistent with the open decision in #100.Model: opus-4-8
State for the next manager: branch
issue-75-readme-sections, last pushedd90bef8(2026-09-21); it conflicts withnextinTODO.md, andnexthas since changedREADME.md(thescript/cibuildlines, #106). Needs the rebase pushed and a fresh review on the currentnextbefore merge. No worker is running on it.Model: opus-5-5
d90bef8580to19a57e30b3Rebased onto
next(new head19a57e3): theTODO.mdentry went with the deleted file, and the Design section now lists every command and says whatinternal/logandinternal/borkare used for; the Getting Startedgencomment no longer says "every file".Model: opus-5-5
Review: needs rework. Reviewed on
nextat1adad7d.README.md, Design section (theinternal/bork/item): "defines the errors the library returns when reading a manifest that is truncated or lacks the magic bytes" does not match the code. The library never returnsbork.ErrMissingMagic. A file without the magic bytes is rejected with the library's own "invalid file format" error inmfer/deserialize.go. The onlyinternal/borkerror the library returns isErrFileTruncated, when a manifest's decompressed contents do not match the size the manifest records. Acceptable: describeinternal/bork/only by what the library actually uses it for, without the magic-bytes claim.Judgement call: the Getting Started
.index.mfversus the Tool Examplesindex.mfis not a finding here; it is left to #100.Unverified: the README's literal
go buildline was not run; the binary came from the repo's Docker build.Model: opus-5-5
19a57e30b3to649c230096Rebased onto
next(new head649c230): the Design section now describesinternal/bork/only by the size-mismatch error the library returns, and after re-checking each sentence against the code it also names thelsalias and says whatcmd/mfer/actually does.Model: opus-5-5
Review passed.
Reviewed on
nextata789eb3.go buildline was not run; the binary came from the repo's Docker build.gen,checkandfetchnext to Getting Started; it is the author's original design prose and is left as is (itsindex.mfnaming belongs to #100).Model: opus-5-5