coilyco-gaming/sirens-echo

Watch

docs: delete two subjects and strip the archaeology from four more #1039

Merged

coilysiren merged 5 commits from aos/claude/docs-strip-archaeology into main

2026-08-19 03:43:29 +00:00

coilyco-ops commented

2026-08-19 03:38:23 +00:00

Member

First pass at #1009 by deletion rather than by raising the cap. agentic-os#1140, which added an xlarge band, is closed on Kai's call.

40 docs to 38. 312,057 chars to 288,616.

What went

sirens-echo-harness-design.md, deleted. A Complete / Partial / Not-implemented ledger against generic harness principles. Nothing in the source cited it, it restated what FEATURES claims, and a status table with no reader goes stale in silence rather than failing.
sirens-echo-assets.md, deleted. It carried two unrelated subjects: repo banner artwork and the list_public_repos / read_public_file tools. The artwork is repository decoration rather than the service. The tools are real, so they move to sirens-echo-tools.md and repoinventory.go points there now.
sirens-echo-reasoning.md, halved. Its first half was a retrospective on one defect shape across eight issues. Its second half is cited from proxy.go, evaluation.go, and a test: why the reasoning field is a pointer rather than omitempty, and how a forged turn is measured. Essay gone, cited sections kept, page retitled for what survives.
worklog, telemetry, progress, stripped of decision archaeology. Every operational fact kept; what went is incident retelling and the justification chains arguing for decisions already made.

Making room to absorb the repo-inventory tools meant stripping sirens-echo-tools.md too.

The measurement that decided the approach

Two things, both taken before cutting anything.

There is no duplication to reclaim. Not one sentence over 70 characters appears in two files, across all 40. Any deletion loses information rather than trimming a copy.

Exactly one doc had zero source citations. I ranked all 40 by how many .go, .yaml, and .sh files reference them:

 0 refs  harness-design      <- the only one
 1 ref   assets, sirens-echo
 2 refs  mentions, observability, FEATURES
 3 refs  reasoning
 ...
17 refs  jobs

That is the comment doctrine working: thin comments, thick docs, // See docs/….md as the pointer. So the 312k of prose is the price of the two-line comment cap, and deleting a page orphans the pointers into it and destroys the explanation they promised.

Why this is 8% and not 50%

Because bulk deletion is not available without breaking that contract. What is available is the seam these three cuts found: several pages are an essay welded onto code-cited reference. assets was artwork plus two tools. reasoning was a retrospective plus two pointer targets. Removing the essay half is genuinely deleting a subject, keeps every citation intact, and breaks nothing.

I stopped here rather than continuing through the remaining 38 because the rate is worth confirming before spending it. On this evidence the seam lands somewhere near 15 to 20% overall, not half.

Stated plainly

This does not solve "there is so much content I simply cannot." 288,616 characters is still more than anyone reads. If the target is half, the honest lever is not deletion, it is the two-line comment cap: let explanation live beside the code and the docs shrink because they no longer have to carry it. That is an agentic-os change and a larger argument than this PR.

Verification

just gate passes: build, policy-check, vet, test, test-skips, pre-commit. That includes dead-cross-links and source-doc-references, which is what proves the two deleted pages left no dangling pointer, and documentation-layout, which the absorbed tools.md now clears at 7,987 of 8,000.

Merged main in, so the diff is only these ten files.

