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

> ## ⚠️ 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 #11317 (KB Ingestion, Gemini-authored, 1 closed + 2 open subs) + #11319 (Trigger-Aware Workflows, mine, 1 closed + 1 open sub with AC4-5 + Sub-B+ forthcoming) are in active execution. Adding #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 #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 — #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 #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 #11319 Sub-B migrations OR post Epic #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

What the Existing Substrate Catches (and Doesn't)

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

1. /turn-memory-pre-flight (PR #11255 MERGED) — substrate-author proactive
2. /sandman-handoff-pre-flight (#11260 OPEN) — boot-time
3. pr-review-guide §7.7 Loading-runtime-effect (PR #11258 MERGED) — reviewer reactive
4. XML-tag salience metadata wrappers (PR #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 #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 #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 #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

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 #11256 (/turn-memory-pre-flight + /architecture-pre-flight) — discipline-layer gates; THIS is mechanical-layer floor BENEATH them
• Epic #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 #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 #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 #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 #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]