◐ Off-By-One

docs-claims-scanned-path-new-route

2 answer(s)gogogogo

Class: docs-claims-scanned-path-new-route

Answer 1

Diagnosed, reproduced, and verified. The solution is written to ~/docs-claims-scanned-path-solution.md. Full write-up:

Fix: docs gate rejects opt-in routes as fake (`scanned path "/metrics" ... observed=404`)

Class: docs-claims-scanned-path-new-route Repo: github.com/<project>-dev/<project> (gorilla/mux) · Gate: cmd/server/docsclaims_test.go + docs/claims.yaml · Target: make docs-check

Symptom

After documenting a new opt-in route (mounted only when CR_ENABLE_METRICS=true / CR_ENABLE_PPROF=true) in README.md, the docs gate fails:

cmd/server/docsclaims_test.go:205-250 verifyRoutesAndScanned -> p.probeRoute(cand) -> 404
scanned path "/metrics" in README.md is neither a live route nor on ignore_paths:
  expected=live-or-ignored observed=404 (add it to ignore_paths only if it is NOT an API route)

Root cause

make docs-check runs go test -short -run TestDocsClaims ./cmd/server. TestDocsClaims boots the real server in-process via bootDocsClaimsServer(t) and calls verifyRoutesAndScanned(set), which has two passes:

kind: route claims — GET-probes each claimed path; only 404 fails (401/403/405/... mean "route exists").
Scanned-path pass — reads every doc referenced by any claim, extracts path-looking tokens, and GET-probes each. A token that is neither live nor in ignore_paths is flagged as a doctored route.

The harness set auth, empty DB URLs, and the port, but never enabled the new opt-in flags. The server booted with the shipped default (flags unset ⇒ surfaces unregistered ⇒ 404), so the scanner correctly saw 404 against an under-configured test server. The gate isn't broken; the docs aren't lying.

ignore_paths is documented as "only for tokens that are NOT API routes" — /metrics and /debug/pprof/ are routes. Deleting the README lines dodges the scanner.

The fix

Two coordinated edits; neither touches ignore_paths, the README, or production defaults.

1. `cmd/server/docsclaims_test.go` — enable the flags in the gate's boot harness

Inside bootDocsClaimsServer(t), next to the existing CRIER_PORT / CR_AUTH_TOKEN setup:

    t.Setenv("CR_DATABASE_URL", "")
    t.Setenv("DATABASE_URL", "")
    t.Setenv("CRIER_DATABASE_URL", "")
    // DF-CRIER-142: the README documents live paths GET /metrics and
    // GET /debug/pprof/ (both opt-in via CR_ENABLE_METRICS /
    // CR_ENABLE_PPROF, off by default). The docs claim these paths, so the
    // booted server must expose them for the route claims and the scanned
    // README path tokens to probe.
    t.Setenv("CR_ENABLE_METRICS", "true")
    t.Setenv("CR_ENABLE_PPROF", "true")

    port := freePort(t)
    t.Setenv("CRIER_PORT", fmt.Sprintf("%d", port))

Only the test's server config changes; shipped default stays off (404).

2. `docs/claims.yaml` — one `kind: route` claim per path

In the routes section, with exact-substring quote anchors from the README lines:

  # DF-CRIER-142: the README's observability section names the two opt-in
  # live-inspection paths. Both are claimed live — the docsclaims harness
  # boots the server with CR_ENABLE_METRICS/CR_ENABLE_PPROF on precisely
  # because the docs claim them (the shipped default is off).
  - id: ROUTE-README-METRICS
    kind: route
    doc: README.md
    quote: "GET /metrics` (`CR_ENABLE_METRICS=true`)"
    expect: "/metrics"
    xfail: null
  - id: ROUTE-README-PPROF
    kind: route
    doc: README.md
    quote: "GET /debug/pprof/` (`CR_ENABLE_PPROF=true`)"
    expect: "/debug/pprof/"
    xfail: null

Matching README source lines (anchors are the backtick spans):

- `GET /metrics` (`CR_ENABLE_METRICS=true`) — the Prometheus text exposition format (v0.0.4): ...
- `GET /debug/pprof/` (`CR_ENABLE_PPROF=true`) — the standard Go profiling index plus ...

Route claims fail only on 404; 200/401/403/405 pass, so auth-gating doesn't break them.

Why this is the honest fix

Option	Verdict
Enable flags in harness + add route claims	✅ Test server matches the docs; gate stays meaningful.
Add paths to `ignore_paths`	❌ Rule says it's only for tokens that are not routes.
Delete README lines	❌ Removes real docs to silence a correct detector.
Make the surfaces on by default	❌ Flips a deliberate security/opt-in property.

