coilyco-flight-deck/agentic-os

Watch

Close the docs-count gap: 66 to 40 is a trimming pass, not a deletion pass #1097

New issue

Closed

opened 2026-08-16 06:51:10 +00:00 by coilyco-ops · 2 comments

coilyco-ops commented

2026-08-16 06:51:10 +00:00

Member

Walked all 68 docs. Two were dead and are deleted on #1090's branch. The rest of the gap does not close by deleting, and this is what the walk found instead.

What was actually dead

issue-corpus.md - said in full that the corpus is retired and must not be revived, while FEATURES.md advertised it as a shipped capability. One of the two had been wrong long enough that the pair went unnoticed.
security-boundaries.md - two dated audits that closed their issues. Zero inbound references. An audit records a question already answered.

That is 66 docs. The cap is 40.

Nothing else in `docs/` is dead

I went looking for staleness and did not find it. No doc references a renamed thing (ward-mcp, cli-guard) or a deleted repo. The quiet docs are quiet because their subject is stable, not because they rotted:

signoz.md - one commit, one inbound, untouched since 2026-08-01. It documents a live guarded MCP read surface.
aos-catalogue-cache.md - same shape. Documents a live config section.
composed-house-taste.md - same shape.

Low churn on a stable feature is the good case. Deleting those to reach a number destroys reference material the cap exists to make readable.

Why merging alone cannot finish

66 docs hold 5,137 lines. The ceiling is 40 x 120 = 4,800.

The blocker is that the corpus is already dense. Median doc is 77 lines, so two median docs merge to 154 and breach the 120-line cap on contact. I hit this three times today: features-agents + claude-settings-guardrails came to 116 lines but 9,146 chars, over the 8,000 cap, despite the second file literally opening with "Back to features-agents.md". Reverted.

Merging also adds lines, measured at 3.7 per fold.

The path that closes it, and it is trimming rather than deleting

Nine docs are candidates, 680 lines. Deleting all nine gives 57 docs / 4,457 lines, and 17 further merges land at 40 docs / 4,525 lines, inside the ceiling. The arithmetic works.

But only two or three of the nine should actually be deleted:

Delete - just-task-runner.md (79 lines, zero inbound). Framed as a spike for inbox#365. The justfile it proposed is live and in use, so the decision is made and the spike prose is the leftover. Fold ~15 lines into repo-layout.md.
Delete or relocate - agent-sdk-patterns.md (117). Opens "implementation options, not" - generic agent-design patterns rather than anything this repo ships. Belongs in a skill.
Trim, not delete - dictatable-id-alphabet.md (74) is rationale for a shipped generator. The why is worth keeping at ~25 lines.
Merge with real trimming - the terminal trio agent-terminal-native.md + alacritty-directors.md + statusline.md is 237 lines across three live features. One page needs it cut to 120, so roughly half goes.
Merge - signoz.md into aosguard.md, aos-catalogue-cache.md into aos-cli.md, composed-house-taste.md into role-composed-skills.md. Each needs the host trimmed to make room.

So reaching 40 is an editing pass, not a deletion pass: roughly 600 lines of prose cut out of docs that all stay. That is the honest shape of the remaining work and it is a day of careful editing rather than a sweep.

Acceptance

docs/ holds 40 or fewer *.md, each inside 120 lines and 8,000 chars.
No live capability loses its reference material.
check_docs_count wired into main()'s violation list in the commit that lands it.

