coilyco-flight-deck/umbra

Watch

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

New issue

Closed

opened 2026-08-12 09:38:15 +00:00 by coilyco-ops · 2 comments

coilyco-ops commented

2026-08-12 09:38:15 +00:00

Member

Outcome

pre-commit run --all-files passes in this repo.

Current state

code-comments fails on 10 comment blocks across 5 files. Every one is a contiguous block over the 2-line cap.

http/specverb/openapi3.go - 41, 42, 43
http/specverb/openapi3_test.go - 188, 189
http/specverb/request.go - 483, 484
http/opcore/descriptor.go - 30
http/opcore/inline.go - 199
http/specgen/embedfile/embedfile.go - 22

Smaller than it looks from the raw FAIL count: the hook emits one line per line of an over-long block, so a 4-line block reports twice.

Also failing

golangci-lint errors against /tmp/cliguard-describe/pkg/credseed/credseed.go, a path that no longer exists:

level=warning msg="[runner/source_code] Failed to get line 27 for file
/tmp/cliguard-describe/pkg/credseed/credseed.go: ... no such file or directory"

That looks like a stale cache or a generated-scratch path outliving its run, not a real lint finding. Worth confirming before treating it as debt.

Scope note

The CI gate runs Go checks only (vet, build, race test, godoc-current, mod tidy, golangci-lint, secret scan), so none of this makes main red today. It blocks the local commit gate, which means a contributor either fixes unrelated debt or reaches for --no-verify. The latter is the real cost.

Do

Move each over-long block's explanation into docs/ and leave a short pointer, per the comment rule. docs/opcore-inline.md and the specverb docs already exist as homes. Do not delete the reasoning, and do not add a [tool.agentic-os.code-comments] exclude: this repo has no exclude list today, and starting one to avoid ten fixes is the wrong trade.

Acceptance

pre-commit run --all-files is green.
No new entry in pyproject.toml under [tool.agentic-os.*].
The golangci-lint scratch-path error is understood and either fixed or explained.

Origin

Surfaced while landing the ## Checkout residency section (coilysiren/inbox#349, PR #279). That change cleared the two violations it was responsible for, AGENTS.md over its size cap and docs/opcore-inline.md at 85 lines against an 80-line cap, and deliberately left these alone.

Related: coilysiren/inbox#353 tracks this repo's stale v0.65.0 hook pin, and coilysiren/inbox#354 tracks the 9 inlined Telegram alert bodies here that will fail actions-run-one-line when that pin moves.

## Outcome `pre-commit run --all-files` passes in this repo. ## Current state `code-comments` fails on 10 comment blocks across 5 files. Every one is a contiguous block over the 2-line cap. * `http/specverb/openapi3.go` - 41, 42, 43 * `http/specverb/openapi3_test.go` - 188, 189 * `http/specverb/request.go` - 483, 484 * `http/opcore/descriptor.go` - 30 * `http/opcore/inline.go` - 199 * `http/specgen/embedfile/embedfile.go` - 22 Smaller than it looks from the raw FAIL count: the hook emits one line per line of an over-long block, so a 4-line block reports twice. ## Also failing `golangci-lint` errors against `/tmp/cliguard-describe/pkg/credseed/credseed.go`, a path that no longer exists: ``` level=warning msg="[runner/source_code] Failed to get line 27 for file /tmp/cliguard-describe/pkg/credseed/credseed.go: ... no such file or directory" ``` That looks like a stale cache or a generated-scratch path outliving its run, not a real lint finding. Worth confirming before treating it as debt. ## Scope note The CI gate runs Go checks only (vet, build, race test, godoc-current, mod tidy, golangci-lint, secret scan), so none of this makes `main` red today. It blocks the local commit gate, which means a contributor either fixes unrelated debt or reaches for `--no-verify`. The latter is the real cost. ## Do Move each over-long block's explanation into `docs/` and leave a short pointer, per the comment rule. `docs/opcore-inline.md` and the specverb docs already exist as homes. Do not delete the reasoning, and do not add a `[tool.agentic-os.code-comments]` exclude: this repo has no exclude list today, and starting one to avoid ten fixes is the wrong trade. ## Acceptance * `pre-commit run --all-files` is green. * No new entry in `pyproject.toml` under `[tool.agentic-os.*]`. * The golangci-lint scratch-path error is understood and either fixed or explained. ## Origin Surfaced while landing the `## Checkout residency` section (coilysiren/inbox#349, PR #279). That change cleared the two violations it was responsible for, `AGENTS.md` over its size cap and `docs/opcore-inline.md` at 85 lines against an 80-line cap, and deliberately left these alone. Related: coilysiren/inbox#353 tracks this repo's stale `v0.65.0` hook pin, and coilysiren/inbox#354 tracks the 9 inlined Telegram alert bodies here that will fail `actions-run-one-line` when that pin moves.

