docs: adapt the comment style guide to this repo, and sweep

[ShocOne]

CLAUDE.md requires comments to say what and why and nothing else, and
docs/comment-style.md is the long form of that rule. The tree had never been
swept against it.

First, the guide describes this repo

It arrived citing internal/hcs/netmodes.go, internal/hcs/reconcile.go,
docs/backends.md, internal/command, cmd/hcsspike, and gate/milestone ids —
none of which exist here. Two sections therefore described a layout this tree
does not have.

The rules are unchanged. What changed is everything that pointed elsewhere:

• Keep — examples are now generator and API behaviour ("kiota models an object
  union as a composed type with one named accessor per branch"), and the tabular
  blocks cited are internal/corpus/cache.go and
  internal/sdkbind/binder_kiota.go, which really carry them.
• Cross-references — docs/contract.md, docs/glossary.md, docs/mapping.md,
  x-tfpfgen-* keys, TFPFGEN_* variables.
• Drop — gains counts and measurements from a particular run, and which
  pull request changed it, both of which CLAUDE.md names and the guide did
  not.
• Transform, don't delete — the before/after is now a real comment from this
  sweep (joinTreeKeeping) rather than one about a Windows guest agent.
• Where the doc goes for commands — internal/cli, cmd/tfpfgen, and a new
  entry for internal/templates: a template's comments are emitted into
  somebody else's repository, where nobody can edit them, so they say what the
  generated code does and never how this toolkit decided to generate it.
• The preamble pointed the investigation at docs/backends.md; it now points at
  the pull request body and commit messages, where a measurement carries a date.

Then the sweep

Every narrative sentence carried a fact, and the fact stays. What goes is the
account of how it was found. Seventeen files:

Kept	Dropped
an inline request body lands in the operation's package, not models, and the exact failure text	"everything else used to fall back to. That fallback was wrong"
the three ways kiota spells an indexer hop (ByGist_id, ByOwnerId, ByEnterpriseTeamId)	"between them they took thirty-eight of one document's forty resources"
taking an envelope as the element binds nothing, and why	"one pilot wraps 166 of its collection responses and leaves only 36 bare"
a removal the emitter kept costs the operator nothing	"how this file came to claim 207 losses on one pilot"
one record beats a switch per name, because the compiler cannot help with bare strings	"those names used to live in six switches… one had already drifted into a duplicate"
real documents annotate only a fraction of their properties	"one pilot annotating 12% … against another's 52%"
an ignorable gate is an ignored gate	"v1's -allow-conflicts taught that"
a committed IR becomes a second source of truth	"v1's fatal flaw was…"
a cache must not be relative, and why go test makes that fatal	"v1 learned this the hard way: 19 MB…"

CLAUDE.md forbids "war stories about a previous version" explicitly, which is
what the six v1 references were. Each stated a real constraint; each keeps it.

Also removed: two editorial asides ("Not a nicety", "which is the point").

Templates were checked and left alone — their tfpfgen references correctly tell
a generated-repo reader where to make changes, which is what those comments are
for.

Measured effect

None, and that is the acceptance test. unsupported.json is
byte-identical on all three pilots, verified with diff:

github         byte-identical
jamfpro        byte-identical
thousandeyes   byte-identical

tfpfgen provider verify — no drift on all three (3358 / 2935 / 1420 files).

Gates

• gofmt -l internal cmd — empty
• scripts/repo_hygiene_gate.sh — pass
• golangci-lint run — 0 issues
• go build ./... && go vet ./... — pass
• go test ./... — pass, coverage 91.4% total

🤖 Generated with Claude Code