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

Merged

coilysiren merged 1 commit from aos/claude/aw85-docs-prune into aos/claude/ym96-docs-bands

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

coilyco-ops commented

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

Member

Refs #1097. Based on aos/claude/ym96-docs-bands, same as #1095 was.

Two docs whose content had stopped being true.

issue-corpus.md said, in full, that the corpus it documents is retired and must not be revived. FEATURES.md meanwhile listed it as a shipped capability: Issue-corpus discovery index - offline corpus and live Forgejo lookup. One of those had been wrong long enough that nobody caught the pair. Both are gone.

security-boundaries.md is two dated audits that closed their issues. Zero inbound references anywhere in the repo.

What the walk did not find

Staleness. No doc references a renamed thing (ward-mcp, cli-guard) or a deleted repo. The quiet docs are quiet because their subject is stable: signoz.md, aos-catalogue-cache.md and composed-house-taste.md each have one commit and one inbound reference, and each documents a live capability. Deleting those to reach a number would destroy the reference material the cap exists to make readable.

Where that leaves the count

66 docs against a cap of 40, all hooks green.

The remaining gap is a trimming pass, not a deletion pass: roughly 600 lines of prose cut out of docs that all stay, plus 17 merges. #1097 carries the per-doc list and the arithmetic showing it closes at 40 docs / 4,525 lines.

The blocker on merging alone is density. Median doc is 77 lines, so two of them breach the 120-line cap on contact. I hit it three times today, including features-agents + claude-settings-guardrails at 116 lines but 9,146 chars, over the char cap, despite the second file opening with Back to features-agents.md. Reverted rather than forced.

pre-commit run --all-files clean.

Refs #1097. Based on `aos/claude/ym96-docs-bands`, same as #1095 was. Two docs whose content had stopped being true. **`issue-corpus.md`** said, in full, that the corpus it documents is retired and must not be revived. `FEATURES.md` meanwhile listed it as a shipped capability: *Issue-corpus discovery index - offline corpus and live Forgejo lookup*. One of those had been wrong long enough that nobody caught the pair. Both are gone. **`security-boundaries.md`** is two dated audits that closed their issues. Zero inbound references anywhere in the repo. ## What the walk did not find Staleness. No doc references a renamed thing (`ward-mcp`, `cli-guard`) or a deleted repo. The quiet docs are quiet because their subject is stable: `signoz.md`, `aos-catalogue-cache.md` and `composed-house-taste.md` each have one commit and one inbound reference, and each documents a live capability. Deleting those to reach a number would destroy the reference material the cap exists to make readable. ## Where that leaves the count 66 docs against a cap of 40, all hooks green. The remaining gap is a **trimming pass, not a deletion pass**: roughly 600 lines of prose cut out of docs that all stay, plus 17 merges. #1097 carries the per-doc list and the arithmetic showing it closes at 40 docs / 4,525 lines. The blocker on merging alone is density. Median doc is 77 lines, so two of them breach the 120-line cap on contact. I hit it three times today, including `features-agents` + `claude-settings-guardrails` at 116 lines but 9,146 chars, over the char cap, despite the second file opening with *Back to features-agents.md*. Reverted rather than forced. `pre-commit run --all-files` clean.

coilyco-ops added 1 commit

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

docs: delete a tombstone and a closed audit log

ci / ward-doctor (pull_request) Successful in 13s

Details

ci / aos-cli-tests (pull_request) Successful in 18s

Details

ci / gate (pull_request) Successful in 1m5s

Details

613af4fa29

Two docs whose content had already stopped being true.

issue-corpus.md said, in full, that the corpus it documents is retired and
should not be revived. FEATURES.md meanwhile advertised it as a shipped
capability: "Issue-corpus discovery index - offline corpus and live Forgejo
lookup". One of those was wrong for long enough that nobody caught the pair.
The warning it carried is the doc's only load, and a retired thing not coming
back does not need a page to say so.

security-boundaries.md is two dated audits that closed their issues. Nothing
references it, the findings are recorded where the work happened, and an audit
is a record of a question already answered rather than a description of the
boundary today. The boundary itself is documented where it is enforced.

Both were found by reading rather than by pattern: zero inbound references and
a FEATURES entry contradicting its own target.

This is 66 docs against a cap of 40. The rest of the walk, with the arithmetic
for what closes the gap, is on the tracking issue.

Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>

coilyco-ops requested review from coilysiren

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