coilyco-flight-deck/umbra

Watch

main is red on code-comments and catalog-doc-size under the pinned catalog rev #330

New issue

Closed

opened 2026-08-27 05:00:17 +00:00 by coilyco-ops · 1 comment

coilyco-ops commented

2026-08-27 05:00:17 +00:00

Owner

Found while landing #304. pre-commit run --all-files on a clean main (5e27572) fails before any change is made:

code-comments - 18 failures. Contiguous comment blocks over the 2-line cap in cli/execverb/action_run.go, http/opcore/binder.go, http/opcore/body_mapping.go, http/opcore/body_pin_test.go, http/specverb/action.go, and others.
catalog-doc-size and documentation-layout - docs/specverb-actions.md at 83 lines against an 80-line cap and 6992 chars against a 4000-char cap.

None of it relates to #304, and a commit only runs the hooks over its own changed files, so #304 landed clean without touching any of it. The backlog only bites a change that edits one of those files, and it bites silently until then.

Two things worth deciding together:

Whether the comment blocks get split or the affected files get a scoped opt-out. The cap is about comment volume rather than correctness, and several of these blocks look like they are carrying real constraints that the surrounding code cannot say.
docs/specverb-actions.md is a single doc at 175 percent of its char cap. The validator's own remedy is a split, and umbra's docs count is well under its band's ceiling, so a split is available here in a way it is not in agentic-os.

Filing rather than fixing, since both are judgment calls about someone else's prose and neither blocks any current work.

Found while landing #304. `pre-commit run --all-files` on a clean `main` (5e27572) fails before any change is made: * `code-comments` - 18 failures. Contiguous comment blocks over the 2-line cap in `cli/execverb/action_run.go`, `http/opcore/binder.go`, `http/opcore/body_mapping.go`, `http/opcore/body_pin_test.go`, `http/specverb/action.go`, and others. * `catalog-doc-size` and `documentation-layout` - `docs/specverb-actions.md` at 83 lines against an 80-line cap and 6992 chars against a 4000-char cap. None of it relates to #304, and a commit only runs the hooks over its own changed files, so #304 landed clean without touching any of it. The backlog only bites a change that edits one of those files, and it bites silently until then. Two things worth deciding together: * Whether the comment blocks get split or the affected files get a scoped opt-out. The cap is about comment volume rather than correctness, and several of these blocks look like they are carrying real constraints that the surrounding code cannot say. * `docs/specverb-actions.md` is a single doc at 175 percent of its char cap. The validator's own remedy is a split, and umbra's docs count is well under its band's ceiling, so a split is available here in a way it is not in agentic-os. Filing rather than fixing, since both are judgment calls about someone else's prose and neither blocks any current work.

coilyco-ops referenced this issue

2026-08-27 05:02:25 +00:00

valuesource: the env provider does not trim, so a trailing newline reaches the auth header and Go refuses the request #304

coilyco-ops commented

2026-08-28 04:23:58 +00:00

Author

Owner

Resolved by `5c292bc`. Verified on a fresh clone of `main`, not inferred.

code-comments check: OK
documentation-layout check: OK
pre-commit run --all-files -> exit 0

Both of this issue's judgment calls got answered, and one of them differently than the issue expected.

The 18 comment blocks: split, no opt-out

They were trimmed to the two-line cap keeping the load-bearing half, across exactly the files named here: cli/execverb/action_run.go, http/opcore/binder.go, http/opcore/body_mapping.go, http/opcore/body_pin_test.go, http/specverb/action.go, plus http/specverb/action_test.go, http/specverb/deny.go, http/specverb/specverb.go and pkg/stepflow/stepflow.go. No scoped opt-out was taken.

The instinct here that "several of these blocks look like they are carrying real constraints the surrounding code cannot say" was right, and that is what the trim preserved: each kept its non-obvious claim and dropped the restatement around it.

`docs/specverb-actions.md`: not split, and it did not need to be

The file is byte-for-byte unchanged. It is still 83 lines and 6,992 chars. What changed is the cap it answers to.

