feat(#717): re-base workflow size budget on bytes + document quality rationale (#719)

* feat(#717): re-base workflow size budget on bytes + document quality rationale

Re-base tests/workflow-size-budget.test.cjs from line counts to byte
counts (matches Codex's 32,768-byte project_doc_max_bytes cap; deterministic,
no tokenizer). Tier ceilings: XL=90000, LARGE=54000, DEFAULT=38000, GRACE=3000;
discuss-phase target re-expressed as <30 KB. The #597 tighten-only ratchet and
per-file budget semantics are preserved unchanged — only the unit swaps.

byteCount() uses fs.statSync().size to match `wc -c` (includes trailing
newline), deliberately not lineCount()'s newline-stripping.

Document the context-rot / attention-budget QUALITY rationale (independent of
prompt caching) in the test JSDoc and docs/ARCHITECTURE.md, plus the
Goodhart caveat: the byte budget measures one file, so the real goal is
bounded *loaded* context — eager @-imports game the proxy; legitimate
extraction is lazy. Update CONTEXT.md RULESET.WORKFLOW_SIZE_BUDGET to bytes and
remove a stale duplicate ruleset entry that still said "1800 lines".

Defers the #3182 MVP-mode split (tracked separately): MVP is a cross-cutting
concern woven through plan-phase/execute-phase, not a discrete extractable mode.

Closes #717

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs(#717): add changeset fragment for byte-budget re-base

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

docs/ARCHITECTURE.md

@@ -145,19 +145,43 @@ Orchestration logic that commands reference. Contains the step-by-step process i
 #### Progressive disclosure for workflows
 
 Workflow files are loaded verbatim into Claude's context every time the
-corresponding `/gsd-*` command is invoked. To keep that cost bounded, the
-workflow size budget enforced by `tests/workflow-size-budget.test.cjs`
-mirrors the agent budget from #2361:
+corresponding `/gsd-*` command is invoked. The workflow size budget enforced by
+`tests/workflow-size-budget.test.cjs` keeps each file bounded, mirroring the
+agent budget from #2361. The budget is measured in **bytes** (#717), not lines:
+line count over-penalizes prose and under-catches token-dense tables and code
+blocks, whereas bytes are deterministic and match the unit our vendors bound on
+— Codex truncates instruction docs past 32,768 bytes (`project_doc_max_bytes`).
+We adopt that unit, not that exact number: the XL/LARGE ceilings below sit above
+32,768 because these are grandfathered top-level orchestrators loaded by Claude,
+not Codex AGENTS.md docs.
 
-| Tier      | Per-file line limit |
-|-----------|--------------------|
-| `XL`      | 1700 — top-level orchestrators (`execute-phase`, `plan-phase`, `new-project`) |
-| `LARGE`   | 1500 — multi-step planners and large feature workflows |
-| `DEFAULT` | 1000 — focused single-purpose workflows (the target tier) |
+| Tier      | Per-file byte limit |
+|-----------|---------------------|
+| `XL`      | 90,000 — top-level orchestrators (`execute-phase`, `plan-phase`, `new-project`) |
+| `LARGE`   | 54,000 — multi-step planners and large feature workflows |
+| `DEFAULT` | 38,000 — focused single-purpose workflows (the target tier) |
 
-`workflows/discuss-phase.md` is held to a stricter <500-line ceiling per
-issue #2551. When a workflow grows beyond its tier, extract per-mode bodies
-into `workflows/<workflow>/modes/<mode>.md`, templates into
+Ceilings are not fixed forever: under the tighten-only ratchet (#597) each one
+tracks its tier's current high-water mark within a small grace band, so budgets
+may only decrease over time.
+
+**Why the budget exists.** With prompt caching the per-invocation *cost* of a
+large workflow is modest (cache reads run ~10% of input). The stronger,
+caching-independent reason is **quality**: as context grows, recall and
+reasoning degrade ("context rot" / attention budget), so leaner, higher-signal
+instructions produce better plans. The ceiling protects the agent's attention,
+not just the token bill.
+
+Because the budget measures one file, it is a proxy for the real goal —
+*bounded loaded context*. Extraction only helps when the extracted content is
+loaded **lazily** (Read at the step that needs it). Moving prose into a file
+that is still eagerly `@`-imported shrinks the measured file without shrinking
+loaded context, which games the proxy rather than serving the goal.
+
+`workflows/discuss-phase.md` is held to a stricter <30,000-byte ceiling per
+issue #2551 (originally <500 lines; re-based to bytes for #717). When a workflow grows
+beyond its tier, extract per-mode bodies into
+`workflows/<workflow>/modes/<mode>.md`, templates into
 `workflows/<workflow>/templates/`, and shared knowledge into
 `gsd-core/references/`. The parent file becomes a thin dispatcher that
 Reads only the mode and template files needed for the current invocation.