guard: close the gaps two other projects pointed at

The owner shared the notes of two other projects of his, and the rule
that held was: measurements, traps and methods transfer, conclusions do
not. Two conclusions from there did not survive being checked here, and
three of the traps found real defects.

The conclusion that failed: a refusal comes out in the language of the
machine. True there, on .NET, measured on two machines. Go does not
behave that way - it asks Windows for the English message explicitly
before falling back. Measured here on a Polish install, Errno(1) gives
"Incorrect function." while FormatMessage on its own gives "Niepoprawna
funkcja.". Writing their sentence down would have been a false claim
about this tool.

The change stands for a different reason. The system's sentence is opaque
in any language - "Incorrect function." for reading a directory tells
nobody anything - so describeError replaces it with ours and keeps the
number, which is the part that means the same everywhere. Pointing a
command at a directory now says so and prints what to run instead, which
is the mistake somebody actually makes because the neighbouring commands
take directories.

Also checked and NOT adopted: their two command line findings, a flag
silently accepted and a flag missing from the help. Both are impossible
here by construction - a separate FlagSet per command refuses an unknown
flag, and the help is generated from that same set. No guard was added
for something the architecture already closes.

The trap that paid off most: a guard kept by hand is a guard somebody
eventually does not add. Two rows of the regression surface claimed a
locality guard was proven by mutation and no entry named one, so
untouchable rule 2 rested on a sentence. Four mutations went in, each
aimed one test at a time - the first substitution reddened only the
reordering guard, and naming any of the other three would have reported
it as uncaught.

Their question about a second Ctrl+C produced a probe and two answers.
There is no second press to measure: the run ends within 0.00 s of the
first, in both shapes tried, so every later press lands on a process that
has already gone. And the probe crashed on "files": null in a manifest
describing no files - a defect nobody was looking for, where every other
empty collection beside it was written as {}.

Six numbering schemes and 186 links between documents now have guards
too. They skip loudly on a fresh checkout, because the documents live
outside the repository.

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

Author: donislawdev

CHANGELOG-DEV.md

@@ -38,6 +38,50 @@ belongs in one place.
   lowercase - the last one **the same length as what it replaced**, so the file
   does not move by a single byte and only a guard that knows SVG is case
   sensitive notices.
+- **The mutation list is kept by hand, so something now checks it is kept.**
+  Every guard is named by a mutation, or written down as unproven, or written
+  down as proven by probe - and which of the three is visible rather than
+  assumed. The third state exists for guards that read documents, where there is
+  no product code underneath for a mutation to reach.
+  It earned its place immediately. Two rows of the regression surface said a
+  locality guard was proven by mutation and no entry named one, so untouchable
+  rule 2 - seeds are derived, never drawn from a shared stream - rested on a
+  sentence rather than on a check. Four mutations went in for it, and each was
+  aimed one test at a time: the first substitution reddened only the reordering
+  guard, and naming any of the other three would have reported it as uncaught.
+- **A guard for the identifiers the documents are built on.** Six numbering
+  schemes carry the decisions here, they collided once, and nothing was watching
+  them. A reference now has to land on something, a range may not grow a hole -
+  numbers are handed out once and never withdrawn - and the summary table in
+  CLAUDE.md has to agree with what the six documents actually define. Measured
+  when it went in: 66 identifiers across 13 documents, none dangling, no holes,
+  every declared range correct.
+  Proven by probe rather than by mutation, three ways: a reference to a decision
+  that does not exist, a number removed from the middle of a range, and the
+  summary table announcing a range the document no longer defines.
+- **A probe that sends a real Ctrl+C**, `tools/probes/ctrl-c-probe.py`. It is
+  safe to run beside a working session because the child gets its own process
+  group and the console event goes only there - sending to group 0 would hit the
+  shell running it.
+  What it settled: there is no second press to measure. The run ends within
+  0.00 s of the first one in both shapes tried - thousands of small files and a
+  single 400 MB file - so every later press lands on a process that has already
+  gone. Six runs, exit 130 every time, manifest always written, files on disk
+  always equal to manifest entries. The probe reports whether each press landed
+  on a live run, because an earlier version sent four and measured one.
+  It also crashed on `"files": null` and found a defect nobody was looking for.
+- **Errors from the system go through one place.** `describeError` swaps the
+  system's sentence for ours wherever it sits in a wrapped chain and keeps every
+  layer of context above it. Sixteen call sites route through it.
+  **The finding that prompted this did not survive being checked, and the
+  change stands for a different reason.** It came from another project of the
+  owner's, where a refusal comes out in the language of the machine - measured
+  there, on two machines. Go does not behave that way: it asks Windows for the
+  English message explicitly before falling back to the machine's own. Measured
+  here, on a Polish install, `syscall.Errno(1)` gives "Incorrect function."
+  while FormatMessage on its own gives "Niepoprawna funkcja.". So the leak is
+  only the fallback. The sentence is opaque in any language, which is the reason
+  that held.
 - **One primitive for every record based format, in `core.FillRecords`.** Whole
   records while another still leaves room, then a closing record built to the
   byte. That rule was written out by hand for the third and fourth time when

