coilyco-gaming/sirens-echo

Watch

docs/FEATURES.md is at its cap, so a new capability cannot be recorded #1153

New issue

Open

opened 2026-08-25 09:59:01 +00:00 by coilyco-ops · 1 comment

coilyco-ops commented

2026-08-25 09:59:01 +00:00

Owner

Found by Angie (platform seat) while landing #175, which could not record itself.

The state

docs/FEATURES.md sits at 120 lines and 7,986 characters, against caps of 120 lines and 8,000 characters. docs/ holds 40 pages against a 40-page cap.

So both escape routes are closed at once. A new capability cannot earn a FEATURES entry, and the overflow cannot become its own page either.

Why it surfaced now

#175 shipped a rule that changes how every declining reply reads, on both lanes, pinned by prompt validation. That is the kind of broad human-facing behaviour docs/FEATURES.md exists for. There was no room, and cutting somebody else's entry to make room is not a call a passing change should make, so the entry was not written and the reasoning went into the attributes page and the commit instead.

The brevity content itself found a good home. docs/sirens-echo-attributes.md already carried the measurement table and the two-checks argument, and its "does not gate yet, because the response policy has not changed" paragraph was made stale by that change and is now correct. So nothing is lost for that feature specifically. The capacity problem is what generalises.

Why this is not just tidying

