The hourglass has inverted: half the core is an operating manual, not engineering policy

[braboj]

The hourglass has inverted

The design is a tight core that barely changes, with rich integration above
and below. Measured 2026-09-03:

                      files      KB   share   edits since v2.55.0
WAIST  base/core         12     310   40.3%   71
WAIST  base/workflow      9     159   20.7%   31
END    stack             17     106   13.8%   11
END    backend           18      68    8.9%    0
END    frontend           3      17    2.2%    0

WAIST  61.1% of bytes, 102 edits
ENDS   30.1% of bytes,  16 edits

The waist is twice the size of both ends combined and takes six times the
churn. backend/ holds the most files of any layer and has not been touched
in 22 releases; frontend/ likewise. The average waist file is 26KB, the
average end file 4KB — seven to one, the wrong way round.

Supporting measurements: 12 of the 16 template file-touches across
v2.63.0..v2.77.0 landed in base/core and base/workflow; one in stack.
Zero template files have been deleted since v2.55.0. Control: the same probe
sees 3 stack/backend/frontend files in the preceding eight releases, so it is
not blind.

The test

A rule belongs in the waist only if changing the stack, the platform, or the
team's way of working would not change it.

"Branch naming is feat/<scope>" survives it. "The release runs nine steps,
here are the twelve gh commands" does not — that is one team's answer.
A heading ending in "(if applicable)" is the section declaring its own failure.

Result of applying it to all 226 sections

verdict	bytes	share
KEEP — invariant policy	181,365	38.4%
MOVE — process layer	232,694	49.3%
MOVE — stack/platform end	52,315	11.1%
MOVE — language end	5,320	1.1%
total waist today	471,694

Nearly half the waist is an operating manual for running an agent-assisted
repository. It is good material. It is not synthesized engineering policy,
and it currently ships to every consumer of every stack.

Per file

file	keep	process	end	lang
workflow/quality-gates.md	30,050	36,109
core/git.md	7,476	57,266
core/docs.md	46,715	5,803	11,756
core/quality.md	33,355	1,459	24,003
core/testing.md	37,124	2,997	5,517	5,320
workflow/ai-workflow.md		38,487
workflow/360.md		20,890
core/review.md	4,711	14,137
core/agents.md		17,558
workflow/scope.md		12,697
workflow/issues.md		11,127
core/config.md	7,887
core/readme.md	7,418
core/examples.md			6,625
core/skills.md		6,458
core/cli.md			4,414
core/oop.md	3,958
workflow/two-pass-review.md		3,559
workflow/compression.md		3,379
workflow/release.md	2,671
workflow/communication.md		768

core/git.md is the sharpest case: 88% process. Its invariant content —
committer identity, commit messages, branching, versioning, .gitignore,
general — is 7.5KB. "Release process" and "Pull requests" are 54KB of it.

Nine files are 100% process and move whole: ai-workflow, 360, agents,
scope, issues, skills, two-pass-review, compression,
communication. Four are 100% keep: config, readme, oop, release.

What it buys

Measured by re-resolving all 37 roots with the non-keep sections removed:

root	today	after	cut
base-communication (floor)	269,146	140,120	48%
stack-nodejs-lib (median)	299,034	159,737	47%
stack-django (ceiling)	467,003	291,597	38%

Mean cut across 37 roots: 44%. The floor moves from ~67k tokens to ~35k,
the ceiling from ~116k to ~72k.

Where the judgement is arguable

These are my calls and the ones worth challenging first:

• quality.md's "Calibration discipline" (9KB) and "Cross-validation and
  tool trust" (12KB) marked END. They are genuinely deep, but they address a
  project that calibrates against reference data — a data/ML shape, not every
  consumer.
• quality-gates.md split roughly in half. The gate model, categories,
  thresholds and pair-a-constraint-with-its-check are invariant; "Run the check
  in the form it ships" (13KB) and "Gate scope agreement" (7.5KB) are this
  project's operating discipline.
• docs.md's "Development journal" marked process — it is an
  agent-assisted-workflow artifact, not a documentation universal.
• testing.md's pytest-specific sections (autouse fixtures, class-attribute
  resource allocation, AST meta-tests) marked LANG. They name Python mechanics
  in a stack-agnostic file.

Acceptance criteria

• A decision on whether the process layer becomes an opt-in root (like
  platform/) or a separate published artifact
• The split is executed so base/core holds only what survives the test
• A rule states the test, so the next addition has somewhere to be judged —
  without it the waist re-inflates by the same mechanism that filled it:
  nobody adds to the core deliberately, they add to whichever file already
  discusses the topic
• The chain-budget ceiling is re-based after the split, and The chain ceiling has been raised 313 times and lowered none, so it prices growth rather than refusing it #1462 is
  resolved in the same pass — a cap that has never refused anything cannot
  hold the new floor either

Provenance

Raised by the owner on 2026-09-03 after reviewing #1462: "the idea was to
synthesize the core engineering policies that are more or less known and refine
them with own knowledge, but clearly we are incrementing indefinitely."

The classification is reproducible: section boundaries are H2 headings outside
fenced blocks, sizes are bytes between headings, and every one of the 226
sections carries a verdict — 0 unclassified.

Related: #1462 (the ceiling prices growth rather than refusing it), #1470 (the
chains grew 45% in eight days at a flat stack count), #1471 (twenty template
files reach no stack chain).

Consolidated core-boundary review (owner-approved, 2026-09-05)