Walked all 68 docs. Two were dead and are deleted on https://forgejo.coilysiren.me/coilyco-flight-deck/agentic-os/pulls/1090's branch. The rest of the gap does **not** close by deleting, and this is what the walk found instead. ## What was actually dead * **`issue-corpus.md`** - said in full that the corpus is retired and must not be revived, while `FEATURES.md` advertised it as a shipped capability. One of the two had been wrong long enough that the pair went unnoticed. * **`security-boundaries.md`** - two dated audits that closed their issues. Zero inbound references. An audit records a question already answered. That is 66 docs. The cap is 40. ## Nothing else in `docs/` is dead I went looking for staleness and did not find it. No doc references a renamed thing (`ward-mcp`, `cli-guard`) or a deleted repo. The quiet docs are quiet because their subject is stable, not because they rotted: * `signoz.md` - one commit, one inbound, untouched since 2026-08-01. It documents a live guarded MCP read surface. * `aos-catalogue-cache.md` - same shape. Documents a live config section. * `composed-house-taste.md` - same shape. **Low churn on a stable feature is the good case.** Deleting those to reach a number destroys reference material the cap exists to make readable. ## Why merging alone cannot finish 66 docs hold 5,137 lines. The ceiling is 40 x 120 = 4,800. The blocker is that the corpus is already dense. Median doc is 77 lines, so two median docs merge to 154 and breach the 120-line cap on contact. I hit this three times today: `features-agents` + `claude-settings-guardrails` came to 116 lines but **9,146 chars**, over the 8,000 cap, despite the second file literally opening with "Back to features-agents.md". Reverted. Merging also **adds** lines, measured at 3.7 per fold. ## The path that closes it, and it is trimming rather than deleting Nine docs are candidates, 680 lines. Deleting all nine gives 57 docs / 4,457 lines, and 17 further merges land at **40 docs / 4,525 lines, inside the ceiling**. The arithmetic works. But only two or three of the nine should actually be deleted: * **Delete** - `just-task-runner.md` (79 lines, **zero inbound**). Framed as a spike for inbox#365. The `justfile` it proposed is live and in use, so the decision is made and the spike prose is the leftover. Fold ~15 lines into `repo-layout.md`. * **Delete or relocate** - `agent-sdk-patterns.md` (117). Opens "implementation options, not" - generic agent-design patterns rather than anything this repo ships. Belongs in a skill. * **Trim, not delete** - `dictatable-id-alphabet.md` (74) is rationale for a shipped generator. The why is worth keeping at ~25 lines. * **Merge with real trimming** - the terminal trio `agent-terminal-native.md` + `alacritty-directors.md` + `statusline.md` is 237 lines across three live features. One page needs it cut to 120, so roughly half goes. * **Merge** - `signoz.md` into `aosguard.md`, `aos-catalogue-cache.md` into `aos-cli.md`, `composed-house-taste.md` into `role-composed-skills.md`. Each needs the host trimmed to make room. So reaching 40 is **an editing pass, not a deletion pass**: roughly 600 lines of prose cut out of docs that all stay. That is the honest shape of the remaining work and it is a day of careful editing rather than a sweep. ## Acceptance * `docs/` holds 40 or fewer `*.md`, each inside 120 lines and 8,000 chars. * No live capability loses its reference material. * `check_docs_count` wired into `main()`'s violation list in the commit that lands it.

coilyco-ops referenced this issue

2026-08-16 06:51:26 +00:00

docs: delete a tombstone and a closed audit log #1098

coilysiren referenced this issue from a commit

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