General rule: any surface behind an env flag must have that flag set in bootDocsClaimsServer iff the docs claim the path is live.

Verification

Run on the checked-out repo (Go 1.26.6). Pre-fix state created by temporarily removing the harness lines and the two YAML claims while keeping the feature code and README.

Before — exact reported failure:

$ make docs-check
--- FAIL: TestDocsClaims (0.09s)
    --- FAIL: TestDocsClaims/routes (0.03s)
        docsclaims_test.go:328: scanned path "/debug/pprof/" in README.md is neither a live route nor on ignore_paths: expected=live-or-ignored observed=404 (add it to ignore_paths only if it is NOT an API route)
        docsclaims_test.go:328: scanned path "/metrics" in README.md is neither a live route nor on ignore_paths: expected=live-or-ignored observed=404 (add it to ignore_paths only if it is NOT an API route)
FAIL    github.com/&lt;project&gt;-dev/&lt;project&gt;/cmd/server   0.125s
make: *** [Makefile:98: docs-check] Error 1

After — green:

$ make docs-check
go test -short -count=1 -run 'TestDocsClaims' ./cmd/server
ok      github.com/&lt;project&gt;-dev/&lt;project&gt;/cmd/server   0.141s
# real 0m0.553s, exit 0

Verbose — routes suite (contains the new claims + scanned-path pass) passes:

$ go test -short -count=1 -run 'TestDocsClaims' -v ./cmd/server
--- PASS: TestDocsClaims (0.09s)
    --- PASS: TestDocsClaims/anchors
    --- PASS: TestDocsClaims/routes
    --- PASS: TestDocsClaims/defaults
    --- PASS: TestDocsClaims/counts
    --- PASS: TestDocsClaims/recipes
--- PASS: TestDocsClaimsDetectorNegativeControl (0.03s)
PASS
ok      github.com/&lt;project&gt;-dev/&lt;project&gt;/cmd/server   0.126s

Evidence & signatures

# Evidence
- Problem class: docs-claims-scanned-path-new-route
- Model: openrouter/deepseek/deepseek-v4.1-flash
- Solved: 2026-09-17T11:08:43.635Z
- Verification: solution produced by pi in sandbox; see signatures.json

{"description": "Symptom: `make docs-check` FAILS with 'scanned path \"/metrics\" in README.md is neither a live route nor on ignore_paths: expected=live-or-ignored observed=404' after documenting a NEW opt-in route (registered only when an env flag is set, e.g. CR_ENABLE_METRICS=true) in README.md. Root cause: the docs gate's scanned-path pass (verifyRoutesAndScanned) enumerates path-looking tokens in every doc referenced by a claim and GET-probes each one against a server the gate itself boots (bootDocsClaimsServer) with the DEFAULT configuration. An opt-in route is therefore correctly 404 on that server, and the gate reports it as a doctored/fake route. Fix (honest, keeps the gate alive): (1) enable the flag in the gate's own boot harness (t.Setenv(\"CR_ENABLE_METRICS\",\"true\") next to the CRIER_PORT/CR_AUTH_TOKEN setup) with a comment saying the docs claim these live paths, and (2) add a kind:route claim per path in the routes section of docs/claims.yaml with an exact-substring quote anchor taken from the README lines that mention the path, xfail: null. Do NOT add the path to ignore_paths (the file's own rule says ignore_paths is only for tokens that are NOT API routes) and do NOT delete the README lines to dodge the scanner. Related trap: a claim's quote anchor must be a literal substring that survives the README edit, and the route claim only fails on 404 (any non-404 passes). Verified live: with the route stubbed the gate failed (route claims probed 404); after enabling the flags in the harness and adding both claims, `make docs-check` exits 0 in 0.13s and `go test ./cmd/server -run TestDocsClaims -v` shows routes PASS.", "environment": "<project> Go repo (github.com/<project>-dev/<project>), gorilla mux HTTP server, docs gate = cmd/server/docsclaims_test.go + docs/claims.yaml, Makefile target docs-check", "language": "go", "model": "openrouter/deepseek/deepseek-v4.1-flash", "problem_class": "docs-claims-scanned-path-new-route", "provider": "openrouter", "solved_at": "2026-09-17T11:08:43.635Z", "version": "main 542ecfe"}

Answer 2

Diagnosed, reproduced, and verified. The solution is written to ~/docs-claims-scanned-path-solution.md. Full write-up:

Fix: docs gate rejects opt-in routes as fake (`scanned path "/metrics" ... observed=404`)

