chore(comments): move the over-long blocks into docs, and fix the skill drift

coilyco-ops commented

2026-08-16 04:09:31 +00:00

Member

Refs #280. Stacked on #294 - both touch http/specverb/openapi3.go, so merge that one first.

Comment blocks

code-comments passes. Every over-long block now carries a pointer and its reasoning lives in docs/, per the rule and the issue's instruction not to delete it.

The argv value-flag explanation got a new docs/execverb-value-flags.md rather than a section in docs/execverb.md. That doc sits at 3995 chars against a 4000-char cap, so it cannot take a section - it cannot even take a one-line pointer. Worth knowing before anyone tries to extend it.

No [tool.agentic-os.*] entry added, as the issue asked.

The skill drift

.agents/skills/repo-cli-guard renamed to repo-umbra. The generator has written name: repo-umbra into a directory still called cli-guard since the module rename, so repo-pointer-skills failed on a mismatch nobody introduced by hand. Now green.

The golangci scratch path, answered

The issue asks whether it is real. It is a stale cache, not debt. It reports files under paths that no longer exist, and golangci-lint cache clean clears it. I hit the identical thing twice today, reporting five phantom violations under a temp checkout I had deleted - including pkg/credseed/credseed.go:27, the same file the issue quotes.

Not green yet, and why I stopped

README.md is 84 lines against an 80-line cap. Four lines is a small trim, but the lines available are stale link definitions: the badges still point at github.com/coilysiren/cli-guard after the rename to umbra, and exactly one definition ([urfave/cli]) is unreferenced.

So trimming to the cap means deciding what the README should claim about itself post-rename - whether the GitHub mirror is still at that path, and whether those badges should exist at all. That is a content decision rather than a line count, and it wants its own change rather than riding in on a comment cleanup.

So #280's acceptance is not fully met and I have left it open rather than claiming it.

Verification

make vet, go test ./http/... ./cli/... green. godoc-current.txt regenerated. pre-commit clean apart from the README above.

I also left the three assets/mark/umbra-favicon-*.svg whitespace autofixes out again - pre-commit keeps offering them and they belong to #290, not here.

Refs #280. **Stacked on #294** - both touch `http/specverb/openapi3.go`, so merge that one first. ## Comment blocks `code-comments` passes. Every over-long block now carries a pointer and its reasoning lives in `docs/`, per the rule and the issue's instruction not to delete it. The argv value-flag explanation got a **new** `docs/execverb-value-flags.md` rather than a section in `docs/execverb.md`. That doc sits at 3995 chars against a 4000-char cap, so it cannot take a section - it cannot even take a one-line pointer. Worth knowing before anyone tries to extend it. No `[tool.agentic-os.*]` entry added, as the issue asked. ## The skill drift `.agents/skills/repo-cli-guard` renamed to `repo-umbra`. The generator has written `name: repo-umbra` into a directory still called `cli-guard` since the module rename, so `repo-pointer-skills` failed on a mismatch nobody introduced by hand. Now green. ## The golangci scratch path, answered The issue asks whether it is real. **It is a stale cache, not debt.** It reports files under paths that no longer exist, and `golangci-lint cache clean` clears it. I hit the identical thing twice today, reporting five phantom violations under a temp checkout I had deleted - including `pkg/credseed/credseed.go:27`, the same file the issue quotes. ## Not green yet, and why I stopped `README.md` is 84 lines against an 80-line cap. Four lines is a small trim, but the lines available are stale link definitions: the badges still point at `github.com/coilysiren/cli-guard` after the rename to umbra, and exactly one definition (`[urfave/cli]`) is unreferenced. So trimming to the cap means deciding what the README should claim about itself post-rename - whether the GitHub mirror is still at that path, and whether those badges should exist at all. That is a content decision rather than a line count, and it wants its own change rather than riding in on a comment cleanup. **So #280's acceptance is not fully met** and I have left it open rather than claiming it. ## Verification `make vet`, `go test ./http/... ./cli/...` green. `godoc-current.txt` regenerated. `pre-commit` clean apart from the README above. I also left the three `assets/mark/umbra-favicon-*.svg` whitespace autofixes out again - pre-commit keeps offering them and they belong to #290, not here.

coilyco-ops added 2 commits

2026-08-16 04:09:31 +00:00

fix(specverb): a response offering JSON is parsed, not raw

ci / secrets (pull_request) Successful in 8s

Details

ci / test (pull_request) Successful in 42s

Details

ci / lint (pull_request) Successful in 29s

Details

92afd48af7

#291 read "any non-JSON media type" as raw. A Swagger 2.0 shared $ref
response inherits the document's root produces, and Forgejo's root lists
text/html beside application/json, so every object read in the fleet was
classified raw and --query was refused on all of them.

Raw now means offering no JSON at all. A response listing JSON beside
something else is negotiating content rather than declaring bytes, which
is the fail-safe direction docs/specverb-raw-responses.md already argued
for and the one Darren proposed on the report.

Checked against the vendored Forgejo snapshot rather than a synthetic:
repoGet carries [application/json text/html] and is parsed again, while
repoGetActionJobLogs and repoGetActionRunLogs stay raw. Both halves of
the issue's acceptance hold.

The regression test uses a shared $ref response, because my first attempt
declared the media types inline and passed without the fix. Inline
produces is honoured; the $ref path is where the root leaks in, and a
test that does not reproduce is worse than none.

Closes #293

Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>

chore(comments): move the over-long blocks into docs, and fix the skill drift

ci / test (pull_request) Successful in 41s

Details

ci / lint (pull_request) Successful in 29s

Details

ci / secrets (pull_request) Successful in 6s

Details

46a2e8644c

Every contiguous comment block over the 2-line cap now carries a pointer
and the reasoning lives in docs/, per the rule. Nothing was deleted.

The argv value-flag table's explanation, including why dropping an entry
silently weakens an argN guard, moved to a new docs/execverb-value-flags.md
rather than into docs/execverb.md, which sits 5 chars under its char cap
and cannot take a pointer let alone a section.

.agents/skills/repo-cli-guard is renamed to repo-umbra. The generator has
been writing `name: repo-umbra` into a directory still called cli-guard
since the module rename, so the pointer-skill hook failed on a mismatch
nobody introduced by hand.

The golangci-lint scratch-path error the issue asks about is a stale
cache, not debt. It reports files under paths that no longer exist, and
`golangci-lint cache clean` clears it. I hit the same thing twice today
against a deleted temp checkout.

Still failing, and deliberately not fixed here: README.md is 84 lines
against an 80-line cap. Trimming it means deciding what its badges should
say, because they still point at github.com/coilysiren/cli-guard after
the rename to umbra. That is a content decision rather than a line count,
so it wants its own change.

Refs #280

Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>

coilyco-ops requested review from coilysiren

2026-08-16 04:09:31 +00:00

coilyco-ops referenced this pull request

2026-08-16 04:11:26 +00:00

Clear the code-comments violations blocking a green local gate #280