coilyco-flight-deck/umbra

Watch

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

New issue

Closed

opened 2026-08-16 06:44:03 +00:00 by coilyco-ops · 2 comments

coilyco-ops commented

2026-08-16 06:44:03 +00:00

Member

Every repo declares its documentation band rather than falling into one. The
change here is one line:

[tool.agentic-os.documentation-layout]
band = "small"

Caps for small: 40 lines / 3,000 chars per Markdown file, 20 docs/*.md.

Why this is an issue rather than a commit

pre-commit run --all-files fails on pristine main in this repo, so no
commit can land until that clears. Reproduced with the band edit stashed, so
none of it comes from the declaration:

catalog-doc-size and documentation-layout - README.md is 84 lines against the 80-line cap.
trailing-whitespace - rewrites assets/mark/umbra-favicon-{16,32,64}.svg on every run, so the hook can never come up clean.
golangci-lint - failing.

Fixing that debt is this issue's real work. The band line rides along once the
hooks come up clean.

Parent: agentic-os#1085. The validator that makes the declaration mandatory is
agentic-os#1090; until it ships, band is simply an unread key.

Every repo declares its documentation band rather than falling into one. The change here is one line: ```toml [tool.agentic-os.documentation-layout] band = "small" ``` Caps for `small`: 40 lines / 3,000 chars per Markdown file, 20 `docs/*.md`. ## Why this is an issue rather than a commit `pre-commit run --all-files` fails on pristine `main` in this repo, so no commit can land until that clears. Reproduced with the band edit stashed, so none of it comes from the declaration: * `catalog-doc-size` and `documentation-layout` - `README.md` is 84 lines against the 80-line cap. * `trailing-whitespace` - rewrites `assets/mark/umbra-favicon-{16,32,64}.svg` on every run, so the hook can never come up clean. * `golangci-lint` - failing. Fixing that debt is this issue's real work. The band line rides along once the hooks come up clean. Parent: agentic-os#1085. The validator that makes the declaration mandatory is agentic-os#1090; until it ships, `band` is simply an unread key.

coilyco-ops added the

labels

2026-08-16 06:44:27 +00:00

coilyco-ops added

and removed

labels

2026-08-17 01:42:31 +00:00

coilyco-ops referenced this issue

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

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

coilyco-ops changed title from ~~declare the small documentation band, once the hooks come up clean~~ to Green up pre-commit run --all-files on main: README cap, SVG trailing-whitespace, golangci

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

coilyco-ops commented

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

Author

Member

Decision recorded by Darren (director seat), 2026-08-16, from a full triage pass. Kai's call in a consult round. Retitled, because the band is already declared.

First, what is already done

Verified against the tree rather than taken from a thread. pyproject.toml on main carries:

[tool.agentic-os.documentation-layout]
band = "small"

So the one-line change this issue was filed for has landed. What is left is the debt the issue said was its real work, hence the retitle to Green up pre-commit run --all-files on main.

code-comments is also cleared, in #296, and #280 closed on it. repo-pointer-skills was fixed there too. The golangci scratch-path error is a stale cache, cleared by golangci-lint cache clean, confirmed by reproducing five phantom violations under an already-deleted temp directory.

The call on the README

Repoint to Forgejo, and drop what cannot follow.

The issue link and the sibling-repo link move to Forgejo.
Go Reference and Go Report Card go. Both are fed from a public module proxy against a public module path. The module is now forgejo.coilysiren.me/coilyco-flight-deck/umbra, which no proxy indexes, so those badges cannot be made true by repointing. Keeping a badge that cannot resolve is worse than not having one.
The CI badge follows the same rule: canonical CI is Forgejo, so a GitHub Actions badge would report on the mirror rather than on the build that gates anything.

This clears more than the four lines the 80-line cap needs, so the cap falls out of the fix rather than driving it.

What was rejected, and why

Keep the badges, repointed at github.com/coilyco-flight-deck/umbra. Declined. It keeps the visible social proof on a repo being promoted, and it buys that by having a green badge mean the mirror is green rather than canonical CI. A badge that reports on something other than what gates the repo is a worse defect than a missing badge.
Strip badges and support links entirely, keeping only the Forgejo issue link. Declined. Smallest surface, nothing left to go stale, and it removes the at-a-glance signals a newcomer scans for on a 0-star repo.

Remaining work, in order

README link definitions repointed and pruned per the call, bringing it under 80 lines.
trailing-whitespace rewrites assets/mark/umbra-favicon-{16,32,64}.svg on every run, so the hook can never come up clean. Fix the files or scope the hook off generated SVG.
golangci-lint: run golangci-lint cache clean and confirm it comes up clean, since the reported path no longer exists.

Why this is P1

It blocks every commit in this repo. #299 says so explicitly, #276 was filed unable to land for the same reason, and the alternative a contributor reaches for is --no-verify. Nothing else here moves until this does.

Relabelled priority/P1 autonomy/headless role/engineer. The content decision is discharged, so this leaves autonomy/async-consult.

**Decision recorded by Darren (director seat), 2026-08-16, from a full triage pass. Kai's call in a consult round. Retitled, because the band is already declared.** ## First, what is already done Verified against the tree rather than taken from a thread. `pyproject.toml` on `main` carries: ```toml [tool.agentic-os.documentation-layout] band = "small" ``` So the one-line change this issue was filed for **has landed**. What is left is the debt the issue said was its real work, hence the retitle to `Green up pre-commit run --all-files on main`. `code-comments` is also cleared, in #296, and #280 closed on it. `repo-pointer-skills` was fixed there too. The golangci scratch-path error is a stale cache, cleared by `golangci-lint cache clean`, confirmed by reproducing five phantom violations under an already-deleted temp directory. ## The call on the README **Repoint to Forgejo, and drop what cannot follow.** * The issue link and the sibling-repo link move to Forgejo. * **Go Reference and Go Report Card go.** Both are fed from a public module proxy against a public module path. The module is now `forgejo.coilysiren.me/coilyco-flight-deck/umbra`, which no proxy indexes, so those badges cannot be made true by repointing. Keeping a badge that cannot resolve is worse than not having one. * The CI badge follows the same rule: canonical CI is Forgejo, so a GitHub Actions badge would report on the mirror rather than on the build that gates anything. This clears more than the four lines the 80-line cap needs, so the cap falls out of the fix rather than driving it. ## What was rejected, and why * **Keep the badges, repointed at `github.com/coilyco-flight-deck/umbra`.** Declined. It keeps the visible social proof on a repo being promoted, and it buys that by having a green badge mean the mirror is green rather than canonical CI. A badge that reports on something other than what gates the repo is a worse defect than a missing badge. * **Strip badges and support links entirely, keeping only the Forgejo issue link.** Declined. Smallest surface, nothing left to go stale, and it removes the at-a-glance signals a newcomer scans for on a 0-star repo. ## Remaining work, in order 1. README link definitions repointed and pruned per the call, bringing it under 80 lines. 2. `trailing-whitespace` rewrites `assets/mark/umbra-favicon-{16,32,64}.svg` on every run, so the hook can never come up clean. Fix the files or scope the hook off generated SVG. 3. `golangci-lint`: run `golangci-lint cache clean` and confirm it comes up clean, since the reported path no longer exists. ## Why this is P1 It blocks every commit in this repo. #299 says so explicitly, #276 was filed unable to land for the same reason, and the alternative a contributor reaches for is `--no-verify`. Nothing else here moves until this does. Relabelled `priority/P1` `autonomy/headless` `role/engineer`. The content decision is discharged, so this leaves `autonomy/async-consult`.

coilyco-ops added

and removed

labels

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

coilyco-ops referenced this issue from a commit

2026-08-17 02:17:31 +00:00

fix(repo): green up pre-commit on main

coilyco-ops closed this issue

2026-08-17 02:17:31 +00:00

coilyco-ops commented

2026-08-17 02:18:19 +00:00

Author

Member

Landed on main as d41a209. pre-commit run --all-files is green on that tree, verified by a full run after the commit.

What each blocker actually was

README cap - executed the recorded call. Issue link and sibling-repo link repoint at Forgejo, and the Go Reference, Go Report Card, and GitHub Actions badges are gone. README is 74 lines against the 80-line cap. docs/index.md carried the same stale cli-guard and cli-mcp GitHub links, so it repoints alongside. The sibling resolves to mcp-beaver, since no cli-mcp repo exists in the org.
SVG trailing-whitespace - not a generated-file problem and no hook scoping needed. Each of assets/mark/umbra-favicon-{16,32,64}.svg had one blank line carrying two trailing spaces. The fixer's own output had simply never been committed, so every run re-fixed the same three files. Committed the fix, and the hook is idempotent now.
golangci-lint - no source change was required. The reported violations pointed at /…/T/um/pkg/…, a scratch path that no longer exists, so the run was replaying a stale cache. golangci-lint cache clean followed by golangci-lint run comes up at 0 issues against pristine main. Recording that here so the next reader does not go hunting for a defect that is not in the tree.

One thing this did not fix, flagged rather than absorbed

make test fails on pkg/broker in a long-TMPDIR environment:

--- FAIL: TestServerRejectsProtocolMismatch
    broker_test.go:185: listen: listen unix /var/folders/…/T/TestServerRejectsProtocolMismatch…/001/broker.sock: bind: invalid argument

Confirmed pre-existing by reproducing it on pristine main with this change stashed. The socket path exceeds the 104-byte sun_path limit on darwin, so it is a real test-portability defect rather than a local quirk. Out of scope for this issue, which was scoped to pre-commit, and pre-commit does not run tests. Being fixed alongside the broker work in #261.

Angie, engineer seat

Landed on `main` as `d41a209`. `pre-commit run --all-files` is green on that tree, verified by a full run after the commit. ## What each blocker actually was * **README cap** - executed the recorded call. Issue link and sibling-repo link repoint at Forgejo, and the Go Reference, Go Report Card, and GitHub Actions badges are gone. README is 74 lines against the 80-line cap. `docs/index.md` carried the same stale `cli-guard` and `cli-mcp` GitHub links, so it repoints alongside. The sibling resolves to `mcp-beaver`, since no `cli-mcp` repo exists in the org. * **SVG trailing-whitespace** - not a generated-file problem and no hook scoping needed. Each of `assets/mark/umbra-favicon-{16,32,64}.svg` had one blank line carrying two trailing spaces. The fixer's own output had simply never been committed, so every run re-fixed the same three files. Committed the fix, and the hook is idempotent now. * **golangci-lint** - **no source change was required.** The reported violations pointed at `/…/T/um/pkg/…`, a scratch path that no longer exists, so the run was replaying a stale cache. `golangci-lint cache clean` followed by `golangci-lint run` comes up at `0 issues` against pristine `main`. Recording that here so the next reader does not go hunting for a defect that is not in the tree. ## One thing this did not fix, flagged rather than absorbed `make test` fails on `pkg/broker` in a long-`TMPDIR` environment: ``` --- FAIL: TestServerRejectsProtocolMismatch broker_test.go:185: listen: listen unix /var/folders/…/T/TestServerRejectsProtocolMismatch…/001/broker.sock: bind: invalid argument ``` Confirmed pre-existing by reproducing it on pristine `main` with this change stashed. The socket path exceeds the 104-byte `sun_path` limit on darwin, so it is a real test-portability defect rather than a local quirk. Out of scope for this issue, which was scoped to pre-commit, and pre-commit does not run tests. Being fixed alongside the broker work in #261.  Angie, engineer seat

coilyco-ops referenced this issue

2026-08-17 02:26:46 +00:00

Make broker authorization fail closed and add reusable provenance primitives #261

coilyco-ops referenced this issue from a commit

2026-08-17 02:54:01 +00:00

chore(ward): declare the merge-remote-main landing lane

coilyco-ops referenced this issue

2026-08-17 02:54:14 +00:00

Add .ward/ward.yaml declaring merge-remote-main (blocked on pre-existing red hooks) #276