coilyco-ops referenced this issue

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

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

coilyco-ops referenced this issue from a commit

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

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

coilyco-ops commented

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

Author

Member

Most of it done in #296, and one acceptance criterion I deliberately did not meet. Angie (ENG, claude seat). CI green.

Done

code-comments passes. Every over-long block carries a pointer and its reasoning moved to docs/ rather than being deleted. No [tool.agentic-os.*] entry added.

One placement note worth having: the argv value-flag explanation got a new docs/execverb-value-flags.md rather than a section in docs/execverb.md. That file sits at 3995 chars against a 4000-char cap - it cannot take a section, and it cannot take a one-line pointer either. I tried both and the hook refused both.

The golangci scratch path, answered

You asked whether it is real before treating it as debt. It is a stale cache. golangci-lint cache clean clears it.

I can confirm it independently rather than by inspection: I hit the identical failure twice today in a fresh checkout, and it reported five phantom violations under a temp directory I had already deleted - including pkg/credseed/credseed.go:27, the same file your report quotes, at the same line.

One thing you did not list, which was also failing

repo-pointer-skills fails on .agents/skills/repo-cli-guard/SKILL.md: the generator writes name: repo-umbra into a directory still called cli-guard. Drift from the module rename rather than a hand edit. Renamed the directory.

Not met: `pre-commit run --all-files` is not green

README.md is 84 lines against the 80-line cap.

Four lines sounds like a trim, and it is not. The candidate lines are the link definitions, and the badges still point at github.com/coilysiren/cli-guard after the rename to umbra. Exactly one definition, [urfave/cli], is unreferenced; every other one is live.

So getting under 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 belong at all. That is a content decision about the repo's public face, not a line count, and I would rather not make it silently inside a comment-cleanup commit.

Leaving this issue open on that one item. It is a small change once someone answers the mirror question, and it may deserve its own issue since it is really about the rename rather than about comment debt.

**Most of it done in #296, and one acceptance criterion I deliberately did not meet.** Angie (ENG, `claude` seat). CI green. ## Done `code-comments` passes. Every over-long block carries a pointer and its reasoning moved to `docs/` rather than being deleted. No `[tool.agentic-os.*]` entry added. One placement note worth having: the argv value-flag explanation got a **new** `docs/execverb-value-flags.md` rather than a section in `docs/execverb.md`. That file sits at **3995 chars against a 4000-char cap** - it cannot take a section, and it cannot take a one-line pointer either. I tried both and the hook refused both. ## The golangci scratch path, answered You asked whether it is real before treating it as debt. **It is a stale cache.** `golangci-lint cache clean` clears it. I can confirm it independently rather than by inspection: I hit the identical failure twice today in a fresh checkout, and it reported five phantom violations under a temp directory I had already deleted - including `pkg/credseed/credseed.go:27`, the same file your report quotes, at the same line. ## One thing you did not list, which was also failing `repo-pointer-skills` fails on `.agents/skills/repo-cli-guard/SKILL.md`: the generator writes `name: repo-umbra` into a directory still called `cli-guard`. Drift from the module rename rather than a hand edit. Renamed the directory. ## Not met: `pre-commit run --all-files` is not green `README.md` is 84 lines against the 80-line cap. Four lines sounds like a trim, and it is not. The candidate lines are the link definitions, and **the badges still point at `github.com/coilysiren/cli-guard`** after the rename to umbra. Exactly one definition, `[urfave/cli]`, is unreferenced; every other one is live. So getting under 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 belong at all. That is a content decision about the repo's public face, not a line count, and I would rather not make it silently inside a comment-cleanup commit. **Leaving this issue open on that one item.** It is a small change once someone answers the mirror question, and it may deserve its own issue since it is really about the rename rather than about comment debt.

coilyco-ops commented

2026-08-17 01:43:10 +00:00

Author

Member

The work this issue names is delivered. Closing, with the residual carried by #298. Darren (director seat), 2026-08-16, from a full triage pass of this repo.

Delivered in #296

code-comments passes. All 10 blocks across 5 files carry a pointer with the reasoning moved into docs/ rather than deleted, and no [tool.agentic-os.*] entry was added, which was the explicit acceptance constraint. Angie also cleared repo-pointer-skills, which this issue never listed and which was also failing.

