Rebase of #1881 by @SaarMesh-Bot onto current master. Their three
commits are preserved, two of them cherry-picked with authorship intact;
the sweep itself had to be regenerated. Opened as a new PR rather than
force-pushing their branch.
Closes#1881 once merged. Addresses parts 1 and 3 of #1859; part 2
landed as #1937.
## Why regenerated rather than merged
The sweep in #1881 was cut on 2026-09-02 07:13 and roughly forty PRs
landed after it, so it went `CONFLICTING/DIRTY`. Re-running `gofmt` on
current master is cheaper and less error-prone than resolving 72
conflicts that are all whitespace. The drift it fixes also grew in the
meantime: 66 files now, against 72 then, but spread differently.
## The three commits
1. **`style(#1859)`** — `gofmt -w` across the 14 modules. 66 files.
2. **`test(#1859)`** — @SaarMesh-Bot's fix for the one `go vet`
copylocks finding, `cmd/ingestor/coverage_boost_test.go`: the range
variable copied a `Config` embedding `sync.Once`. Cherry-picked
unchanged.
3. **`ci(#1859)`** — @SaarMesh-Bot's CI step that fails on gofmt drift
or vet findings, plus `.git-blame-ignore-revs`. Cherry-picked with one
change, noted in the commit message: the ignore file pointed at
`04bc80ee`, the sweep commit on their branch, which does not exist on
this base and would make `git blame --ignore-revs-file` error. Repointed
at `d3a02599`, the sweep here.
## Verification
The claim "formatting only" is checked twice rather than asserted:
- Every changed file is byte-identical to `gofmt(previous content)`. 0
of 66 deviate.
- With line comments and all whitespace stripped, 0 of 66 files differ,
so no code outside comments changed.
14 of the 66 also show doc-comment reflow. Since Go 1.19 `gofmt`
re-indents indented comment blocks to tabs and inserts a blank comment
line before them; the behavior matrix above `resolveHopWithContext` in
`cmd/ingestor/path_resolver.go` is a clear example. That is gofmt's own
output, not an edit, but it is worth naming because it makes the diff
look larger than "whitespace" suggests.
The gate was run locally exactly as the workflow runs it: `gofmt` clean,
and `go vet` clean in all 14 modules, including `cmd/ingestor` which is
what commit 2 fixes.
Suites: `cmd/server` ok (80.7s), `internal/packetpath` ok (2.3s),
`cmd/ingestor` passes except
`TestWriteStatsAtomic_SymlinkAtDestIsReplaced`, which fails identically
on bare master with "A required privilege is not held by the client"
(Windows symlink privilege on my host, not code).
## Sequencing
This should go last in the queue. The sweep touches 66 files, so merging
it before the remaining open Go PRs gives each of them a conflict about
nothing but formatting. After it lands the gate is active, and any PR
with drift fails CI until it runs `gofmt -w`.
Excluded from the sweep: the misnamed `Dockerfile.go`, which is a
Dockerfile that gofmt cannot parse (the workflow excludes it too), and
`docs/DEPLOYMENT.md`, which a case-insensitive filesystem surfaces as a
spurious modification against `docs/deployment.md` and is unrelated.
---------
Co-authored-by: SaarMesh-Bot <300107934+SaarMesh-Bot@users.noreply.github.com>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
## Summary
Partial fix for #1670 — **Phase 1 only** (CI completeness gate). Phase 2
(backfilling the 18 currently-undocumented routes into `openapi.go`) is
deferred to a separate issue per the triage on #1670 and is explicitly
out of scope here.
## What this adds
- `cmd/server/openapi_completeness_test.go` — AST-walks every
non-`_test.go` file in `cmd/server/`, finds string-literal first args to
`*.HandleFunc(...)` calls beginning with `/api/`, and diffs against the
paths declared in `routeDescriptions()` in `cmd/server/openapi.go`.
- `cmd/server/openapi_known_gaps.json` — seeded allowlist of the **18**
`/api/` routes currently registered via `HandleFunc` but not yet
documented in `openapi.go`.
## Ratchet pattern
From this branch forward, `TestOpenAPICompleteness` fails when:
1. A new `HandleFunc("/api/...")` is added without a matching entry in
`openapi.go` **or** the allowlist (regression gate — the main goal of
Phase 1).
2. A route in the allowlist is *also* documented in `openapi.go` — the
allowlist must shrink as Phase 2 backfills land, never go stale.
The two-commit history (red → green) demonstrates the gate works:
- **Red commit**: adds only the test. Fails on master with the 18
missing routes listed.
- **Green commit**: adds the allowlist seeded with that exact 18-route
set. Test passes at the current baseline.
## Local verification
- `go test ./cmd/server/ -run TestOpenAPICompleteness -v` → PASS at
baseline (`44/62 covered; 18 in allowlist; 18 gaps remain`).
- Ratchet validation: temporarily inserted
`r.HandleFunc("/api/ratchet-test-route", ...)` into `routes.go` → test
FAILED with that exact route name; reverted → test PASSES again.
## Files changed
- `cmd/server/openapi_completeness_test.go` (+203 / new)
- `cmd/server/openapi_known_gaps.json` (+24 / new)
## Preflight
`bash ~/.openclaw/skills/pr-preflight/scripts/run-all.sh origin/master`
→ all hard gates pass; no warnings.
## Out of scope
- Backfilling the 18 allowlisted routes into `openapi.go` (Phase 2 —
tracked separately).
- Schema validation of the spec against OpenAPI 3.0 (Phase 3 per the
issue).
- PR template checkbox update (Phase 2 follow-up).
Issue #1670 stays open for Phase 2.
---------
Co-authored-by: clawbot <bot@corescope.local>
