cli: say the right thing about the caller's own request

Six refusals from the audit list. None of them lost data. All of them told
somebody something untrue about what they had asked for, which is rule 3 of
this project one level down: the value and the text beside it have to agree.

recipe fmt is about the shape of a file, and now says so. Measured: --check
ends with 0 on a recipe with no version, an unknown top level key, a format
nobody registered, a typo in a target key, and a size and a boundary stated
together - all five of which validate refuses. That is the owner's decision of
2026-08-03 rather than an oversight, because a formatter that refused an
invalid recipe could not lay out one somebody is still writing. What changed
is the text: the help and the flag description now say a check before a commit
wants tfg validate beside it.

The comment in the code claimed the opposite - that the formatter turns away
the same files the rest of the tool turns away - and it was written after
fixing one case of exactly that. True of the case, false in general. This
project has no guard for that kind of prose, so the entry stays in
OBSERVATIONS after being closed.

A PNG asking for more pixels than it can hold ended with 1, which tells CI
this build is broken, for a pair of numbers the caller chose. It is 4 now, the
same as every other value a format cannot deliver. This is the class closed
for declared ranges on 2026-08-03 surviving one layer deeper: the declaration
bounds each side on its own and cannot express a limit on the two multiplied.
tfg formats png now states that limit beside both settings rather than one -
mutation caught the weaker version, because removing the sentence from width
alone left the guard green while somebody setting height still learned
nothing.

What stays open is written down: the limit lives in a sentence rather than in
the declaration, so a window built from the declaration will still offer the
pair. Giving the registry a shape for a constraint binding two settings is a
change to AR9. See O45.

--count 0 or below came back as "asks for 0 files" whatever was typed, because
anything below one produced an empty list and the message described the list
rather than the request. The recipe reader had this right and the flag path
did not.

--out pointing at a file produced two messages for one mistake, the first
saying there was nothing at a path that had something at it - the system
reports a kind of error our mapping had no sentence for.

--expected-reason did not exist. A recipe could say why an outcome was
expected and the command line could not, so a run driven by flags could never
fill the category the closed list exists to make countable. It uses the same
list rather than a second copy, exported for the purpose, because two copies
is how two surfaces drift.

zip's minimum size answered 1<<62 on any failure, on the reasoning that
refusing every size is safer than declaring a wrong minimum. It is not safer,
it is quieter: every ZIP request ever made would be refused with a message
about a minimum of 4611686018427387904 B and nothing would say why. The
condition needs the default entry format to be unregistered, which today
depends on "txt" sorting before "zip" in an import list - true, and true by
accident. It panics now, like format.Register already does for the same class.

Seven guards, each seen red first, and seven mutations. Two were caught wrong:
one did not compile once the struct literal could not be closed by a one line
swap, and one stayed green because it only removed half of what the guard
should have been asking for.

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

Author: donislawdev

CHANGELOG.md

@@ -78,8 +78,33 @@ because it turns other people's test suites red.
   declared contents did not finish at all. It is now 57 ms, and the bytes of
   every archive are unchanged.
 
+### Added
+
+- **`--expected-reason` on the command line.** A recipe could say why an
+  outcome was expected and the flags could not, so a run driven by flags could
+  never fill the category the closed list exists to make countable. The list is
+  the same one the recipe uses, and a value that is not on it is refused with
+  the list to pick from.
+
 ### Changed
 