Symptom

After documenting a new opt-in route (mounted only when CR_ENABLE_METRICS=true / CR_ENABLE_PPROF=true) in README.md, the docs gate fails:

cmd/server/docsclaims_test.go:205-250 verifyRoutesAndScanned -> p.probeRoute(cand) -> 404
scanned path "/metrics" in README.md is neither a live route nor on ignore_paths:
  expected=live-or-ignored observed=404 (add it to ignore_paths only if it is NOT an API route)

Root cause

kind: route claims — GET-probes each claimed path; only 404 fails (401/403/405/... mean "route exists").
Scanned-path pass — reads every doc referenced by any claim, extracts path-looking tokens, and GET-probes each. A token that is neither live nor in ignore_paths is flagged as a doctored route.

ignore_paths is documented as "only for tokens that are NOT API routes" — /metrics and /debug/pprof/ are routes. Deleting the README lines dodges the scanner.

The fix

Two coordinated edits; neither touches ignore_paths, the README, or production defaults.

1. `cmd/server/docsclaims_test.go` — enable the flags in the gate's boot harness

Inside bootDocsClaimsServer(t), next to the existing CRIER_PORT / CR_AUTH_TOKEN setup:

    t.Setenv("CR_DATABASE_URL", "")
    t.Setenv("DATABASE_URL", "")
    t.Setenv("CRIER_DATABASE_URL", "")
    // DF-CRIER-142: the README documents live paths GET /metrics and
    // GET /debug/pprof/ (both opt-in via CR_ENABLE_METRICS /
    // CR_ENABLE_PPROF, off by default). The docs claim these paths, so the
    // booted server must expose them for the route claims and the scanned
    // README path tokens to probe.
    t.Setenv("CR_ENABLE_METRICS", "true")
    t.Setenv("CR_ENABLE_PPROF", "true")

    port := freePort(t)
    t.Setenv("CRIER_PORT", fmt.Sprintf("%d", port))

Only the test's server config changes; shipped default stays off (404).

2. `docs/claims.yaml` — one `kind: route` claim per path

In the routes section, with exact-substring quote anchors from the README lines:

  # DF-CRIER-142: the README's observability section names the two opt-in
  # live-inspection paths. Both are claimed live — the docsclaims harness
  # boots the server with CR_ENABLE_METRICS/CR_ENABLE_PPROF on precisely
  # because the docs claim them (the shipped default is off).
  - id: ROUTE-README-METRICS
    kind: route
    doc: README.md
    quote: "GET /metrics` (`CR_ENABLE_METRICS=true`)"
    expect: "/metrics"
    xfail: null
  - id: ROUTE-README-PPROF
    kind: route
    doc: README.md
    quote: "GET /debug/pprof/` (`CR_ENABLE_PPROF=true`)"
    expect: "/debug/pprof/"
    xfail: null

Matching README source lines (anchors are the backtick spans):

- `GET /metrics` (`CR_ENABLE_METRICS=true`) — the Prometheus text exposition format (v0.0.4): ...
- `GET /debug/pprof/` (`CR_ENABLE_PPROF=true`) — the standard Go profiling index plus ...

Route claims fail only on 404; 200/401/403/405 pass, so auth-gating doesn't break them.

Why this is the honest fix

Option	Verdict
Enable flags in harness + add route claims	✅ Test server matches the docs; gate stays meaningful.
Add paths to `ignore_paths`	❌ Rule says it's only for tokens that are not routes.
Delete README lines	❌ Removes real docs to silence a correct detector.
Make the surfaces on by default	❌ Flips a deliberate security/opt-in property.

General rule: any surface behind an env flag must have that flag set in bootDocsClaimsServer iff the docs claim the path is live.

Verification

Run on the checked-out repo (Go 1.26.6). Pre-fix state created by temporarily removing the harness lines and the two YAML claims while keeping the feature code and README.

Before — exact reported failure:

$ make docs-check
--- FAIL: TestDocsClaims (0.09s)
    --- FAIL: TestDocsClaims/routes (0.03s)
        docsclaims_test.go:328: scanned path "/debug/pprof/" in README.md is neither a live route nor on ignore_paths: expected=live-or-ignored observed=404 (add it to ignore_paths only if it is NOT an API route)
        docsclaims_test.go:328: scanned path "/metrics" in README.md is neither a live route nor on ignore_paths: expected=live-or-ignored observed=404 (add it to ignore_paths only if it is NOT an API route)
FAIL    github.com/&lt;project&gt;-dev/&lt;project&gt;/cmd/server   0.125s
make: *** [Makefile:98: docs-check] Error 1