CHANGELOG.md

@@ -233,6 +233,24 @@ because it turns other people's test suites red.
 
 ### Fixed
 
+- **Pointing a command at a directory says so.** `tfg verify out/` used to answer
+  `read out: Incorrect function.`, which is what Windows says about reading a
+  directory and which reads like a fault in this tool. All four commands that
+  take a file - `verify`, `cleanup`, `validate` and `recipe fmt` - now say the
+  path is a directory and print the command to run instead. The neighbouring
+  commands take directories, so this is the mistake worth answering properly.
+- **A failure caused by the system is reported in our words, with the number.**
+  The sentence an operating system hands back is opaque whatever language it is
+  in, and on an install without the English message resource it is not English
+  either. A missing recipe now reads `there is nothing at that path (system
+  error 2)` rather than whatever the machine chose to say. The number is kept
+  because it means the same thing everywhere.
+- **A manifest describing no files carries an empty list.** A run stopped before
+  its first file finished wrote `"files": null`, while every other empty
+  collection in the same manifest was written as `{}`. Anything reading the
+  manifest and looping over the entries met a value that was not a list. It is
+  `[]` now, at every size including nought.
+
 - **A recipe saved by an editor that adds a byte order mark is read.** Notepad
   on Windows adds one by default. The mark used to reach the reader as part of
   the first key, so the tool reported `version` as an unknown field - and the

internal/cli/cli.go

