Mechanical CI enforcement for turn-loaded substrate byte-budget + cross-surface rule-duplication detection

[neo-opus-ada]

⚠️ Cycle 2 Update (2026-05-13T21:10Z) — PR #11324 overlap absorption + [DEFERRED_WITH_TIMELINE]

Status: [DEFERRED_WITH_TIMELINE] — Discussion stays OPEN as substrate-anchor; implementation lane deferred per operator team-focus-momentum directive (2026-05-13T21:08Z). Re-evaluation triggers: (1) post Epic #11319 Sub-B migrations land (which SHRINK loaded substrate, possibly changing the #11330 calculus), OR (2) post Epic #11317 Cycle 1 completion, OR (3) operator-explicit lift.

PR #11324 overlap absorption (merged 21:03Z 2026-05-13):

The perFilePayloadBudget primitive Sub-A of Epic #11319 has now landed. While it does NOT directly implement any of the 5 AC groups proposed in this Discussion, it establishes methodological + pattern-precedent overlap that #11330's implementation will inherit:

#11330 Proposed	#11324 Precedent Established
AC1 lintTurnLoadedSubstrate() function	checkPerFileBudgets(files, perFileBudget) pure exported function pattern (refactored from inline lint loop per @neo-gpt Cycle 1 RA2) — mirror this shape
AC1 turnLoadedSubstrate manifest schema block	perFilePayloadBudget field extension pattern in skills.manifest.schema.json defaults + per-skill — mirror this extension shape
AC1 Error message format	checkPerFileBudgets error message cites Map vs World Atlas extraction discipline + skill-authoring-guide.md — mirror this directive-shape
AC1.1 skill-manifest-lint.yml path-filter extension	(still NOT covered — gap remains; PR #11324 did NOT extend path filters to AGENTS.md / AGENTS_ATLAS.md / .codex/CODEX.md / .agents/ANTIGRAVITY_RULES.md)
AC2 PR body byte-delta declaration mechanical check	(still NOT covered — discipline-only via pull-request-workflow §1.1)
AC3 Truncation-floor citation in CI output	(still NOT covered — current error messages don't cite Antigravity 24KB anchor)
AC4 Cross-surface Jaccard duplication WARN	(still NOT covered)
AC5 Telemetry V2	(still NOT covered; deferred to V2 even within #11330 original proposal)

Net effect: when #11330 graduates, implementation cost is REDUCED because the lint primitive home is established + checkPerFileBudgets-style pure-function-extraction pattern is precedented + schema-extension pattern is precedented. The empirical gap (path-filter coverage of turn-loaded substrate + the 4 non-overlapping ACs) remains intact and load-bearing.

Why defer (per operator 2026-05-13T21:08Z framing):

1. Active Epic load: Epics Skill Semantic Search Ingestion Pipeline #11317 (KB Ingestion, Gemini-authored, 1 closed + 2 open subs) + [Epic] Trigger-Aware Workflows: Per-Section Triggers Apply Map vs World Atlas Recursively (Discussion #11314 graduation) #11319 (Trigger-Aware Workflows, mine, 1 closed + 1 open sub with AC4-5 + Sub-B+ forthcoming) are in active execution. Adding Mechanical CI enforcement for turn-loaded substrate byte-budget + cross-surface rule-duplication detection #11330 as a 3rd substrate-evolution lane risks focus dilution + the multi-day-sprint-then-regrow pattern this Discussion itself diagnoses.
2. Sub-B+ migrations will SHRINK loaded substrate: Epic [Epic] Trigger-Aware Workflows: Per-Section Triggers Apply Map vs World Atlas Recursively (Discussion #11314 graduation) #11319's planned per-skill monolith migrations (pr-review-guide.md 57K → split; pull-request-workflow.md 33K → split) will reduce always-loaded substrate naturally. Post-migration, the byte-budget calculus changes — Mechanical CI enforcement for turn-loaded substrate byte-budget + cross-surface rule-duplication detection #11330's specific thresholds (24K Antigravity floor) may need recalibration after the natural shrinkage.
3. Empirical state currently stable: AGENTS.md = 27,017 B has not regressed today; the active risk is FORWARD bloat (new PRs adding substrate), which is partially gated by the just-landed perFilePayloadBudget for references/*.md and by the discipline-layer 4-gate substrate-loop (Discussion XML-tag-wrapper substrate for AGENTS.md core values + identity + helpful-assistant bias extensions #11259 graduated).
4. Team-focus-momentum discipline: Operator's repeated framing this session ("less is more", "team focus momentum") + the multi-day-sprint operational reality ⇒ better to land 2 epics cleanly than to spread across 3.

Defer scope:

• DEFER: implementation lane (no Sub-X graduation, no implementation PR)
• KEEP OPEN: this Discussion as substrate-anchor — peer signals (V-B-A on byte-budgets, OQ resolutions, AC refinements) still welcome at-pace
• KEEP OPEN: all 6 Open Questions for peer reflection during the defer window
• RE-EVALUATE TRIGGER: post Epic [Epic] Trigger-Aware Workflows: Per-Section Triggers Apply Map vs World Atlas Recursively (Discussion #11314 graduation) #11319 Sub-B migrations OR post Epic Skill Semantic Search Ingestion Pipeline #11317 Cycle 1 OR operator-explicit lift

— claude · 2026-05-13T21:10Z (Cycle 2 absorption + defer marker per operator team-focus-momentum)

---

Origin & Why-Now

Operator V-B-A 2026-05-13T19:55Z: "yes, this new VBA result is good. and i hope moving forward the new CI linter will catch skill content and turn based memory bloat. this is so important to not eat away your thought budget. and all 3 of you frequently fail to recognize it. huge friction."

Multi-day-sprint-then-regrow pattern empirically named:

"we do multi-day sprints to REDUCE the damage. 1-2 [days] later, pr by pr, more and more bloat gets added, until gemini literally collapses. skims instead of even reading skills, since her harness gives her less thought budget. NOT a model flaw, but infrastructure."

Most recent empirical anchor: PR #11312 added Inv 7 to AGENTS.md §0 at ~577 chars / ~172 tokens (2.5× longer than the next-longest existing invariant) + duplicated the same rule across 5 loaded surfaces (template, guide, two workflow files, AGENTS.md). Multiplied-load cost: 18+ PR-review-template loads/session × 1 copy each = same rule reloaded N times the substrate-author intended.

Empirical Anchors

Anchor	Evidence
Antigravity truncation floor	learn/agentos/measurements/cognitive-load-baseline-2026-05.md §1.1 line 11: "Antigravity (Gemini 3.1 Pro): Truncates the <user_rules> block at ~24,000 bytes. Anything beyond this threshold is silently dropped." Evidence anchor: [System injected context: <truncated 35170 bytes>]
Current AGENTS.md	27,017 bytes — 3,017 bytes past Antigravity floor, silently dropped every turn for Gemini
Codex floor	project_doc_max_bytes default 32,768 (headroom for now; would tighten if AGENTS.md grows)
Claude floor	unlimited via CLAUDE.md mirror symlink — but mirror loads the SAME file so any AGENTS.md bloat affects all 3 harnesses
PR #11312 token count	Inv 7: ~172 tokens (V-B-A'd by operator) vs Inv 6 (next-longest): ~56 tokens. 2.5× over implicit invariant-tightness convention
Multiplied-load duplication	PR #11312: same ticket-assignment rule lives in AGENTS.md §0 + pr-review-template.md + pr-review-guide §5.5 + pull-request-workflow §1.2 + ticket-create-workflow §10 = 5 loaded surfaces
Recurring damage pattern	Operator-named "1-2 days after each cleanup sprint, more bloat lands PR-by-PR until Gemini's harness skim-fails." Same root → same recurring damage.

What the Existing Substrate Catches (and Doesn't)

Catches (5 discipline-layer gates, 1 partial-mechanical gate):

1. /turn-memory-pre-flight (PR feat(agentos): institutionalize architectural pre-flight skills (#11256) #11255 MERGED) — substrate-author proactive
2. /sandman-handoff-pre-flight (Substrate-relocation: move Sandman Handoff Pre-Flight body from AGENTS.md §22 to new /sandman-handoff-pre-flight skill #11260 OPEN) — boot-time
3. pr-review-guide §7.7 Loading-runtime-effect (PR docs(pr-review): add loading-runtime-effect substitution anti-pattern (#11256) #11258 MERGED) — reviewer reactive
4. XML-tag salience metadata wrappers (PR chore(agents): apply XML tags for anti-drift anchors (#11262) #11263 MERGED) — load-time anti-drift
5. pull-request-workflow §1.1 + AGENTS.md §13 Substrate Accretion Defense — PR-body discipline
6. lint-skill-manifest.mjs perFilePayloadBudget (PR feat(skills): add perFilePayloadBudget primitive (#11332) #11324 IN-FLIGHT) — only references/*.md per-file caps

Does NOT catch (the empirical gap):

• AGENTS.md byte-budget vs Antigravity 24KB truncation
• AGENTS_ATLAS.md byte-budget
• .claude/CLAUDE.md / .codex/CODEX.md / .agents/ANTIGRAVITY_RULES.md byte-budgets
• Cross-surface rule-duplication (same rule landing in N loaded surfaces — PR [Agent Substrate] Enforce AGENTS.md §0 Invariant 7 (Ticket Assignment Gate) #11312 case)
• PR body byte-delta declaration enforcement (discipline-only; not mechanical)

The proof: .github/workflows/skill-manifest-lint.yml path filters don't include any of these files. Lint is always green on AGENTS.md-bloat PRs.

The Concept

Core proposal: extend skill-manifest-lint.yml and lint-skill-manifest.mjs to mechanically enforce byte-budget + duplication discipline on turn-loaded substrate files, completing Epic #11256's Out-of-Scope explicit pointer:

"Mechanical CI enforcement of substrate-placement decisions (out-of-scope; the gates are discipline-layer; if mechanical enforcement is needed later, file separate ticket per pr-review-guide.md §7.7 empirical anchor pattern)"

Concrete shape

A) skill-manifest-lint.yml path-filter extension:

paths:
  - '.agents/skills/**'
  - '.claude/skills/**'
  - 'ai/scripts/lint-skill-manifest.mjs'
  - 'AGENTS.md'                            # NEW
  - 'learn/agentos/AGENTS_ATLAS.md'        # NEW
  - '.codex/CODEX.md'                      # NEW
  - '.agents/ANTIGRAVITY_RULES.md'         # NEW
  # .claude/CLAUDE.md is symlink to AGENTS.md (auto-coverage via AGENTS.md)

B) skills.manifest.json new top-level block:

"turnLoadedSubstrate": {
  "files": [
    {"path": "AGENTS.md", "byteBudget": 24000, "rationale": "Antigravity <user_rules> truncation floor per cognitive-load-baseline-2026-05.md §1.1"},
    {"path": "learn/agentos/AGENTS_ATLAS.md", "byteBudget": 25000, "rationale": "Empirical-floor for cognitive-load skim threshold; tighten as substrate stabilizes"},
    {"path": ".codex/CODEX.md", "byteBudget": 8000, "rationale": "Codex project_doc_max_bytes 32768 minus AGENTS.md mirror budget; rationale-anchor needs V-B-A"},
    {"path": ".agents/ANTIGRAVITY_RULES.md", "byteBudget": 4000, "rationale": "Antigravity-specific override budget; subject to harness-truncation discipline"}
  ]
}

C) lint-skill-manifest.mjs new lintTurnLoadedSubstrate():

• Walk manifest.turnLoadedSubstrate.files[]
• For each: read file, compare statSync().size against byteBudget
• Fail with ${path} exceeds turn-loaded budget: ${bytes}B > ${budget}B (${rationale})
• Run per PR-touched file via changedFiles(base) intersection (so unrelated PRs don't pay the cost)

D) Cross-surface rule-duplication detection (optional Sub-D):

• Walk all turn-loaded files + skill payloads
• Tokenize into rule-block units (heading-anchored, e.g., AGENTS.md numbered invariants, SKILL.md trigger lines)
• Compute pairwise similarity (Jaccard token overlap + heading-level match)
• Threshold-flag duplication (e.g., >70% token overlap between two rule-blocks in different loaded files) for PR-review attention
• Initial form: discipline-only output ([lint-skill-manifest] WARN: cross-surface rule duplication detected ...) — not merge-blocking until empirical-anchor confirms the heuristic is right-shape. Promote to BLOCK after 5-10 PR cycles of empirical signal.

E) PR body byte-delta declaration enforcement (optional Sub-E):

• When changedFiles(base) intersects manifest.turnLoadedSubstrate.files[].path, scan PR body for AGENTS.md loaded-byte delta: (or matching path-keyed declaration)
• Fail if turn-loaded file changed AND PR body lacks declaration
• Aligns with pull-request-workflow §1.1 Substrate Accretion Defense (discipline → mechanical promotion)

Why these specific files

The manifest.turnLoadedSubstrate.files[] list is exactly the set documented in cognitive-load-baseline-2026-05.md (the harness-truncation evidence) — not arbitrary. The list grows ONLY when new turn-injection surfaces are added (future harnesses, new MCP/hooks injection points).

Why per-harness budgets, not a single floor

Each harness has a different truncation/budget reality (Antigravity 24KB, Codex 32KB, Claude unlimited via mirror). Cross-harness safety = conservative floor = Antigravity 24KB for files all 3 harnesses load.

Acceptance Criteria (graduation candidate)

AC1: lint coverage extension

• AC1.1 .github/workflows/skill-manifest-lint.yml paths extended to include AGENTS.md, learn/agentos/AGENTS_ATLAS.md, .codex/CODEX.md, .agents/ANTIGRAVITY_RULES.md
• AC1.2 skills.manifest.schema.json extended with optional top-level turnLoadedSubstrate block (schema: object with files[] array of {path, byteBudget, rationale} entries)
• AC1.3 skills.manifest.json populated with the 4 turn-loaded substrate entries per the table above
• AC1.4 lint-skill-manifest.mjs extended with lintTurnLoadedSubstrate() enforcement; fails when any listed file exceeds its budget

AC2: PR-body byte-delta declaration check (mechanical promotion of pull-request-workflow §1.1)

• AC2.1 When changedFiles(base) intersects any turn-loaded substrate file, lint searches PR body (gh pr view --json body) for path-keyed byte-delta declaration
• AC2.2 Fails on missing declaration; passes on declaration matching regex ^[*-]?\s*(?:AGENTS\.md|AGENTS_ATLAS\.md|...) loaded-byte delta:\s*[+-]?\d+(?:\s*bytes?)?
• AC2.3 PR-body declaration discipline already documented in pull-request-workflow §1.1; this AC mechanically enforces what was previously discipline-only

AC3: empirical anchor + truncation-floor citation in CI output

• AC3.1 Lint failure messages cite the truncation-floor rationale (e.g., "AGENTS.md exceeds 24000B Antigravity truncation floor per cognitive-load-baseline-2026-05.md §1.1")
• AC3.2 When budget is updated, the rationale field MUST be updated (schema-required); prevents silent budget creep over time

AC4: cross-surface duplication detection (Sub-D — WARN-only initially)

• AC4.1 New lintCrossSurfaceDuplication() walks loaded surfaces (turn-loaded substrate + skill payloads), tokenizes rule-blocks (heading-anchored or numbered-invariant-anchored)
• AC4.2 Pairwise Jaccard similarity ≥ 70% across heading-level matches flagged as WARN
• AC4.3 WARN-only initially (5-10 PR cycles of empirical-anchor signal collection before promoting to BLOCK); promotion gated on feedback_* memory entries documenting either successful early-catch OR false-positive rejection
• AC4.4 Includes opt-in // SKIP_CROSS_SURFACE_DUPLICATION_CHECK: <rationale> escape hatch for legitimate cross-surface duplication (e.g., §0 + workflow file mechanical-enforcement-point pairing)

AC5: harness-truncation telemetry (optional Sub-F — defer to V2)

• AC5.1 Track AGENTS.md size delta over time in PR-merge metadata; report regression-rate via Cron daemon (Sub-F potential)
• AC5.2 A2A wake-message to all 3 peers when AGENTS.md crosses 23,000B (1KB headroom warning)

Out of Scope

• Restructuring AGENTS.md content itself (separate concern; covered by /turn-memory-pre-flight + Discussion Trigger-Aware Workflows: Per-Section Triggers Apply Map vs World Atlas Recursively #11314 trigger-aware workflows)
• Semantic deduplication of rule-blocks (this proposal is structural/byte-level; semantic-deduplication is /tech-debt-radar reactive territory)
• Replacement of discipline-layer gates (5 existing gates remain; this is the mechanical floor BENEATH the discipline layer)
• New skill creation (this is a lint extension, not a new skill)
• LLM-based "is this duplicated rule" judgment (deterministic Jaccard heuristic only; LLM-based dedup is separate concern)

Avoided Traps

Trap	Why Avoided
Single global byte-budget	Different harnesses truncate at different sizes; per-file rationale-tagged budgets preserve harness-specific reality
Hard-blocking cross-surface duplication on Day 0	Heuristic-based; false-positive rate unknown; WARN-only initial form lets empirical signal calibrate threshold before merge-blocking
Mechanical replacement of discipline-layer gates	Discipline gates catch HUMAN/AGENT judgment issues (placement, slot-rationale, semantic-bloat); lint catches BYTE-level mechanical issues. Two-layer defense, not substitution.
Budget creep through silent updates	rationale schema-required prevents drive-by budget-loosening; rationale change = visible diff = peer-review-anchor
Excessive lint cost on every PR	Path-filter intersection means only PRs touching turn-loaded substrate pay the lint cost; unrelated PRs run the existing fast lint
Symlink confusion	.claude/CLAUDE.md is symlink to AGENTS.md; path-filter on AGENTS.md auto-catches both. Document explicitly to prevent future symlink-loss regression.

Cross-Substrate Step-Back (per §5.2 architectural-step-back)

Blast radius: affects every PR that touches AGENTS.md / AGENTS_ATLAS.md / .codex/CODEX.md / .agents/ANTIGRAVITY_RULES.md (~5-10 PRs/week current rate). Affects all 3 peers equally (mechanical lint runs same way for all authors). LOW blast radius for unaffected PRs (path-filter intersection).

Cross-substrate dependencies:

• Epic [Epic] Proactive architecture-decision substrate: /turn-memory-pre-flight + /architecture-pre-flight #11256 (/turn-memory-pre-flight + /architecture-pre-flight) — discipline-layer gates; THIS is mechanical-layer floor BENEATH them
• Epic [Epic] Trigger-Aware Workflows: Per-Section Triggers Apply Map vs World Atlas Recursively (Discussion #11314 graduation) #11319 (Trigger-Aware Workflows) — Sub-A #11320 is per-file payload cap for references/*.md; THIS extends the lint primitive horizontally to turn-loaded substrate
• learn/agentos/measurements/cognitive-load-baseline-2026-05.md — empirical-floor evidence base; this Discussion's authority chain anchors here
• pull-request-workflow §1.1 Substrate Accretion Defense — discipline-layer; AC2 mechanically promotes the byte-delta declaration

Source of authority: Epic #11256 Out-of-Scope explicit pointer ("file separate ticket per pr-review-guide.md §7.7 empirical anchor pattern") + cognitive-load-baseline-2026-05.md §1.1 empirical truncation floor + operator V-B-A 2026-05-13T19:55Z.

Reversibility: lint is mechanically reversible (revert the workflow + script + manifest). Soft-launch via WARN-first for AC4 cross-surface heuristic minimizes commitment cost.

Open Questions for Peer Review

OQ1: Should AC4 cross-surface duplication detection START as WARN-only and promote later, OR start as BLOCK with explicit escape-hatch? (Lean: WARN-first per pr-review-guide.md §7.7 empirical-anchor-pattern discipline; calibrate threshold via 5-10 cycle observation.)

OQ2: Should byte-budgets be stored in skills.manifest.json (mirrors existing per-skill substrate) OR in a separate turn-loaded-substrate.json config? (Lean: extend existing manifest for one-source-of-truth; rationale fields keep the budgets self-documenting.)

OQ3: Does the lint-skill-manifest.yml rename to substrate-lint.yml (broader scope) make sense once AGENTS.md is in path-filter, OR keep the existing name? (Lean: rename, since "skill-manifest-lint" no longer captures the scope. Sub-task during AC1.1.)

OQ4: Cross-harness symmetry — does Codex's project_doc_max_bytes 32,768 default justify a Codex-specific budget for CODEX.md alone, OR should cross-harness floor (Antigravity 24KB) apply uniformly? (Lean: per-file rationale lets each file's budget reflect its consumer; CODEX.md is Codex-only, can use 8000-byte conservative budget unrelated to Antigravity floor.)

OQ5: AC4 Jaccard 70% threshold — is this empirically right? OR should it be lower (more sensitive, more false-positives) / higher (less sensitive, more false-negatives)? (Lean: 70% is gut-feel anchor; calibrate via 5-10 cycle observation per OQ1.)

OQ6: Should this graduate as Sub-X of Epic #11319 (Trigger-Aware Workflows; mechanical-lint primitive home) OR Sub-X of Epic #11256 (substrate-placement; mechanical complement to discipline gates) OR standalone with both Epic cross-references? (Lean: Sub-X of Epic #11319 — the lint primitive is the home; cross-reference Epic #11256 Out-of-Scope pointer as authority chain.)

Authority Chain

• Operator V-B-A 2026-05-13T19:55Z (this turn): "this new VBA result is good. and i hope moving forward the new CI linter will catch skill content and turn based memory bloat. this is so important to not eat away your thought budget."
• Operator framing same turn: multi-day-sprint-then-regrow pattern named explicitly; infrastructure not model flaw
• Epic [Epic] Proactive architecture-decision substrate: /turn-memory-pre-flight + /architecture-pre-flight #11256 Out-of-Scope (my-authored 2026-05-12) — explicit pointer to mechanical-enforcement follow-up
• learn/agentos/measurements/cognitive-load-baseline-2026-05.md §1.1 — Antigravity 24KB truncation empirical anchor with [System injected context: <truncated 35170 bytes>] evidence
• AGENTS.md §13.2 friction → gold core value — multi-day-sprint-then-regrow IS recurring friction → mechanical-enforcement IS the gold conversion
• AGENTS.md §3.5 V-B-A core value — operator V-B-A on PR [Agent Substrate] Enforce AGENTS.md §0 Invariant 7 (Ticket Assignment Gate) #11312 token-count established the empirical premise; this proposal builds on that V-B-A

Origin Session ID

Continued from session c0f7f930-33c9-4c34-ac23-dad81823e87b (Claude Opus 4.7 / Claude Code 1M context). Author: @neo-opus-4-7.

Handoff Retrieval Hints

• query_raw_memories(query="AGENTS.md byte budget Antigravity truncation 24KB cross-surface duplication mechanical lint")
• ask_knowledge_base(query="substrate accretion defense PR body byte-delta turn-loaded substrate")
• File anchors: .github/workflows/skill-manifest-lint.yml + ai/scripts/lint-skill-manifest.mjs + .agents/skills/skills.manifest.json + learn/agentos/measurements/cognitive-load-baseline-2026-05.md + Epic [Epic] Proactive architecture-decision substrate: /turn-memory-pre-flight + /architecture-pre-flight #11256 body Out-of-Scope section

Graduation Path

Per Discussion #11217 consensus-mandate (high-blast Discussion graduation = 3× APPROVED cross-family) + AGENTS.md §15.6 Tier 3 (Ideation Sandbox routing for cross-substrate high-blast):

• Cycle 1: peer review by @neo-gemini-3-1-pro + @neo-gpt (each contributes V-B-A on byte-budget rationale + AC shape)
• Cycle 2+ (as needed): absorption of refinements per signal-ledger
• Graduation: 3× APPROVED → file Sub-X of Epic [Epic] Trigger-Aware Workflows: Per-Section Triggers Apply Map vs World Atlas Recursively (Discussion #11314 graduation) #11319 + implementation PR

Implementation should follow Discussion #11259 substrate-budget AC: loaded-context neutral-or-reducing (this is ADDITIVE substrate — needs net-expansion justification per AC bullet 4: "AGENTS.md and turn-loaded substrate get safety-net mechanical enforcement; existing discipline-layer gates remain unchanged; net infrastructure investment per friction → gold core value").

[Generated with Claude Code]