+- **`tfg recipe fmt` says what it does not check.** It settles the layout of a
+  file and never claimed otherwise in `--help`, but the text implied more than
+  it did. A recipe with a key nobody recognises still has a settled shape and
+  is still formatted, so a check before a commit wants `tfg validate` beside
+  it. Both the help and the flag description now say so.
+- **A PNG asking for more pixels than it can hold is the caller's request, not
+  a fault in the tool.** It ended with 1, which tells CI this build is broken,
+  for a pair of numbers somebody chose. It now ends with 4, the same as every
+  other value a format cannot deliver. `tfg formats png` also states the limit
+  on the two dimensions multiplied - it offered each side up to 20000 without
+  saying that both cannot be at their largest at once.
+- **`--count 0` or below is reported with the number that was written.** It
+  used to come back as "asks for 0 files" whatever was typed, because anything
+  below one produced an empty list and the message described the list.
+- **`--out` pointing at a file says so, once.** It produced two messages for
+  one mistake, the first of them saying there was nothing at a path that had
+  something at it.
 - **A file name ending in a dot or a space is refused.** Windows stores such a
   name without the last character, so the file on disk was not the file the
   manifest described - `tfg generate --name "report."` ended with 0 and `tfg

internal/cli/cli.go

@@ -193,7 +193,7 @@ func flagsGiven(fs *flag.FlagSet) map[string]bool {
 // meaningless next to a recipe that may hold many.
 func describingFlagsGiven(given map[string]bool) []string {
 	var bad []string
-	for _, name := range []string{"format", "size", "size-range", "boundary", "count", "name", "id", "set", "expected"} {
+	for _, name := range []string{"format", "size", "size-range", "boundary", "count", "name", "id", "set", "expected", "expected-reason"} {
 		if given[name] {
 			bad = append(bad, "--"+name)
 		}

internal/cli/generate.go

@@ -18,20 +18,21 @@ import (
 )
 
 type generateOpts struct {
-	formatID  string
-	sizeStr   string
-	sizeRange string
-	boundary  string
-	count     int
-	outDir    string
-	name      string
-	id        string
-	seed      int64
-	expected  string
-	clean     bool
-	dryRun    bool
-	asJSON    bool
-	props     propertyFlag
+	formatID       string
+	sizeStr        string
+	sizeRange      string
+	boundary       string
+	count          int
+	outDir         string
+	name           string
+	id             string
+	seed           int64
+	expected       string
+	expectedReason string
+	clean          bool
+	dryRun         bool
+	asJSON         bool
+	props          propertyFlag
 }
 
 func generateFlagSet(errOut io.Writer, g *generateOpts) (*flag.FlagSet, func(io.Writer)) {
@@ -48,6 +49,8 @@ func generateFlagSet(errOut io.Writer, g *generateOpts) (*flag.FlagSet, func(io.
 	fs.StringVar(&g.id, "id", "files", "target id, the anchor the seeds are derived from")
 	fs.Int64Var(&g.seed, "seed", 0, "run seed, the same seed gives the same bytes")
 	fs.StringVar(&g.expected, "expected", "", "declared expectation: accept, reject, sanitize or unspecified")
+	fs.StringVar(&g.expectedReason, "expected-reason", "",
+		"why that outcome is expected, from the closed list. Run with an unknown value to see it")
 	fs.BoolVar(&g.clean, "clean", false, "turn off the self describing label")
 	fs.BoolVar(&g.dryRun, "dry-run", false, "count and show, write nothing at all")
 	fs.BoolVar(&g.asJSON, "json", false, "write the manifest to standard output")
@@ -209,6 +212,16 @@ func targetsFromFlags(g *generateOpts, given map[string]bool, errOut io.Writer)
 		return nil, ExitUsage
 	}
 
+	// Reported with the number the caller wrote. It used to fall through to the
+	// planner, which builds an empty list from anything below one and then says
+	// "asks for 0 files" - a sentence about a number nobody typed.
+	if given["count"] && g.count < 1 {
+		fmt.Fprintf(errOut,
+			"tfg: --count %d asks for fewer than one file. A target that produces nothing is almost always a mistake rather than an intention. Ask for at least one, or leave the flag out to get a single file.\n",
+			g.count)
+		return nil, ExitRecipe
+	}
+
 	// Asked before the list is built, because building it is the failure. A
 	// count past the ceiling used to reach make([]int64) and panic with a stack
 	// trace under the exit code that means a mistyped flag.
@@ -242,18 +255,34 @@ func targetsFromFlags(g *generateOpts, given map[string]bool, errOut io.Writer)
 		return nil, ExitUsage
 	}
 
+	// The list is closed so that a report can group by reason, and a typo would
+	// make a category of one. Same list the recipe uses rather than a second
+	// copy, because two copies is how the two surfaces drift apart.
+	if g.expectedReason != "" && !recipe.KnownReason(g.expectedReason) {
+		fmt.Fprintf(errOut,
+			"tfg: --expected-reason %q is not on the list. The list is closed so that a report can group by reason. Use one of: %s.\n",
+			g.expectedReason, strings.Join(recipe.Reasons(), ", "))
+		return nil, ExitUsage
+	}
+	if g.expectedReason != "" && g.expected == "" {
+		fmt.Fprintln(errOut,
+			"tfg: --expected-reason says why an outcome is expected and no outcome was given. Add --expected accept, reject, sanitize or unspecified, or drop the reason.")
+		return nil, ExitUsage
+	}
+
 	return []engine.Target{{
-		ID:            g.id,
-		Format:        g.formatID,
-		Sizes:         sizes,
-		SizeIsRange:   g.sizeRange != "",
-		SizeMin:       rangeLow,
-		SizeMax:       rangeHigh,
-		BoundaryLimit: boundaryLimit,
-		NameTmpl:      g.name,
-		Label:         !g.clean,
-		Expected:      g.expected,
-		Properties:    g.props,
+		ID:             g.id,
+		Format:         g.formatID,
+		Sizes:          sizes,
+		SizeIsRange:    g.sizeRange != "",
+		SizeMin:        rangeLow,
+		SizeMax:        rangeHigh,
+		BoundaryLimit:  boundaryLimit,
+		NameTmpl:       g.name,
+		Label:          !g.clean,
+		Expected:       g.expected,
+		ExpectedReason: g.expectedReason,
+		Properties:     g.props,
 	}}, ExitOK
 }
 

internal/cli/recipecmd.go

@@ -202,10 +202,15 @@ func recipeCmd(args []string, out, errOut io.Writer) int {
 	fs := flag.NewFlagSet("recipe fmt", flag.ContinueOnError)
 	fs.SetOutput(errOut)
 	write := fs.Bool("w", false, "write the result back to the file instead of printing it")
-	check := fs.Bool("check", false, "print nothing and end with code 3 when the file is not in its settled shape")
+	check := fs.Bool("check", false, "print nothing and end with code 3 when the layout is not settled. It says nothing about whether the recipe is valid - use tfg validate for that")
 	usage := func(w io.Writer) {
 		fmt.Fprint(w, `tfg recipe fmt - print a recipe in its settled shape, comments kept.
 