@@ -13,6 +13,7 @@ import (
 	"flag"
 	"fmt"
 	"io"
+	"io/fs"
 	"os"
 	"path/filepath"
 	"strings"
@@ -244,7 +245,7 @@ Flags:
 
 		bytesWanted, err := core.ParseSize(*sizeStr)
 		if err != nil {
-			fmt.Fprintf(errOut, "tfg: %v\n", err)
+			fmt.Fprintf(errOut, "tfg: %s\n", describeError(err))
 			return ExitUsage
 		}
 
@@ -272,7 +273,7 @@ Flags:
 
 	planned, err := engine.Plan(targets, opt)
 	if err != nil {
-		fmt.Fprintf(errOut, "tfg: %v\n", err)
+		fmt.Fprintf(errOut, "tfg: %s\n", describeError(err))
 		return classify(err)
 	}
 
@@ -294,7 +295,7 @@ Flags:
 	}
 
 	if runErr != nil {
-		fmt.Fprintf(errOut, "tfg: %v\n", runErr)
+		fmt.Fprintf(errOut, "tfg: %s\n", describeError(runErr))
 		if !*dryRun {
 			saveManifest(res, opt, errOut)
 		}
@@ -311,7 +312,7 @@ Flags:
 	if *asJSON {
 		var buf bytes.Buffer
 		if err := res.Manifest.Encode(&buf); err != nil {
-			fmt.Fprintf(errOut, "tfg: cannot render the manifest: %v\n", err)
+			fmt.Fprintf(errOut, "tfg: cannot render the manifest: %s\n", describeError(err))
 			return ExitRuntime
 		}
 		out.Write(buf.Bytes())
@@ -403,17 +404,17 @@ func contentsOf(t recipe.Target) []format.Content {
 func loadRecipe(path string, errOut io.Writer) (*recipe.Recipe, string, int) {
 	src, err := os.ReadFile(path)
 	if err != nil {
-		fmt.Fprintf(errOut, "tfg: cannot read the recipe %s: %v\n", path, err)
+		fmt.Fprintf(errOut, "tfg: cannot read the recipe %s: %s\n", path, describeError(err))
 		return nil, "", ExitIO
 	}
 	rec, err := recipe.Parse(src, path)
 	if err != nil {
-		fmt.Fprintf(errOut, "tfg: %v\n", err)
+		fmt.Fprintf(errOut, "tfg: %s\n", describeError(err))
 		return nil, "", classify(err)
 	}
 	hash, err := recipe.Hash(src)
 	if err != nil {
-		fmt.Fprintf(errOut, "tfg: %v\n", err)
+		fmt.Fprintf(errOut, "tfg: %s\n", describeError(err))
 		return nil, "", classify(err)
 	}
 	return rec, hash, ExitOK
@@ -438,6 +439,10 @@ func validate(args []string, out, errOut io.Writer) int {
 		fmt.Fprintln(errOut, "tfg: validate takes one recipe file. Example: tfg validate recipe.yaml")
 		return ExitUsage
 	}
+	if err := mustBeFile(path, "recipe.yaml", "validate"); err != nil {
+		fmt.Fprintf(errOut, "tfg: %s\n", err)
+		return ExitUsage
+	}
 
 	rec, hash, code := loadRecipeReporting(path, *asJSON, errOut)
 	if code != ExitOK {
@@ -465,7 +470,7 @@ func validate(args []string, out, errOut io.Writer) int {
 				Problems: []validateProblem{{What: err.Error()}}})
 			return classify(err)
 		}
-		fmt.Fprintf(errOut, "tfg: %v\n", err)
+		fmt.Fprintf(errOut, "tfg: %s\n", describeError(err))
 		return classify(err)
 	}
 
@@ -569,10 +574,14 @@ Flags:
 		fmt.Fprintln(errOut, "tfg: verify takes one manifest file. Example: tfg verify out/manifest.json")
 		return ExitUsage
 	}
+	if err := mustBeFile(path, "manifest.json", "verify"); err != nil {
+		fmt.Fprintf(errOut, "tfg: %s\n", err)
+		return ExitUsage
+	}
 
 	m, err := manifest.Load(path)
 	if err != nil {
-		fmt.Fprintf(errOut, "tfg: %v\n", err)
+		fmt.Fprintf(errOut, "tfg: %s\n", describeError(err))
 		return classify(err)
 	}
 
@@ -673,10 +682,14 @@ Flags:
 		fmt.Fprintln(errOut, "tfg: cleanup takes one manifest file. Example: tfg cleanup out/manifest.json")
 		return ExitUsage
 	}
+	if err := mustBeFile(path, "manifest.json", "cleanup"); err != nil {
+		fmt.Fprintf(errOut, "tfg: %s\n", err)
+		return ExitUsage
+	}
 
 	m, err := manifest.Load(path)
 	if err != nil {
-		fmt.Fprintf(errOut, "tfg: %v\n", err)
+		fmt.Fprintf(errOut, "tfg: %s\n", describeError(err))
 		return classify(err)
 	}
 
@@ -766,7 +779,7 @@ Flags:
 		if blocked > 0 {
 			fmt.Fprintf(errOut, "tfg: the manifest was kept because %d file(s) it lists are still there. It is the only record of them.\n", blocked)
 		} else if err := os.Remove(path); err != nil {
-			fmt.Fprintf(errOut, "tfg: cannot remove the manifest %s: %v\n", path, err)
+			fmt.Fprintf(errOut, "tfg: cannot remove the manifest %s: %s\n", path, describeError(err))
 			return ExitIO
 		}
 	}
@@ -898,16 +911,20 @@ Flags:
 		fmt.Fprintln(errOut, "tfg: recipe fmt takes one recipe file. Example: tfg recipe fmt recipe.yaml")
 		return ExitUsage
 	}
+	if err := mustBeFile(path, "recipe.yaml", "recipe fmt"); err != nil {
+		fmt.Fprintf(errOut, "tfg: %s\n", err)
+		return ExitUsage
+	}
 
 	src, err := os.ReadFile(path)
 	if err != nil {
-		fmt.Fprintf(errOut, "tfg: cannot read the recipe %s: %v\n", path, err)
+		fmt.Fprintf(errOut, "tfg: cannot read the recipe %s: %s\n", path, describeError(err))
 		return ExitIO
 	}
 
 	canon, err := recipe.Canonical(src, path)
 	if err != nil {
-		fmt.Fprintf(errOut, "tfg: %v\n", err)
+		fmt.Fprintf(errOut, "tfg: %s\n", describeError(err))
 		return classify(err)
 	}
 