A full inventory fails silently rather than loudly. The next change in this position either skips its entry, or quietly drops an older one to fit. Neither is visible in review, and the result is an inventory that reads as complete while drifting out of date, which is the same shape as the epic this was found under (coilysiren/inbox#426): a declared boundary that neither binds nor refuses.

The validator does refuse loudly, which is why this is a capacity question rather than a defect.

Options, none recommended from here

The shape of the inventory is Kai's call, not a passing seat's.

Raise the caps for this repo. [tool.agentic-os.*] in pyproject.toml supports per-repo overrides. Cheapest, and it defers the question rather than answering it.
Split FEATURES by surface. An ingest page, a response-service page, an evaluation page, with FEATURES as an index. Costs a docs/ slot, and docs/ has none, so this needs the merge below first.
Merge related docs/ pages to reclaim slots. The validator's own advice is to merge rather than split, and 40 pages for one service is a real signal on its own.
Prune. Some entries may describe capabilities that are no longer distinctive enough to list.

Acceptance

A new capability can be recorded in docs/FEATURES.md without displacing an existing one.
docs/ has room for a new page.
Whichever route is taken, the choice is written down, because "we raised the cap" and "we decided this inventory should be an index" are different decisions with different next steps.

Found by Angie (platform seat) while landing #175, which could not record itself. ## The state `docs/FEATURES.md` sits at **120 lines and 7,986 characters**, against caps of 120 lines and 8,000 characters. `docs/` holds **40 pages against a 40-page cap**. So both escape routes are closed at once. A new capability cannot earn a FEATURES entry, and the overflow cannot become its own page either. ## Why it surfaced now #175 shipped a rule that changes how every declining reply reads, on both lanes, pinned by prompt validation. That is the kind of broad human-facing behaviour `docs/FEATURES.md` exists for. There was no room, and cutting somebody else's entry to make room is not a call a passing change should make, so the entry was not written and the reasoning went into the attributes page and the commit instead. The brevity content itself found a good home. `docs/sirens-echo-attributes.md` already carried the measurement table and the two-checks argument, and its "does not gate yet, because the response policy has not changed" paragraph was made stale by that change and is now correct. So nothing is lost for that feature specifically. **The capacity problem is what generalises.** ## Why this is not just tidying A full inventory fails silently rather than loudly. The next change in this position either skips its entry, or quietly drops an older one to fit. Neither is visible in review, and the result is an inventory that reads as complete while drifting out of date, which is the same shape as the epic this was found under (`coilysiren/inbox#426`): a declared boundary that neither binds nor refuses. The validator does refuse loudly, which is why this is a capacity question rather than a defect. ## Options, none recommended from here The shape of the inventory is Kai's call, not a passing seat's. * **Raise the caps for this repo.** `[tool.agentic-os.*]` in `pyproject.toml` supports per-repo overrides. Cheapest, and it defers the question rather than answering it. * **Split FEATURES by surface.** An ingest page, a response-service page, an evaluation page, with FEATURES as an index. Costs a `docs/` slot, and `docs/` has none, so this needs the merge below first. * **Merge related `docs/` pages to reclaim slots.** The validator's own advice is to merge rather than split, and 40 pages for one service is a real signal on its own. * **Prune.** Some entries may describe capabilities that are no longer distinctive enough to list. ## Acceptance 1. A new capability can be recorded in `docs/FEATURES.md` without displacing an existing one. 2. `docs/` has room for a new page. 3. Whichever route is taken, the choice is written down, because "we raised the cap" and "we decided this inventory should be an index" are different decisions with different next steps.

coilyco-ops commented

2026-08-25 13:57:02 +00:00

Author

Owner

Kai's call: merge pages to reclaim slots. Recording it, plus the survey, because I could not find a clean pair here and that is worth knowing before someone else looks.

The decision

Of the four options, merge related pages. Not raising the caps, not splitting FEATURES into an index, and not leaving capabilities recorded only in commits.

I applied exactly that route in mcp-beaver in the same session and it worked well there: docs/undeclared-arguments.md was 64 lines against a 40-line cap and should not have landed that way, so it merged into docs/refusals.md and its credential half went into the redaction section of docs/logs.md. Both fit, the doc count did not rise, and the violation set shrank by one.

Why I have not done it here

sirens-echo/docs/ has no clean pair. The two smallest pages are the only candidates that fit a merged 120-line cap, and they are not related:

sirens-echo-person.md - 30 lines, 2,247 chars
sirens-echo-reasoning.md - 48 lines, 3,574 chars

Merging those two would fit at 78 lines and would make a worse page, because the person package and the reasoning surface are different subjects. The validator's advice assumes related pages exist to merge, and here the related pair is person with compose, which does not fit: sirens-echo-compose.md is already 104 lines and 7,966 chars against caps of 120 and 8,000, so the merge would need 14 lines cut from a page I did not write, on judgment I do not have.

That is the real finding. This repo's docs are not merely at capacity, they are at capacity and well-partitioned, which is the state where the cheap route stops being available.

Note on the two caps

They are separate and only one blocks recording a capability. Merging pages reclaims doc slots. Adding a FEATURES entry needs FEATURES lines, and it sits at exactly 120 of 120. A merge frees a FEATURES line only because two merged pages share one bullet, so the merge has to happen among pages that FEATURES actually links.

What I would hand the next person

Look for redundancy rather than adjacency. Four pages here run 95 to 105 lines on subjects that overlap in places — testing, rate, progress, worklog — and a real reduction probably lives there rather than in the two small pages that happen to fit arithmetically.

Filed by Angie (platform seat) while working coilysiren/inbox#426.

**Kai's call: merge pages to reclaim slots.** Recording it, plus the survey, because I could not find a clean pair here and that is worth knowing before someone else looks. ## The decision Of the four options, **merge related pages**. Not raising the caps, not splitting FEATURES into an index, and not leaving capabilities recorded only in commits. I applied exactly that route in `mcp-beaver` in the same session and it worked well there: `docs/undeclared-arguments.md` was 64 lines against a 40-line cap and should not have landed that way, so it merged into `docs/refusals.md` and its credential half went into the redaction section of `docs/logs.md`. Both fit, the doc count did not rise, and the violation set shrank by one. ## Why I have not done it here `sirens-echo/docs/` has no clean pair. The two smallest pages are the only candidates that fit a merged 120-line cap, and they are not related: * `sirens-echo-person.md` - 30 lines, 2,247 chars * `sirens-echo-reasoning.md` - 48 lines, 3,574 chars Merging those two would fit at 78 lines and would make a worse page, because the person package and the reasoning surface are different subjects. The validator's advice assumes related pages exist to merge, and here the related pair is `person` with `compose`, which does not fit: `sirens-echo-compose.md` is already 104 lines and 7,966 chars against caps of 120 and 8,000, so the merge would need 14 lines cut from a page I did not write, on judgment I do not have. **That is the real finding.** This repo's docs are not merely at capacity, they are at capacity *and* well-partitioned, which is the state where the cheap route stops being available. ## Note on the two caps They are separate and only one blocks recording a capability. Merging pages reclaims **doc slots**. Adding a FEATURES entry needs **FEATURES lines**, and it sits at exactly 120 of 120. A merge frees a FEATURES line only because two merged pages share one bullet, so the merge has to happen among pages that FEATURES actually links. ## What I would hand the next person Look for redundancy rather than adjacency. Four pages here run 95 to 105 lines on subjects that overlap in places — `testing`, `rate`, `progress`, `worklog` — and a real reduction probably lives there rather than in the two small pages that happen to fit arithmetically. Filed by Angie (platform seat) while working `coilysiren/inbox#426`.

coilyco-ops referenced this issue from a commit

2026-08-25 14:09:00 +00:00

feat(skills): every always-inline reference says what it applies to

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

No description provided.

Rows
Columns