docs: delete a tombstone and a closed audit log (#1098)

coilyco-ops added the

labels

2026-08-17 02:36:06 +00:00

coilyco-ops referenced this issue

2026-08-17 19:08:53 +00:00

docs/test-harness.md documents a goose harness deleted in June 2026 #1117

coilyco-ops referenced this issue

2026-08-22 20:54:50 +00:00

Lane: headless engineer burn-down in agentic-os, 28 issues at P1 and P2, ordered so the toolchain unblocks itself first #1177

coilyco-ops added this to the Headless engineer lane: toolchain first milestone

2026-08-22 20:58:39 +00:00

coilyco-ops referenced this issue

2026-08-22 21:13:31 +00:00

AGENTS.md is over its own cap on main, so any edit to it fails the hook #1089

coilyco-ops commented

2026-08-23 00:08:47 +00:00

Author

Member

This is done. Measured on main at 1277aaba before anyone spends the trimming pass this issue plans.

docs/*.md                 40      cap 40
total lines               4207    ceiling 4800 (40 x 120)

And the hook itself, run against a snapshot of current main:

$ python3 -m agentic_os.pre_commit.check_documentation_layout
documentation-layout check: OK
exit=0

The issue's numbers were 66 docs and 5,137 lines. Both are now inside the caps, with 593 lines of headroom.

Nine of the eleven named files are already gone

issue-corpus              gone        security-boundaries    gone
just-task-runner          gone        alacritty-directors    gone
agent-sdk-patterns        gone        statusline             gone
dictatable-id-alphabet    gone        aos-catalogue-cache    gone
composed-house-taste      gone
agent-terminal-native     present     signoz                 present

The two survivors are both ones this issue argued should survive. signoz.md is named explicitly under "nothing else in docs/ is dead": low churn on a stable feature is the good case, and deleting it to reach a number destroys reference material the cap exists to make readable. agent-terminal-native.md was in the terminal trio, and the other two members merged into it, which is the merge this issue proposed.

So the corpus did not just shrink to a number. It shrank the way this issue said it should, which is why the arithmetic landed rather than the trimming being forced.

What I would do

Close it. The analysis was right, the plan was followed, and the acceptance is measurable and met.

Worth keeping from it rather than losing with the issue: merging adds about 3.7 lines per fold, and two median docs breach the 120-line cap on contact because the median is 77. Those are the numbers that make the next person's estimate honest, and docs/documentation-bands.md is where they would stay useful. That is a one-paragraph addition rather than a task, and only worth doing if it does not push the page over its own cap, which would be an unusually pointed way to prove the finding.

Not closing it myself. It is the engineer's issue and the lane's count, and I would rather hand over a measurement than a decision.

**This is done. Measured on `main` at `1277aaba` before anyone spends the trimming pass this issue plans.** ``` docs/*.md 40 cap 40 total lines 4207 ceiling 4800 (40 x 120) ``` And the hook itself, run against a snapshot of current `main`: ``` $ python3 -m agentic_os.pre_commit.check_documentation_layout documentation-layout check: OK exit=0 ``` The issue's numbers were 66 docs and 5,137 lines. Both are now inside the caps, with 593 lines of headroom. ## Nine of the eleven named files are already gone ``` issue-corpus gone security-boundaries gone just-task-runner gone alacritty-directors gone agent-sdk-patterns gone statusline gone dictatable-id-alphabet gone aos-catalogue-cache gone composed-house-taste gone agent-terminal-native present signoz present ``` The two survivors are both ones this issue argued **should** survive. `signoz.md` is named explicitly under "nothing else in `docs/` is dead": low churn on a stable feature is the good case, and deleting it to reach a number destroys reference material the cap exists to make readable. `agent-terminal-native.md` was in the terminal trio, and the other two members merged into it, which is the merge this issue proposed. So the corpus did not just shrink to a number. It shrank the way this issue said it should, which is why the arithmetic landed rather than the trimming being forced. ## What I would do Close it. The analysis was right, the plan was followed, and the acceptance is measurable and met. Worth keeping from it rather than losing with the issue: **merging adds about 3.7 lines per fold**, and **two median docs breach the 120-line cap on contact** because the median is 77. Those are the numbers that make the next person's estimate honest, and `docs/documentation-bands.md` is where they would stay useful. That is a one-paragraph addition rather than a task, and only worth doing if it does not push the page over its own cap, which would be an unusually pointed way to prove the finding. Not closing it myself. It is the engineer's issue and the lane's count, and I would rather hand over a measurement than a decision.

coilyco-ops referenced this issue

2026-08-23 00:47:48 +00:00

Lane: headless engineer burn-down in agentic-os, 28 issues at P1 and P2, ordered so the toolchain unblocks itself first #1177

coilyco-ops commented

2026-08-23 00:48:41 +00:00

Author

Member

Every acceptance criterion is met on main today. The trimming pass this issue argued for happened, and no commit closed the issue.

Measured, not assumed

docs: 40 (cap 40), total lines: 4217 (ceiling 40 x 120 = 4800)
over cap: none
largest: warp-host-setup.md 120, skill-discipline-authoring.md 120, role-composed-skills.md 120

40 or fewer *.md, each inside 120 lines and 8,000 chars - 40 exactly, and nothing over either cap. pre-commit run --all-files passes.
check_docs_count wired into main()'s violation list - check_documentation_layout.py:579.
No live capability loses its reference material - signoz.md is still its own page. The issue proposed merging it into aosguard.md, and that turned out not to be needed to reach 40, so a live guarded MCP read surface kept its own reference. That is the outcome this issue asked for over the arithmetic.

Every doc the walk named as a candidate is gone or folded: just-task-runner, agent-sdk-patterns, dictatable-id-alphabet, aos-catalogue-cache, composed-house-taste, alacritty-directors, statusline, plus the two dead ones. dictatable-id-alphabet landed exactly as recommended, trimmed into build-output-is-not-content.md rather than deleted.

The arithmetic held

The issue predicted 40 docs at ~4,525 lines against a 4,800 ceiling. Actual is 4,217, so there is more headroom than the plan expected.

Worth recording, because it is the live cost

Headroom is not comfort. Across this burn-down I touched nine docs, and every one was at or within two lines of the 120-line cap, so each change spent real time compressing surrounding prose to fit. docs/native-session-start.md absorbed three additions and needed a heading merged away to stay legal.

So the count gap is closed and the per-doc pressure is not. That is a different issue from this one, and I am not filing it speculatively: it is worth watching whether the next few features spend the same tax before deciding the band is wrong.

Closing as done.

Every acceptance criterion is met on `main` today. The trimming pass this issue argued for happened, and no commit closed the issue. ## Measured, not assumed ``` docs: 40 (cap 40), total lines: 4217 (ceiling 40 x 120 = 4800) over cap: none largest: warp-host-setup.md 120, skill-discipline-authoring.md 120, role-composed-skills.md 120 ``` * **40 or fewer `*.md`, each inside 120 lines and 8,000 chars** - 40 exactly, and nothing over either cap. `pre-commit run --all-files` passes. * **`check_docs_count` wired into `main()`'s violation list** - `check_documentation_layout.py:579`. * **No live capability loses its reference material** - `signoz.md` is still its own page. The issue proposed merging it into `aosguard.md`, and that turned out not to be needed to reach 40, so a live guarded MCP read surface kept its own reference. That is the outcome this issue asked for over the arithmetic. Every doc the walk named as a candidate is gone or folded: `just-task-runner`, `agent-sdk-patterns`, `dictatable-id-alphabet`, `aos-catalogue-cache`, `composed-house-taste`, `alacritty-directors`, `statusline`, plus the two dead ones. `dictatable-id-alphabet` landed exactly as recommended, trimmed into `build-output-is-not-content.md` rather than deleted. ## The arithmetic held The issue predicted 40 docs at ~4,525 lines against a 4,800 ceiling. Actual is 4,217, so there is more headroom than the plan expected. ## Worth recording, because it is the live cost Headroom is not comfort. Across this burn-down I touched nine docs, and **every one was at or within two lines of the 120-line cap**, so each change spent real time compressing surrounding prose to fit. `docs/native-session-start.md` absorbed three additions and needed a heading merged away to stay legal. So the count gap is closed and the per-doc pressure is not. That is a different issue from this one, and I am not filing it speculatively: it is worth watching whether the next few features spend the same tax before deciding the band is wrong. Closing as done.

coilyco-ops closed this issue

2026-08-23 00:48:47 +00:00

coilyco-ops referenced this issue

2026-08-23 00:49:30 +00:00

Lane: headless engineer burn-down in agentic-os, 28 issues at P1 and P2, ordered so the toolchain unblocks itself first #1177

coilyco-ops referenced this issue

2026-08-23 01:55:37 +00:00

Lane: headless engineer burn-down in agentic-os, 28 issues at P1 and P2, ordered so the toolchain unblocks itself first #1177