@@ -929,7 +946,7 @@ Flags:
 			return ExitOK
 		}
 		if err := os.WriteFile(path, canon, 0o644); err != nil {
-			fmt.Fprintf(errOut, "tfg: cannot write %s: %v\n", path, err)
+			fmt.Fprintf(errOut, "tfg: cannot write %s: %s\n", path, describeError(err))
 			return ExitIO
 		}
 		fmt.Fprintf(errOut, "%s rewritten.\n", path)
@@ -950,7 +967,7 @@ func saveManifest(res *engine.Result, opt engine.Options, errOut io.Writer) int
 	}
 	path := filepath.Join(opt.OutDir, name)
 	if err := res.Manifest.Save(path); err != nil {
-		fmt.Fprintf(errOut, "tfg: cannot write the manifest to %s: %v\n", path, err)
+		fmt.Fprintf(errOut, "tfg: cannot write the manifest to %s: %s\n", path, describeError(err))
 		return ExitIO
 	}
 	fmt.Fprintf(errOut, "manifest: %s\n", path)
@@ -997,7 +1014,7 @@ func formats(args []string, out, errOut io.Writer) int {
 		enc := json.NewEncoder(out)
 		enc.SetIndent("", "  ")
 		if err := enc.Encode(list); err != nil {
-			fmt.Fprintf(errOut, "tfg: cannot render the list: %v\n", err)
+			fmt.Fprintf(errOut, "tfg: cannot render the list: %s\n", describeError(err))
 			return ExitRuntime
 		}
 		return ExitOK
@@ -1016,6 +1033,71 @@ func formats(args []string, out, errOut io.Writer) int {
 // The mapping lives here and nowhere else, and it works on error types rather
 // than on message text. Anything unrecognised becomes a runtime error, which
 // is the honest answer for a failure the tool did not anticipate.
+// describeError renders an error for a person, in English, whatever language
+// the operating system speaks.
+//
+// Every message this tool prints is English. A wrapped operating system error
+// breaks that with nothing noticing, because the system formats its messages in
+// the language of the machine - "Incorrect function." reaches somebody on a
+// Polish install as a Polish sentence. The guard that scans this binary for non
+// English text cannot see it, since that text is not in the binary at all. It
+// arrives at run time.
+//
+// So the system's sentence is swapped for ours and every layer of our own
+// context above it is kept. The number it carried stays, because a number means
+// the same thing in every language and it is what somebody puts into a search.
+func describeError(err error) string {
+	if err == nil {
+		return ""
+	}
+
+	var errno syscall.Errno
+	if !errors.As(err, &errno) {
+		return err.Error()
+	}
+
+	// Replace it wherever it sits rather than only at the end. A message built
+	// by wrapping prints the innermost error last, but nothing guarantees that,
+	// and a leak of one sentence is the whole defect.
+	full := err.Error()
+	if osText := errno.Error(); osText != "" && strings.Contains(full, osText) {
+		return strings.ReplaceAll(full, osText, systemReason(errno))
+	}
+	return full
+}
+
+// systemReason is our own English sentence for a system error, with the number
+// beside it. The number is the part that survives translation.
+func systemReason(errno syscall.Errno) string {
+	reason := "the system refused it"
+	switch {
+	case errors.Is(errno, fs.ErrNotExist):
+		reason = "there is nothing at that path"
+	case errors.Is(errno, fs.ErrPermission):
+		reason = "the system refused permission"
+	case errors.Is(errno, fs.ErrExist):
+		reason = "something is already there"
+	}
+	return fmt.Sprintf("%s (system error %d)", reason, uintptr(errno))
+}
+
+// mustBeFile turns the likeliest mistake into a sentence of ours.
+//
+// Every command below takes a file and the neighbouring ones take directories,
+// so pointing one at a directory is the mistake somebody actually makes. Left
+// alone it surfaces as whatever the system says about reading a directory,
+// which on Windows is "Incorrect function." and says nothing to anybody.
+func mustBeFile(path, kind, command string) error {
+	info, err := os.Stat(path)
+	if err != nil || !info.IsDir() {
+		// Anything else is left to the read that follows, so one fault gives
+		// one message.
+		return nil
+	}
+	return fmt.Errorf("%s is a directory and %s reads a file. Name the one inside it, for example: tfg %s %s",
+		path, command, command, filepath.Join(path, kind))
+}
+
 func classify(err error) int {
 	var recipeErr *engine.RecipeError
 	if errors.As(err, &recipeErr) {