coilyco-flight-deck/umbra

Watch

docs band migration: merge 29 docs, trim 29 files #299

New issue

Closed

opened 2026-08-16 06:59:48 +00:00 by coilyco-ops · 1 comment

coilyco-ops commented

2026-08-16 06:59:48 +00:00

Member

This repo declares the small documentation band, so its caps are
40 lines / 3,000 chars per Markdown file and 20 docs/*.md.

Measured by running the validator against this checkout:

docs/: 49 files against a 20 cap - 29 to merge away
29 files over a size cap - 29 docs/*.md prose

The work

Merge docs/ from 49 pages down to 20. Related pages join; a page that only exists because another got too long goes back where it came from.
Bring 29 files under 40 lines / 3,000 chars. Breakdown: 29 docs/*.md prose.

Merging is the move, not splitting. Splitting one over-long doc into two trades
a size violation for a count violation, which is the whole reason the count cap
exists.

Done means

pre-commit run --all-files green, with no new entry under
[tool.agentic-os.documentation-layout] excludes. Excludes still govern
placement and flatness and no longer reach either size cap or the count, so
adding one cannot close this issue. A generated file over the cap is a
generator emitting too much, and the fix is the generator.

Take as long as it needs. There is no partial-credit state to reach for.

The docs count cap is implemented and tested but not yet wired into the hook's
main() - it lands with agentic-os's own migration. So pre-commit will not
fail on the count today. Do the merging anyway: it goes red the moment that
one-line wiring commit lands.

This repo's pre-commit run --all-files fails on pristine main for reasons unrelated to this work, so nothing can commit until umbra#298 clears. Start there.

Parent: coilyco-flight-deck/agentic-os#1102. Rationale and the measurements behind the numbers:
docs/documentation-bands.md.

This repo declares the **`small`** documentation band, so its caps are **40 lines / 3,000 chars** per Markdown file and **20 `docs/*.md`**. Measured by running the validator against this checkout: * **`docs/`: 49 files against a 20 cap** - **29 to merge away** * **29 files over a size cap** - 29 `docs/*.md` prose ## The work 1. Merge `docs/` from 49 pages down to 20. Related pages join; a page that only exists because another got too long goes back where it came from. 2. Bring 29 files under 40 lines / 3,000 chars. Breakdown: 29 `docs/*.md` prose. Merging is the move, not splitting. Splitting one over-long doc into two trades a size violation for a count violation, which is the whole reason the count cap exists. ## Done means `pre-commit run --all-files` green, with no new entry under `[tool.agentic-os.documentation-layout] excludes`. Excludes still govern placement and flatness and no longer reach either size cap or the count, so adding one cannot close this issue. A generated file over the cap is a generator emitting too much, and the fix is the generator. Take as long as it needs. There is no partial-credit state to reach for. The docs count cap is implemented and tested but not yet wired into the hook's `main()` - it lands with agentic-os's own migration. So `pre-commit` will not fail on the count today. Do the merging anyway: it goes red the moment that one-line wiring commit lands. This repo's `pre-commit run --all-files` fails on pristine `main` for reasons unrelated to this work, so nothing can commit until umbra#298 clears. Start there. Parent: coilyco-flight-deck/agentic-os#1102. Rationale and the measurements behind the numbers: [docs/documentation-bands.md](https://forgejo.coilysiren.me/coilyco-flight-deck/agentic-os/src/branch/main/docs/documentation-bands.md).

coilyco-ops added the

labels

2026-08-16 07:01:15 +00:00

coilyco-ops referenced this issue from coilyco-flight-deck/agentic-os

2026-08-16 07:03:24 +00:00

docs band migration: 468 docs to merge, 531 files to trim, 24 repos #1102

coilyco-ops added

priority

and removed

priority

labels

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

coilyco-ops referenced this issue

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

docs: declare a band, 49 docs to 20, 29 oversized docs #300

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

coilyco-ops referenced this issue from a commit

2026-08-17 03:24:15 +00:00

docs(band): merge the execverb, opcore, and broker families

coilyco-ops referenced this issue from a commit

2026-08-17 03:47:40 +00:00

docs(band): merge docs/ from 51 pages to 20

coilyco-ops referenced this issue from a commit

2026-08-17 03:47:41 +00:00

docs(band): finish the small-band migration

coilyco-ops closed this issue

2026-08-17 03:47:41 +00:00

coilyco-ops commented

2026-08-17 03:48:04 +00:00

Author

Member

Landed on main as ebc6cb8. 51 docs -> 20, every file under 40 lines / 3,000 chars. make test and pre-commit run --all-files green.

The measurement first, because it changed the shape of the decision

Before starting I measured umbra against both bands:

large (120 lines / 8,000 chars / 40 docs) - 0 of 51 files breached a per-file cap. Only the count was over, by 11.
small (40 / 3,000 / 20) - 17 files over on chars, 30 over on lines, 31 merges, and a 60 KB ceiling against 130 KB of prose.

So small was not a merge job with some trimming attached: it meant deleting ~54% of the documentation. That is a content decision rather than a mechanical migration, so I put it to Kai rather than inferring it. Her call was to hold small and take the cut, with the cost stated. Recording that here so the deletion has an owner and is not read later as drift.

What the 20 are

Merged onto the page that owns the subject, never split:

execverb <- actions, inspect, value-flags
opcore-inline <- query-types, query-aliases, body-mapping, proxy
specverb-resolution <- unrecognised-verbs, wildcard
specverb-policy <- override, inherit, auth-none
specverb-request <- raw-responses, user-agent
specverb-actions <- action-{mount,collect,defaults}
specgen <- discovery, install, vendored-sources, mixed-transports
specgen-materialization <- embedded-files, skills
value-providers <- value-chain, ssm-resolver, kdl-description
broker <- provenance
FEATURES <- features-detail, examples
release-pipeline <- umbra-mark, golangci-notes

Two files were deleted rather than merged. docs/CODE_OF_CONDUCT.md and docs/SECURITY.md were byte-identical copies of the root files. The root copies are canonical and are where a forge looks, so the duplicates were pure count with zero content. That freed two slots, which is why specverb-fetch and specverb-describe survive as their own pages instead of being crushed into a neighbour.

No new excludes entry, as the issue required.

Pointers followed the content

The part that would rot silently if skipped:

15 Go files had docs/*.md references retargeted. Verified by re-scanning every docs/…md string in the tree against the filesystem: zero dangling, in Go and Markdown both.
assets/mark/README.md is an outpost, and the hook caught it pointing at the merged-away umbra-mark.md. Repointed.
The mkdocs nav lost the entries whose pages merged away. While there, its site_url and repo_url still pointed at the retired coilysiren/cli-guard GitHub path, so those move to Forgejo too.

A correction rode along, deliberately

#303 landed mid-migration and corrected the User-Agent claim: the earlier measurement blamed reddit's 403 on Go's default agent, but re-measured from net/http the 403 came from the placeholder Authorization a credential-free Guardfile was forced to send. My merge had already absorbed the superseded text. The merged specverb-request carries the corrected version, and auth none is documented in specverb-policy. A migration that quietly reinstated a retracted claim would have been worse than not merging at all.

One thing worth flagging, not fixed here

pkg/version/release_pipeline_contract_test.go asserts that docs/FEATURES.md contains the literal string commit-scoped draft tags on `main` . It failed on the rewrite and I restored the phrase, since it is true and belongs there.

But that is a test encoding prose in a docs file, which is the shape the workspace rule against tests restating configuration exists to prevent. It makes FEATURES.md wording load-bearing for a Go test in an unrelated package. Not mine to change under this issue, and worth its own if anyone agrees.

Angie, engineer seat

Landed on `main` as `ebc6cb8`. **51 docs -> 20, every file under 40 lines / 3,000 chars.** `make test` and `pre-commit run --all-files` green. ## The measurement first, because it changed the shape of the decision Before starting I measured umbra against both bands: * **`large`** (120 lines / 8,000 chars / 40 docs) - **0 of 51 files breached a per-file cap.** Only the count was over, by 11. * **`small`** (40 / 3,000 / 20) - 17 files over on chars, 30 over on lines, 31 merges, and a 60 KB ceiling against 130 KB of prose. So `small` was not a merge job with some trimming attached: it meant deleting **~54% of the documentation**. That is a content decision rather than a mechanical migration, so I put it to Kai rather than inferring it. **Her call was to hold `small` and take the cut**, with the cost stated. Recording that here so the deletion has an owner and is not read later as drift. ## What the 20 are Merged onto the page that owns the subject, never split: * `execverb` <- actions, inspect, value-flags * `opcore-inline` <- query-types, query-aliases, body-mapping, proxy * `specverb-resolution` <- unrecognised-verbs, wildcard * `specverb-policy` <- override, inherit, auth-none * `specverb-request` <- raw-responses, user-agent * `specverb-actions` <- action-{mount,collect,defaults} * `specgen` <- discovery, install, vendored-sources, mixed-transports * `specgen-materialization` <- embedded-files, skills * `value-providers` <- value-chain, ssm-resolver, kdl-description * `broker` <- provenance * `FEATURES` <- features-detail, examples * `release-pipeline` <- umbra-mark, golangci-notes **Two files were deleted rather than merged.** `docs/CODE_OF_CONDUCT.md` and `docs/SECURITY.md` were byte-identical copies of the root files. The root copies are canonical and are where a forge looks, so the duplicates were pure count with zero content. That freed two slots, which is why `specverb-fetch` and `specverb-describe` survive as their own pages instead of being crushed into a neighbour. **No new `excludes` entry**, as the issue required. ## Pointers followed the content The part that would rot silently if skipped: * **15 Go files** had `docs/*.md` references retargeted. Verified by re-scanning every `docs/…md` string in the tree against the filesystem: zero dangling, in Go and Markdown both. * `assets/mark/README.md` is an **outpost**, and the hook caught it pointing at the merged-away `umbra-mark.md`. Repointed. * The mkdocs nav lost the entries whose pages merged away. While there, its `site_url` and `repo_url` still pointed at the retired `coilysiren/cli-guard` GitHub path, so those move to Forgejo too. ## A correction rode along, deliberately `#303` landed mid-migration and **corrected** the User-Agent claim: the earlier measurement blamed reddit's 403 on Go's default agent, but re-measured from `net/http` the 403 came from the placeholder `Authorization` a credential-free Guardfile was forced to send. My merge had already absorbed the superseded text. The merged `specverb-request` carries the **corrected** version, and `auth none` is documented in `specverb-policy`. A migration that quietly reinstated a retracted claim would have been worse than not merging at all. ## One thing worth flagging, not fixed here `pkg/version/release_pipeline_contract_test.go` asserts that `docs/FEATURES.md` contains the literal string ``commit-scoped draft tags on `main` ``. It failed on the rewrite and I restored the phrase, since it is true and belongs there. But that is a test encoding prose in a docs file, which is the shape the workspace rule against tests restating configuration exists to prevent. It makes FEATURES.md wording load-bearing for a Go test in an unrelated package. Not mine to change under this issue, and worth its own if anyone agrees.  Angie, engineer seat

coilyco-ops referenced this issue

2026-08-17 03:52:14 +00:00

The inline grammar cannot set a request header, so reddit 403s every guardfile that reaches it #303

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

No description provided.

Rows
Columns