+This settles the layout of a file. It does not check that the recipe makes
+sense - a file with a key nobody recognises or a format that does not exist
+still has a settled shape, and this will print it. Run "tfg validate" for
+that, and run both if you are checking recipes before a commit.
+
 Usage:
   tfg recipe fmt <recipe.yaml>
 

internal/engine/engine.go

@@ -396,6 +396,17 @@ func preflight(files []PlannedFile, opt Options) error {
 	// A failure to read the free space is not a reason to refuse. A disk we
 	// cannot measure is not the same as a disk that is full.
 
+	// Pointing --out at a file rather than a directory is a mistake somebody
+	// makes, and it used to arrive as two messages about one fault, the first
+	// of them saying "there is nothing at that path" about a path that has
+	// something at it. The system reports ENOTDIR and our mapping only knew
+	// "missing", "no permission" and "already there".
+	if info, err := os.Stat(opt.OutDir); err == nil && !info.IsDir() {
+		return &RecipeError{Detail: fmt.Sprintf(
+			"the output directory %s is a file, not a directory. Point --out at a directory, or at one that does not exist yet and it will be created",
+			opt.OutDir)}
+	}
+
 	// The manifest is checked with the files it would describe, and leaving it
 	// out cost exactly what it protects. A second run into the same directory
 	// wrote a fresh manifest over the old one, so every file the old one listed

internal/format/png/png.go

@@ -91,15 +91,22 @@ func init() {
 		Label:  format.LabelVisible,
 		Oracle: "pillow",
 		Properties: []format.Property{
+			// The declaration bounds each side on its own and cannot say that
+			// the two multiplied have a limit as well, so the sentence carries
+			// it. Without that, "tfg formats png" offered 20000 by 20000 and
+			// the run then refused it - the tool advertising a pair it does not
+			// accept. Naming the whole rule in the registry needs a shape for a
+			// limit on two settings at once, which is a change to AR9 rather
+			// than a line here. Recorded in docs/OBSERVATIONS.md, O45.
 			{
 				Name: "width", Kind: format.PropertyInt,
 				Min: minDimension, Max: maxDimension, Unit: "pixels",
-				Detail: "How wide the picture is. Left out, a size is chosen that fits the bytes you asked for.",
+				Detail: "How wide the picture is. Left out, a size is chosen that fits the bytes you asked for. Width times height cannot pass 40 megapixels, so both sides cannot be at their largest at once.",
 			},
 			{
 				Name: "height", Kind: format.PropertyInt,
 				Min: minDimension, Max: maxDimension, Unit: "pixels",
-				Detail: "How tall the picture is. Left out, a size is chosen that fits the bytes you asked for.",
+				Detail: "How tall the picture is. Left out, a size is chosen that fits the bytes you asked for. Width times height cannot pass 40 megapixels, so both sides cannot be at their largest at once.",
 			},
 		},
 		GeneratorVersion: generatorVersion,
@@ -275,10 +282,20 @@ func chooseSize(r format.Request, label string) (memo, bool, error) {
 			return memo{}, true, err
 		}
 		_, _ = wRaw, hRaw
+		// A PropertyValueError rather than a plain one, and the difference is
+		// the exit code somebody's CI reads. This used to end with 1, which
+		// means the tool itself broke, for a pair of numbers the caller chose.
+		// That is the same defect closed for declared ranges on 2026-08-03,
+		// surviving one layer deeper: the declaration bounds each dimension on
+		// its own and cannot express a limit on the two multiplied.
 		if int64(w)*int64(h) > maxPixels {
-			return memo{}, true, fmt.Errorf(
-				"png: %dx%d is %d megapixels and the limit is %d - the picture is held in memory while it is encoded. Ask for smaller dimensions",
-				w, h, int64(w)*int64(h)/1_000_000, maxPixels/1_000_000)
+			return memo{}, true, &format.PropertyValueError{
+				Format: "png", Key: "width and height",
+				Value: fmt.Sprintf("%dx%d", w, h),
+				Reason: fmt.Sprintf(
+					"together they come to %d megapixels and the limit is %d, because the picture is held in memory while it is encoded. Each side may go up to %d, but not both at once - ask for a smaller pair",
+					int64(w)*int64(h)/1_000_000, maxPixels/1_000_000, maxDimension),
+			}
 		}
 		m := memo{width: w, height: h, seed: r.Seed, label: label}
 		body, err := encodedBodySize(m)

internal/format/zip/zip.go

@@ -557,23 +557,34 @@ func intProperty(props map[string]string, key string, fallback, min, max int) (i
 
 // minimumBytes is the smallest archive this generator can produce: one empty
 // entry, no label, no padding.
+// It panics rather than returning a number nobody measured.
+//
+// This used to answer 1<<62 on any failure, on the reasoning that refusing
+// every size is safer than declaring a wrong minimum. It is not safer, it is
+// quieter: ZIP would refuse every request ever made with a message about a
+// minimum of 4611686018427387904 B, and nothing would say why. That is rule 6
+// broken in the way this project keeps finding.
+//
+// The condition is a programming mistake rather than a runtime one. It needs
+// the default entry format to be unregistered when this runs, which today
+// depends on "txt" sorting before "zip" in the import list of format/all -
+// true, and true by accident. format.Register already panics on the same class
+// of mistake, so this matches it: a build that cannot state its own minimum
+// fails at start rather than at every use.
 func minimumBytes() int64 {
 	desc, err := format.Get(defaultEntryFmt)
 	if err != nil {
-		// The default entry format is not registered yet, which happens only
-		// if registration order changes. Refusing every size is safer than
-		// declaring a minimum that was never measured.
-		return 1 << 62
+		panic(fmt.Sprintf("zip: the default entry format %q is not registered yet, so the minimum size of an archive cannot be worked out. Check the import order in internal/format/all", defaultEntryFmt))
 	}
 	cp, err := desc.Generator.Plan(format.Request{Bytes: 0, Seed: 0, Label: false})
 	if err != nil {
-		return 1 << 62
+		panic(fmt.Sprintf("zip: the default entry format %q cannot produce an empty file, so the minimum size of an archive cannot be worked out: %v", defaultEntryFmt, err))
 	}
 	n, err := archiveSize(memo{children: []child{{
 		name: "txt_0001.txt", desc: desc, plan: cp,
 	}}})
 	if err != nil {
-		return 1 << 62
+		panic(fmt.Sprintf("zip: the smallest archive cannot be measured: %v", err))
 	}
 	return n
 }