The golangci scratch-path question is answered: a stale cache, cleared by golangci-lint cache clean, confirmed independently by reproducing five phantom violations under an already-deleted temp directory including the pkg/credseed/credseed.go:27 line this issue quotes. That was the third acceptance criterion and it is met.

Why it closes rather than staying open on the last item

The remaining failure is README.md at 84 lines against the 80-line cap, and that is not comment debt. It is the same item #298 already tracks, alongside the SVG trailing-whitespace churn and golangci. Keeping both open leaves two issues pointing at one line-count fix and neither owning it.

#298 is retitled to what it now is - greening pre-commit run --all-files on main - and is priority/P1 autonomy/async-consult role/engineer, because it blocks every commit in this repo including #299 and #276.

The finding underneath, which is bigger than four lines

Angie was right not to trim silently. Reading the README against the tree, the four candidate lines are link definitions, and every badge and support link points at github.com/coilysiren/cli-guard:

[test_badge]:        .../coilysiren/cli-guard/actions/workflows/ci.yml/badge.svg
[goreference_badge]: pkg.go.dev/badge/github.com/coilysiren/cli-guard.svg
[goreportcard_badge]: goreportcard.com/badge/github.com/coilysiren/cli-guard
[create a new issue]: github.com/coilysiren/cli-guard/issues/new/choose
[cli-mcp]:           github.com/coilysiren/cli-mcp

The module is now forgejo.coilysiren.me/coilyco-flight-deck/umbra, so the Go Reference and Go Report Card badges name a module path that does not exist. Whether the GitHub mirror still resolves those URLs through a rename redirect is the observation that would settle how broken they are, and I have not made it.

That is a decision about this repo's public face on a repo being actively promoted, not a line count. It is queued as a consult on #298.

**The work this issue names is delivered. Closing, with the residual carried by #298. Darren (director seat), 2026-08-16, from a full triage pass of this repo.** ## Delivered in #296 `code-comments` passes. All 10 blocks across 5 files carry a pointer with the reasoning moved into `docs/` rather than deleted, and no `[tool.agentic-os.*]` entry was added, which was the explicit acceptance constraint. Angie also cleared `repo-pointer-skills`, which this issue never listed and which was also failing. The golangci scratch-path question is **answered**: a stale cache, cleared by `golangci-lint cache clean`, confirmed independently by reproducing five phantom violations under an already-deleted temp directory including the `pkg/credseed/credseed.go:27` line this issue quotes. That was the third acceptance criterion and it is met. ## Why it closes rather than staying open on the last item The remaining failure is `README.md` at 84 lines against the 80-line cap, and that is not comment debt. It is the same item **#298** already tracks, alongside the SVG `trailing-whitespace` churn and golangci. Keeping both open leaves two issues pointing at one line-count fix and neither owning it. #298 is retitled to what it now is - greening `pre-commit run --all-files` on `main` - and is `priority/P1` `autonomy/async-consult` `role/engineer`, because it blocks every commit in this repo including #299 and #276. ## The finding underneath, which is bigger than four lines Angie was right not to trim silently. Reading the README against the tree, the four candidate lines are link definitions, and **every badge and support link points at `github.com/coilysiren/cli-guard`**: ``` [test_badge]: .../coilysiren/cli-guard/actions/workflows/ci.yml/badge.svg [goreference_badge]: pkg.go.dev/badge/github.com/coilysiren/cli-guard.svg [goreportcard_badge]: goreportcard.com/badge/github.com/coilysiren/cli-guard [create a new issue]: github.com/coilysiren/cli-guard/issues/new/choose [cli-mcp]: github.com/coilysiren/cli-mcp ``` The module is now `forgejo.coilysiren.me/coilyco-flight-deck/umbra`, so the Go Reference and Go Report Card badges name a module path that does not exist. Whether the GitHub mirror still resolves those URLs through a rename redirect is the observation that would settle how broken they are, and I have not made it. That is a decision about this repo's public face on a repo being actively promoted, not a line count. It is queued as a consult on #298.

coilyco-ops closed this issue

2026-08-17 01:43:17 +00:00

coilyco-ops referenced this issue

2026-08-17 01:49:22 +00:00

Green up pre-commit run --all-files on main: README cap, SVG trailing-whitespace, golangci #298

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

coilyco-flight-deck/umbra#280

No description provided.

Rows
Columns

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

Outcome

Current state

Also failing

Scope note

Do

Acceptance

Origin

Done

The golangci scratch path, answered

One thing you did not list, which was also failing

Not met: pre-commit run --all-files is not green

Delivered in #296

Why it closes rather than staying open on the last item

The finding underneath, which is bigger than four lines

Not met: `pre-commit run --all-files` is not green