This issue measured it against 80 lines / 4,000 chars, which is the pre-band flat cap. umbra's band was small, and that was rollout residue from the agentic-os#1108 sweep rather than a decision: it declared small while carrying 22 docs against that band's 20-doc cap. Re-picked to large, the caps are 120 / 8,000 and this page is comfortably inside both.

So the validator's own remedy, a split, would have fragmented a page that was never actually too long. The real defect was a band nobody had chosen. Worth remembering as a shape: a size violation under a wrong band is a config bug wearing a content bug's clothes.

Two things this issue could not have known

313 of what looked like umbra's comment debt was never umbra's. A /* inside the glob ~/.ward/audit/*.jsonl in a Go raw string opened a phantom block comment in examples/treebuilders/treebuilders.go, giving 313 violations against 12 real comment lines. Fixed upstream in coilyco-flight-deck/agentic-os#1335. The 18 counted here were the genuine ones all along, which is why that number matched exactly.

The pin has also moved on. This issue's title frames the redness as "under the pinned catalog rev", and that pin advanced from v0.65.0, a CLI-train tag this repo was tracking by accident, to aos-precommit-v0.54.0.

One trap worth recording

golangci-lint reported a failure on this verification run that was not real: its cache keys results to absolute paths, and it was replaying findings against a scratch directory that no longer exists. golangci-lint cache clean cleared it and the run went green. It has now produced a convincing false failure twice in one session, so it is worth suspecting whenever the reported path is not one you are working in.

Closing.

## Resolved by `5c292bc`. Verified on a fresh clone of `main`, not inferred. ``` code-comments check: OK documentation-layout check: OK pre-commit run --all-files -> exit 0 ``` Both of this issue's judgment calls got answered, and one of them differently than the issue expected. ### The 18 comment blocks: split, no opt-out They were trimmed to the two-line cap keeping the load-bearing half, across exactly the files named here: `cli/execverb/action_run.go`, `http/opcore/binder.go`, `http/opcore/body_mapping.go`, `http/opcore/body_pin_test.go`, `http/specverb/action.go`, plus `http/specverb/action_test.go`, `http/specverb/deny.go`, `http/specverb/specverb.go` and `pkg/stepflow/stepflow.go`. No scoped opt-out was taken. The instinct here that "several of these blocks look like they are carrying real constraints the surrounding code cannot say" was right, and that is what the trim preserved: each kept its non-obvious claim and dropped the restatement around it. ### `docs/specverb-actions.md`: not split, and it did not need to be **The file is byte-for-byte unchanged. It is still 83 lines and 6,992 chars.** What changed is the cap it answers to. This issue measured it against 80 lines / 4,000 chars, which is the pre-band flat cap. umbra's band was `small`, and that was rollout residue from the agentic-os#1108 sweep rather than a decision: it declared `small` while carrying 22 docs against that band's 20-doc cap. Re-picked to `large`, the caps are 120 / 8,000 and this page is comfortably inside both. So the validator's own remedy, a split, would have fragmented a page that was never actually too long. The real defect was a band nobody had chosen. Worth remembering as a shape: **a size violation under a wrong band is a config bug wearing a content bug's clothes.** ### Two things this issue could not have known `313` of what looked like umbra's comment debt was never umbra's. A `/*` inside the glob `~/.ward/audit/*.jsonl` in a Go raw string opened a phantom block comment in `examples/treebuilders/treebuilders.go`, giving 313 violations against 12 real comment lines. Fixed upstream in coilyco-flight-deck/agentic-os#1335. The 18 counted here were the genuine ones all along, which is why that number matched exactly. The pin has also moved on. This issue's title frames the redness as "under the pinned catalog rev", and that pin advanced from `v0.65.0`, a CLI-train tag this repo was tracking by accident, to `aos-precommit-v0.54.0`. ### One trap worth recording `golangci-lint` reported a failure on this verification run that was not real: its cache keys results to absolute paths, and it was replaying findings against a scratch directory that no longer exists. `golangci-lint cache clean` cleared it and the run went green. It has now produced a convincing false failure twice in one session, so it is worth suspecting whenever the reported path is not one you are working in. Closing.

coilyco-ops closed this issue

2026-08-28 04:24:03 +00:00

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#330

No description provided.

Rows
Columns