Context
Surfaced while reviewing PR #17258 (resolves #17143), and filed by that review's author as a commitment made in the review body — the AC that produced this situation was mine.
#17143 mandated the session signature in ideation-sandbox and created a shared statement at learn/agentos/process/session-signature.md. That was the right shape: the canonical rule text now lives outside the skills byte budget, so restatements can compress by pointing at it instead of duplicating it.
The side effect is the subject of this ticket. After #17258, ideation-sandbox-workflow.md sits at 24,906 B against its 25,000 B budget — 94 bytes of headroom, roughly 99.6% full.
The Problem
This is not a defect and nothing is currently broken. The guard fails loud: ai/scripts/diagnostics/check-substrate-size.mjs ends in process.exit(1) behind an explicit ❌ Substrate Size Check FAILED! banner, and .github/workflows/substrate-size-guard.yml runs it in CI. An overrun is blocked, never silently truncated. This is emphatically not the silent-failure class.
The problem is who pays. The next person with a legitimate ideation-sandbox addition inherits a compression they did not scope. 94 bytes is roughly one sentence. Their PR goes red on a guard that is correct, for a reason that has nothing to do with their change, and they either abandon the addition or open an unplanned refactor inside an unrelated lane. That is a tax levied on whoever arrives next, and it is charged at the least convenient moment.
The asymmetry worth naming: #17258 could not have avoided this. ideation-sandbox had zero prior coverage — that absence was #17143's entire premise — so adding the mandate could not be byte-free, and reaching net-zero would have meant compressing unrelated sibling payloads as scope creep. The bill is real; it simply belongs to a ticket rather than to that PR.
The Architectural Reality
#17258 built the mechanism that makes this cheap to fix, which is why this is a follow-up rather than a redesign. The pattern is established and proven in that PR: a payload restating a rule compresses to a one-line pointer at the shared statement, and ticket-create-workflow.md demonstrates it at −231 B for a single restatement.
Several sibling payloads still carry Origin Session ID text that has a destination to point at now. Note that string presence is not the same as a compressible restatement — some occurrences are template fields or body-structure entries that must stay verbatim. The census below is a starting set to audit, not a work list to execute blindly:
epic-resolution · memory-mining · pull-request/review-response-protocol · pr-review-guide · pull-request-workflow · session-sunset
Reference sizes at the time of filing (wc -c, unrelated payloads that are also large — context, not targets):
| payload |
bytes |
pr-review/references/pr-review-guide.md |
33,341 |
ideation-sandbox/references/ideation-sandbox-workflow.md |
24,484 (pre-#17258) |
ticket-create/references/ticket-create-workflow.md |
23,599 |
peer-role/references/peer-role-mode.md |
22,813 |
Budgets are per-group, not a uniform per-file 25,000 — COMBINED_BUDGETS in the guard defines them, and pr-review-guide.md exceeding 25,000 is not a violation because it belongs to a different group. Do not infer a target from raw size; read the guard's own output.
The Fix
Audit the sibling restatements and compress the genuine ones to the session-signature.md pointer, banking headroom in the ideation-sandbox budget group first. One PR; the mechanism already exists and needs no design.
Deliberately not prescribing a byte target. A number invented here would be arbitrary, and "compress until a threshold is hit" invites compressing text that should stay. The right stopping point is "every genuine restatement now points at the shared statement", and whatever headroom that yields is the honest answer.
Acceptance Criteria
Out of Scope
- Changing any budget's limit. If a group's limit is genuinely wrong, that is a separate argument with its own evidence; raising a cap to fit content is the opposite of this ticket.
- The session-signature rule's content or the artifact classes it covers (#17143, delivered by PR #17258).
- Compressing payloads for their own sake. This is targeted at restatements with an established destination, not a general thinning pass — D#17085 owns that axis.
Avoided Traps
- Treating this as a #17258 defect. It is not. That PR could not have been byte-free, and its placement decision is what makes this ticket cheap.
- Compressing by string match.
Origin Session ID appears in template fields that must render verbatim; a mechanical sweep would eat them. Hence the classification AC.
- Inventing a byte target. A threshold picked here would be reverse-engineered from nothing and would license compressing text that should stay.
- Reading raw file size as a violation. Budgets are grouped;
pr-review-guide.md at 33 KB is compliant.
Related
#17143 (the mandate) · PR #17258 (delivered it; this ticket is its recorded follow-up) · D#17085 (substrate thinning — the general axis this ticket deliberately does not open) · ai/scripts/diagnostics/check-substrate-size.mjs · .github/workflows/substrate-size-guard.yml
Live latest-open sweep: latest 12 open issues checked 2026-08-16T21:01:00Z immediately before creation; no equivalent — #17246/#17248/#17251 are unrelated surfaces. A2A in-flight claim sweep: mailbox drained this session; no claim on skill-payload compression.
Origin Session ID: b17338dd-b474-494f-b08c-683044de2ddb
Retrieval Hint: "ideation-sandbox 94 bytes headroom compress session-signature restatements substrate size budget group"
Context
Surfaced while reviewing PR #17258 (resolves #17143), and filed by that review's author as a commitment made in the review body — the AC that produced this situation was mine.
#17143 mandated the session signature in
ideation-sandboxand created a shared statement atlearn/agentos/process/session-signature.md. That was the right shape: the canonical rule text now lives outside the skills byte budget, so restatements can compress by pointing at it instead of duplicating it.The side effect is the subject of this ticket. After #17258,
ideation-sandbox-workflow.mdsits at 24,906 B against its 25,000 B budget — 94 bytes of headroom, roughly 99.6% full.The Problem
This is not a defect and nothing is currently broken. The guard fails loud:
ai/scripts/diagnostics/check-substrate-size.mjsends inprocess.exit(1)behind an explicit❌ Substrate Size Check FAILED!banner, and.github/workflows/substrate-size-guard.ymlruns it in CI. An overrun is blocked, never silently truncated. This is emphatically not the silent-failure class.The problem is who pays. The next person with a legitimate
ideation-sandboxaddition inherits a compression they did not scope. 94 bytes is roughly one sentence. Their PR goes red on a guard that is correct, for a reason that has nothing to do with their change, and they either abandon the addition or open an unplanned refactor inside an unrelated lane. That is a tax levied on whoever arrives next, and it is charged at the least convenient moment.The asymmetry worth naming: #17258 could not have avoided this.
ideation-sandboxhad zero prior coverage — that absence was #17143's entire premise — so adding the mandate could not be byte-free, and reaching net-zero would have meant compressing unrelated sibling payloads as scope creep. The bill is real; it simply belongs to a ticket rather than to that PR.The Architectural Reality
#17258 built the mechanism that makes this cheap to fix, which is why this is a follow-up rather than a redesign. The pattern is established and proven in that PR: a payload restating a rule compresses to a one-line pointer at the shared statement, and
ticket-create-workflow.mddemonstrates it at −231 B for a single restatement.Several sibling payloads still carry
Origin Session IDtext that has a destination to point at now. Note that string presence is not the same as a compressible restatement — some occurrences are template fields or body-structure entries that must stay verbatim. The census below is a starting set to audit, not a work list to execute blindly:epic-resolution·memory-mining·pull-request/review-response-protocol·pr-review-guide·pull-request-workflow·session-sunsetReference sizes at the time of filing (
wc -c, unrelated payloads that are also large — context, not targets):pr-review/references/pr-review-guide.mdideation-sandbox/references/ideation-sandbox-workflow.mdticket-create/references/ticket-create-workflow.mdpeer-role/references/peer-role-mode.mdBudgets are per-group, not a uniform per-file 25,000 —
COMBINED_BUDGETSin the guard defines them, andpr-review-guide.mdexceeding 25,000 is not a violation because it belongs to a different group. Do not infer a target from raw size; read the guard's own output.The Fix
Audit the sibling restatements and compress the genuine ones to the
session-signature.mdpointer, banking headroom in theideation-sandboxbudget group first. One PR; the mechanism already exists and needs no design.Deliberately not prescribing a byte target. A number invented here would be arbitrary, and "compress until a threshold is hit" invites compressing text that should stay. The right stopping point is "every genuine restatement now points at the shared statement", and whatever headroom that yields is the honest answer.
Acceptance Criteria
session-signature.md) or must stay verbatim (template field / body-structure entry), with the classification recorded in the PR body — not silently skipped.learn/agentos/process/session-signature.md; no payload states the rule twice.wc -c, plus the resulting headroom as reported bycheck-substrate-size.mjsitself, not computed by hand against an assumed cap.ideation-sandboxbudget-group headroom is materially larger than the 94 B this ticket was filed against.npm run ai:check-substrate-sizepasses.Out of Scope
Avoided Traps
Origin Session IDappears in template fields that must render verbatim; a mechanical sweep would eat them. Hence the classification AC.pr-review-guide.mdat 33 KB is compliant.Related
#17143 (the mandate) · PR #17258 (delivered it; this ticket is its recorded follow-up) · D#17085 (substrate thinning — the general axis this ticket deliberately does not open) ·
ai/scripts/diagnostics/check-substrate-size.mjs·.github/workflows/substrate-size-guard.ymlLive latest-open sweep: latest 12 open issues checked 2026-08-16T21:01:00Z immediately before creation; no equivalent — #17246/#17248/#17251 are unrelated surfaces. A2A in-flight claim sweep: mailbox drained this session; no claim on skill-payload compression.
Origin Session ID: b17338dd-b474-494f-b08c-683044de2ddb Retrieval Hint: "ideation-sandbox 94 bytes headroom compress session-signature restatements substrate size budget group"