The docs budget is full, so the issue-label guard has no docs/ page

coilyco-ops commented

2026-08-27 04:08:19 +00:00

Owner

Filed by Angie (platform, claude seat) as the deferral from #1105 / PR #1311.

What was deferred

#1105 landed the issue create label-composition guard. A docs/forgejo-issue-labels.md walkthrough was written for it and then dropped, so the explanation now lives only in the verb's describe string.

The describe is a real surface - it renders in --help and in the generated aosguard skill - so nothing is undocumented. What is missing is the prose page the workspace rule asks for when a feature is substantial enough to earn one.

Why it was dropped

docs/ is at the ceiling.

FAIL: docs/: 41 docs exceeds the 40-doc cap for the large band.
      Merge related pages; splitting one doc into two to clear the
      size cap trades one violation for another.

large is the top band, so there is nothing to promote to. The two natural homes are both already at exactly 120 lines, the band's line cap, with zero headroom:

docs/aosguard.md - 120 lines, 6,213 chars
docs/forgejo-ops.md - 120 lines, 5,482 chars

Folding the content into either means cutting existing documentation to make room, which is a judgement about someone else's pages rather than part of #1105.

The real question

This is the documentation budget doing exactly what docs/documentation-bands.md says it is for, so the answer is a merge rather than an exemption:

A per-doc size cap does not bound a docs folder, it reshapes it.

Worth deciding which:

Merge the Forgejo pages. forgejo-ops.md and forgejo-actions-runs.md are both Forgejo operator surfaces and both sit under the char cap. Merging them frees a slot and makes room, but the combined page has to fit 120 lines, which neither pair does today without cutting.
Prune. Some pages may have outlived their subject. That is a read of the whole folder rather than a guess from here.
Argue for a third band. The bands doc frames the count times lines product as the number worth arguing about (large is 4,800 lines). A repo this size may have outgrown it, and the doc invites exactly that argument rather than a silent cap bump.

I did not pick one, because choosing is a call about the repo's documentation shape rather than about the guard #1105 shipped.

The parked draft

The written page is 66 lines / 3,110 chars and fits the per-doc caps comfortably. It covers the names-not-ids reasoning, the refusal shape and exit code, the two-call mechanism and why it is still pre-write, and the narrowing versus the shadowed leaf. It is not committed anywhere, so it needs rewriting rather than recovering. The material it carries is all present in PR #1311's description and in the describe.

Filed by Angie (platform, `claude` seat) as the deferral from #1105 / PR #1311. ## What was deferred #1105 landed the `issue create` label-composition guard. A `docs/forgejo-issue-labels.md` walkthrough was written for it and then dropped, so the explanation now lives only in the verb's `describe` string. The `describe` is a real surface - it renders in `--help` and in the generated `aosguard` skill - so nothing is undocumented. What is missing is the prose page the workspace rule asks for when a feature is substantial enough to earn one. ## Why it was dropped `docs/` is at the ceiling. ``` FAIL: docs/: 41 docs exceeds the 40-doc cap for the large band. Merge related pages; splitting one doc into two to clear the size cap trades one violation for another. ``` `large` is the top band, so there is nothing to promote to. The two natural homes are both already at exactly 120 lines, the band's line cap, with zero headroom: * `docs/aosguard.md` - 120 lines, 6,213 chars * `docs/forgejo-ops.md` - 120 lines, 5,482 chars Folding the content into either means cutting existing documentation to make room, which is a judgement about someone else's pages rather than part of #1105. ## The real question This is the documentation budget doing exactly what `docs/documentation-bands.md` says it is for, so the answer is a merge rather than an exemption: > A per-doc size cap does not bound a docs folder, it reshapes it. Worth deciding which: 1. **Merge the Forgejo pages.** `forgejo-ops.md` and `forgejo-actions-runs.md` are both Forgejo operator surfaces and both sit under the char cap. Merging them frees a slot and makes room, but the combined page has to fit 120 lines, which neither pair does today without cutting. 2. **Prune.** Some pages may have outlived their subject. That is a read of the whole folder rather than a guess from here. 3. **Argue for a third band.** The bands doc frames the count times lines product as the number worth arguing about (`large` is 4,800 lines). A repo this size may have outgrown it, and the doc invites exactly that argument rather than a silent cap bump. I did not pick one, because choosing is a call about the repo's documentation shape rather than about the guard #1105 shipped. ## The parked draft The written page is 66 lines / 3,110 chars and fits the per-doc caps comfortably. It covers the names-not-ids reasoning, the refusal shape and exit code, the two-call mechanism and why it is still pre-write, and the narrowing versus the shadowed leaf. It is not committed anywhere, so it needs rewriting rather than recovering. The material it carries is all present in PR #1311's description and in the `describe`.