This issue owns the review previously duplicated in #1505. Inventory current core files, including CLI, examples, skill-authoring, and agent-output conventions, and map each to its responsibility and proposed home. Distinguish directory ownership from explicit manifest core: membership; report affected roots and context changes for semantic rewiring.

Coordinate final placement with #1504 so files move once. #727 retains the OOP reach decision and #712 retains delivery mechanics. Related layout and ownership choices may share one architectural decision; no separate ADR is required per issue. Apply the threshold being corrected in #1506.

#1353 and #1506 are the immediate adoption/policy fixes and do not wait for this v3.0 split. This issue remains the larger structural change, not a new hierarchy of process tickets.

---

Superseded citation, corrected 2026-09-06

The last acceptance criterion — "The chain-budget ceiling is re-based after the
split, and #1462 is resolved in the same pass" — can no longer be met.
ADR-041 deleted tests/chain-budget.txt and SYS-12 in v2.82.0 and closed
#1462. Chain size is now reported in README.md's model-limits table and
nothing caps it.

The criterion's reasoning was right and is settled rather than pending: a cap
that refused nothing could not hold the new floor either, so there is no cap.
Read the criterion as discharged. What a split still owes a reader is the
model-limits table, regenerated by tools/sync.py and gated by
sync.py --check.

[braboj]

This and #712 are the same restructure on two axes, and they constrain each
other.

• Restructure rule delivery around progressive disclosure (references load nothing on demand) #712 is about delivery: which rules reach the agent, and its finding is
  that a referenced template loads nothing — no startup load, no load on
  relevance, no description surfaced. A reference has the shape of progressive
  disclosure with the engine removed.
• This issue is about composition: which rules belong in the always-loaded
  core at all.

The interaction matters for the acceptance criterion here that asks whether the
process layer becomes an opt-in root or a separate artifact. Under #712's
finding, "opt-in root delivered as a reference" is not a middle position — it
is deletion with a pointer left behind. 233KB of operating manual would stop
reaching any agent, silently, and the project would read as having kept it.

So the split has three real options, not two:

1. Opt-in root, resolved into the chain — a project that wants the process
   layer gets it inlined, the way platform/ works today. Costs those projects
   the full 233KB; costs everyone else nothing. Compatible with Restructure rule delivery around progressive disclosure (references load nothing on demand) #712 because
   nothing is delivered by reference.
2. A skill — the one mechanism Restructure rule delivery around progressive disclosure (references load nothing on demand) #712 identifies as actually having
   progressive disclosure: frontmatter always in context, body loaded on
   demand. core/skills.md already carries the authoring rules, and the
   process layer is procedure-and-judgment, which is exactly what that file
   says a skill is for.
3. A separate published artifact — its own repository or document, outside
   the composition model entirely.

Option 2 is the one worth measuring, because it is the only shape that keeps
the material reachable without charging every consumer for it — and the
material's own template says that is what skills are for.

Whichever is chosen, the ordering is: decide composition here, then delivery
in #712. Deciding delivery first fixes a mechanism around content that has not
been sorted yet.

[braboj]

Two dimensions of the 2026-09-06 360 audit substantiated this independently,
with sharper numbers than the issue carries.

Architecture measured the core. Six files sit in 100% of all 37 chains:
267,721 characters, 34.5% of the 74-file corpus. git.md is 65KB of that, and
57,330 of its 64,899 sectioned characters — 88.3% — are repository-operations
procedure: PR merging, stack de-stacking, release cutting, repo migration. That
is 21.4% of every chain. The ### Pre-release checks section alone is 18,508
characters, 6.91% of every chain, 2.5× the entire readme.md core file.

The smallest pickable chain, base-communication, is 270,310 bytes and 99.7%
core — up from 96.9% at the 2026-09-03 audit. The hourglass tightened while
this sat open.

Suggested first move, from the same reviewer: split base-git into policy
(identity, commits, branching, versioning) and a base-release-ops opt-in root.

Value measured the same thing from the adopter's side. The stack-specific
share of a resolved chain runs 1.9%–13.5%. stack-c-embedded resolves to 7
files, 6 of them the shared core: 98.1% of its 273K characters are
byte-identical to what a Django project receives, and only 5,278 characters
are embedded-C rules. The README prices that chain at ~78K tokens without
disclosing the ratio.

Per-chain stack share: c-embedded 1.9%, htmx 3.5%, nodejs-lib 3.8%, python-lib
6.6%, go-service 9.9%, fastapi 13.5%. Control: the same probe shows django's
29-file chain differing, so it is not a uniform positive.

Authoring found the lever. 761 of 914 RFC 2119 keywords are absolutes
(83%), grown 367 → 918 since v2.1.0 with the file count flat at 75. Twenty-four
files carry at least one MUST and zero SHOULD and zero MAY. quality-gates.md
alone is 107 absolutes against 7 SHOULD and 4 MAY. A corpus at 83% absolute has
no vocabulary left for a recommendation, which is why every downstream lesson
arrives as another MUST in a file every chain carries.

[braboj]

A chain-size data point from the v2.89.0 cut, 2026-09-11, measured on 4b0c41d.

The STK-15 canary (python-lib) now fills the e2e runner's 65,536-token output limit:

• The prompt is 481,754 characters, 115,868 input tokens.
• Gemini 2.5 Flash returned finish_reason MAX_TOKENS after 62,937 output and 2,595 thinking tokens.
• The inline output model writes the chain out, so the generated file grows with the core tier. The response was cut off mid-line at 261.6K characters.

Details and the runner fix are in #1676. This is relevant here because output size, not just context size, now limits which chains can be generated in a single response.