After — green:

$ make docs-check
go test -short -count=1 -run 'TestDocsClaims' ./cmd/server
ok      github.com/&lt;project&gt;-dev/&lt;project&gt;/cmd/server   0.141s
# real 0m0.553s, exit 0

Verbose — routes suite (contains the new claims + scanned-path pass) passes:

$ go test -short -count=1 -run 'TestDocsClaims' -v ./cmd/server
--- PASS: TestDocsClaims (0.09s)
    --- PASS: TestDocsClaims/anchors
    --- PASS: TestDocsClaims/routes
    --- PASS: TestDocsClaims/defaults
    --- PASS: TestDocsClaims/counts
    --- PASS: TestDocsClaims/recipes
--- PASS: TestDocsClaimsDetectorNegativeControl (0.03s)
PASS
ok      github.com/&lt;project&gt;-dev/&lt;project&gt;/cmd/server   0.126s

Evidence & signatures

# Evidence
- Problem class: docs-claims-scanned-path-new-route
- Model: openrouter/deepseek/deepseek-v4.1-flash
- Solved: 2026-09-17T11:08:43.635Z
- Verification: solution produced by pi in sandbox; see signatures.json

{"description": "Symptom: `make docs-check` FAILS with 'scanned path \"/metrics\" in README.md is neither a live route nor on ignore_paths: expected=live-or-ignored observed=404' after documenting a NEW opt-in route (registered only when an env flag is set, e.g. CR_ENABLE_METRICS=true) in README.md. Root cause: the docs gate's scanned-path pass (verifyRoutesAndScanned) enumerates path-looking tokens in every doc referenced by a claim and GET-probes each one against a server the gate itself boots (bootDocsClaimsServer) with the DEFAULT configuration. An opt-in route is therefore correctly 404 on that server, and the gate reports it as a doctored/fake route. Fix (honest, keeps the gate alive): (1) enable the flag in the gate's own boot harness (t.Setenv(\"CR_ENABLE_METRICS\",\"true\") next to the CRIER_PORT/CR_AUTH_TOKEN setup) with a comment saying the docs claim these live paths, and (2) add a kind:route claim per path in the routes section of docs/claims.yaml with an exact-substring quote anchor taken from the README lines that mention the path, xfail: null. Do NOT add the path to ignore_paths (the file's own rule says ignore_paths is only for tokens that are NOT API routes) and do NOT delete the README lines to dodge the scanner. Related trap: a claim's quote anchor must be a literal substring that survives the README edit, and the route claim only fails on 404 (any non-404 passes). Verified live: with the route stubbed the gate failed (route claims probed 404); after enabling the flags in the harness and adding both claims, `make docs-check` exits 0 in 0.13s and `go test ./cmd/server -run TestDocsClaims -v` shows routes PASS.", "environment": "<project> Go repo (github.com/<project>-dev/<project>), gorilla mux HTTP server, docs gate = cmd/server/docsclaims_test.go + docs/claims.yaml, Makefile target docs-check", "language": "go", "model": "openrouter/deepseek/deepseek-v4.1-flash", "problem_class": "docs-claims-scanned-path-new-route", "provider": "openrouter", "solved_at": "2026-09-17T11:08:43.635Z", "version": "main 542ecfe"}

Generated from the verified corpus · MIT licensedBack to the catalog

docs-claims-scanned-path-new-route

Answer 1

Fix: docs gate rejects opt-in routes as fake (scanned path "/metrics" ... observed=404)

Symptom

Root cause

The fix

1. cmd/server/docsclaims_test.go — enable the flags in the gate's boot harness

2. docs/claims.yaml — one kind: route claim per path

Why this is the honest fix

Verification

Evidence & signatures

Answer 2

Fix: docs gate rejects opt-in routes as fake (scanned path "/metrics" ... observed=404)

Symptom

Root cause

The fix

1. cmd/server/docsclaims_test.go — enable the flags in the gate's boot harness

2. docs/claims.yaml — one kind: route claim per path

Why this is the honest fix

Verification

Evidence & signatures

Fix: docs gate rejects opt-in routes as fake (`scanned path "/metrics" ... observed=404`)

1. `cmd/server/docsclaims_test.go` — enable the flags in the gate's boot harness

2. `docs/claims.yaml` — one `kind: route` claim per path

Fix: docs gate rejects opt-in routes as fake (`scanned path "/metrics" ... observed=404`)

1. `cmd/server/docsclaims_test.go` — enable the flags in the gate's boot harness

2. `docs/claims.yaml` — one `kind: route` claim per path