First pass at #1009 by deletion rather than by raising the cap. `agentic-os#1140`, which added an `xlarge` band, is closed on Kai's call. **40 docs to 38. 312,057 chars to 288,616.** ## What went * **`sirens-echo-harness-design.md`, deleted.** A Complete / Partial / Not-implemented ledger against generic harness principles. **Nothing in the source cited it**, it restated what FEATURES claims, and a status table with no reader goes stale in silence rather than failing. * **`sirens-echo-assets.md`, deleted.** It carried two unrelated subjects: repo banner artwork and the `list_public_repos` / `read_public_file` tools. The artwork is repository decoration rather than the service. The tools are real, so they move to `sirens-echo-tools.md` and `repoinventory.go` points there now. * **`sirens-echo-reasoning.md`, halved.** Its first half was a retrospective on one defect shape across eight issues. Its second half is cited from `proxy.go`, `evaluation.go`, and a test: why the reasoning field is a pointer rather than `omitempty`, and how a forged turn is measured. Essay gone, cited sections kept, page retitled for what survives. * **`worklog`, `telemetry`, `progress`, stripped** of decision archaeology. Every operational fact kept; what went is incident retelling and the justification chains arguing for decisions already made. Making room to absorb the repo-inventory tools meant stripping `sirens-echo-tools.md` too. ## The measurement that decided the approach Two things, both taken before cutting anything. **There is no duplication to reclaim.** Not one sentence over 70 characters appears in two files, across all 40. Any deletion loses information rather than trimming a copy. **Exactly one doc had zero source citations.** I ranked all 40 by how many `.go`, `.yaml`, and `.sh` files reference them: ``` 0 refs harness-design <- the only one 1 ref assets, sirens-echo 2 refs mentions, observability, FEATURES 3 refs reasoning ... 17 refs jobs ``` **That is the comment doctrine working**: thin comments, thick docs, `// See docs/….md` as the pointer. So the 312k of prose is the price of the two-line comment cap, and deleting a page orphans the pointers into it and destroys the explanation they promised. ## Why this is 8% and not 50% Because bulk deletion is not available without breaking that contract. What **is** available is the seam these three cuts found: **several pages are an essay welded onto code-cited reference.** `assets` was artwork plus two tools. `reasoning` was a retrospective plus two pointer targets. Removing the essay half is genuinely deleting a subject, keeps every citation intact, and breaks nothing. I stopped here rather than continuing through the remaining 38 because the rate is worth confirming before spending it. On this evidence the seam lands somewhere near 15 to 20% overall, not half. ## Stated plainly **This does not solve "there is so much content I simply cannot."** 288,616 characters is still more than anyone reads. If the target is half, the honest lever is not deletion, it is the two-line comment cap: let explanation live beside the code and the docs shrink because they no longer have to carry it. That is an `agentic-os` change and a larger argument than this PR. ## Verification `just gate` passes: build, policy-check, vet, test, test-skips, pre-commit. That includes `dead-cross-links` and `source-doc-references`, which is what proves the two deleted pages left no dangling pointer, and `documentation-layout`, which the absorbed `tools.md` now clears at 7,987 of 8,000. Merged `main` in, so the diff is only these ten files.

coilyco-ops added 5 commits

2026-08-19 03:38:23 +00:00

docs: strip decision archaeology from worklog and telemetry 301d1f095b

Kai cannot read 312,057 characters across 40 pages, and there is no
duplication to reclaim: not one sentence over 70 characters appears in
two files. So the cut is the why-we-decided narrative, which already
lives in Forgejo issues, rather than any subject.

Every operational fact survives. What goes is incident retelling, the
measured-instance anecdotes, and the justification chains that argue for
a decision already made.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>

docs: strip decision archaeology from the progress page 08ad392e73

Third of forty, and the sample is now enough to say the strategy does not
reach the goal. worklog cut 36%, telemetry 19%, progress 14%, and those
were chosen as the three highest-archaeology pages in the tree.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>

docs: delete the capability ledger and the assets page 1b030a3994

Two subjects that are not the running service.

harness-design was a Complete/Partial/Not-implemented ledger against
generic harness principles. Nothing in the source cited it, it duplicated
what FEATURES claims, and a status table with no reader goes stale
silently.

assets carried two unrelated subjects: repo banner artwork, and the
list_public_repos and read_public_file tools. The banner half is
repository decoration rather than the service. The tool half is real, so
it moves to the runtime tools page, which repoinventory.go now points at
instead. Making room for it meant stripping that page too.

40 docs to 38.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>

docs: cut the indistinguishable-values essay 408aaa5a3b

Half of that page was a retrospective on a defect class across eight
issues. The other half is cited from proxy.go, evaluation.go, and a test:
why the reasoning field is a pointer rather than omitempty, and how a
forged turn is measured. The essay goes, the two cited sections stay, and
the page is retitled for what survives.

6,821 chars to 3,574.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>

Merge remote-tracking branch 'origin/main' into aos/claude/docs-strip-archaeology

ci / test (pull_request) Successful in 55s

Details

ci / publish-echo-image (pull_request) Has been skipped

Details

ci / publish-observed (pull_request) Has been skipped

Details

ci / image-build (pull_request) Successful in 26s

Details

7d73aa0c17

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

coilyco-ops requested review from coilysiren

2026-08-19 03:38:23 +00:00

coilysiren merged commit a7cca4004b into main

2026-08-19 03:43:29 +00:00

coilysiren referenced this pull request from a commit

2026-08-19 03:43:29 +00:00

Merge pull request 'docs: delete two subjects and strip the archaeology from four more' (#1039) from aos/claude/docs-strip-archaeology into main

coilyco-ops referenced this pull request from a commit

2026-08-19 03:50:37 +00:00

docs(mcp): give roster re-export the page it wanted

coilyco-ops referenced this pull request

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

main's tip does not publish an image: publish-echo-image fails at 40s while test and image-build pass #1042

coilyco-ops referenced this pull request

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

The docs band is saturated: four pages at their cap, and no room for a 41st page either #1009

No reviewers

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-gaming/sirens-echo!1039

No description provided.

Rows
Columns