coilyco-ops added the

labels

2026-08-27 04:08:19 +00:00

coilyco-ops referenced this issue

2026-08-27 04:08:50 +00:00

feat(aosguard): refuse an issue filed with no priority or autonomy label #1311

coilyco-ops referenced this issue

2026-08-27 04:20:07 +00:00

Require a priority and an autonomy label on AOSguard's forgejo issue create #1105

coilyco-ops referenced this issue

2026-08-27 04:25:27 +00:00

The docs/ budget is exhausted: 40/40 pages and the native family at its line cap #1315

coilyco-ops referenced this issue

2026-08-27 04:25:39 +00:00

agentic-os documentation-layout is at every cap simultaneously, so a new rule has nowhere to put its reasoning #1303

coilyco-ops referenced this issue from a commit

2026-08-27 04:26:19 +00:00

feat(aosguard): refuse an issue filed with no priority or autonomy label

coilyco-ops referenced this issue

2026-08-27 04:26:47 +00:00

feat(aosguard): refuse an issue filed with no priority or autonomy label #1318

coilyco-ops referenced this issue

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

Require a priority and an autonomy label on AOSguard's forgejo issue create #1105

coilyco-ops added this to the Rules that do not hold: silent guards, full budgets, second writers milestone

2026-08-29 07:55:29 +00:00

coilyco-ops referenced this issue from a commit

2026-08-29 08:32:10 +00:00

feat(aos-eval): delete the package and its nine reference sites

coilyco-ops commented

2026-08-29 08:34:18 +00:00

Author

Owner

The blocker on this is about to lift, from an unrelated direction.

#1389 deletes aos-eval/ and its nine reference sites, one of which is docs/aos-eval.md. That takes docs/ from 40 of 40 to 39 of 40, which is the first free slot in that budget since it filled.

So docs/forgejo-issue-labels.md, the page this issue exists to place, has somewhere legal to go.

What that does and does not settle

It gives this issue its slot. It does not change the budget, and Kai decided on 2026-08-29 that the count cap stays and pages get merged rather than added. So the slot is a one-off paid for by a deletion, not new headroom, and the next page after this one is back to displacing something.

Worth being explicit about that, because "there is room now" is exactly the reading that refills a cap.

Order

Wait for #1389 to merge, then land the page. Writing it first risks the same three-way squeeze recorded here: this issue, #1274, and #1341 are all blocked on the same slot, and only one of them can have it.

Whoever moves first should say so on the other two rather than racing. My view, not a decision: this issue has the strongest claim, since #1105 already shipped the guard and the page was written and dropped, so the content exists and is the smallest thing to land.

The blocker on this is about to lift, from an unrelated direction. `#1389` deletes `aos-eval/` and its nine reference sites, one of which is `docs/aos-eval.md`. That takes `docs/` from **40 of 40 to 39 of 40**, which is the first free slot in that budget since it filled. So `docs/forgejo-issue-labels.md`, the page this issue exists to place, has somewhere legal to go. ## What that does and does not settle It gives this issue its slot. It does not change the budget, and Kai decided on 2026-08-29 that the count cap **stays** and pages get merged rather than added. So the slot is a one-off paid for by a deletion, not new headroom, and the next page after this one is back to displacing something. Worth being explicit about that, because "there is room now" is exactly the reading that refills a cap. ## Order Wait for `#1389` to merge, then land the page. Writing it first risks the same three-way squeeze recorded here: this issue, `#1274`, and `#1341` are all blocked on the same slot, and only one of them can have it. Whoever moves first should say so on the other two rather than racing. My view, not a decision: this issue has the strongest claim, since `#1105` already shipped the guard and the page was written and dropped, so the content exists and is the smallest thing to land.

coilyco-ops referenced this issue from a commit

2026-08-29 10:25:28 +00:00

refactor(docs): move the warp and aosguard pages into skill references

coilyco-ops referenced this issue

2026-08-29 10:25:40 +00:00

Free the docs budget by moving warp and aosguard pages into skill references #1397

coilyco-ops referenced this issue from a commit

2026-08-29 10:37:30 +00:00

docs: free the rest of the budget and land the three deferred pages

coilyco-ops referenced this issue from a pull request that will close it,

2026-08-29 10:37:43 +00:00

Free the rest of the docs budget and land the three deferred pages #1401