Fail net-positive skill Markdown growth

Context

Release classification: post-release hardening (model-experience / cognitive-load guard; not required to ship v13).

This is a focused leaf under #10757 V2 (mutation-time gate). The latest friction chain is concrete:

• PR #13523 was closed unmerged after the operator challenged lifecycle skill bloat.
• PR #13529 was closed unmerged for the same accretion pattern.
• PR #13530 was closed unmerged after exact measurement showed another +38/-1 lines and +2,232 bytes across three already-hot skill workflow payloads while still using Resolves #10777.

The repeated failure mode is not that agents lack prose telling them Map vs World Atlas exists. ADR 0008, the skill-authoring guide, and lint-skill-manifest.mjs already encode the doctrine. The gap is mechanical: the current linter catches per-file caps and two named oversized workflow maps, but a PR can still add kilobytes to other hot skill Markdown files as long as each file stays under the cap.

Live latest-open sweep: checked latest 20 open issues on 2026-06-19; no equivalent focused net-positive skill Markdown growth guard was found. Closest parent is #10757. Exact/local sweep found existing oversizedWorkflowMaps / maxPositiveDeltaBytes guard only, not a net skill Markdown delta guard. A2A in-flight claim sweep checked the latest 30 messages; no competing claim on this scope was present.

The Problem

Skill bloat is recurring because the present mechanical gates are cliff-based:

• perFilePayloadBudget fails only when a single reference file exceeds the configured cap.
• oversizedWorkflowMaps + maxPositiveDeltaBytes fails only for explicitly listed historical monoliths.
• Files just below the cap, or smaller hot workflow payloads, can still accumulate positive deltas every PR.

That shape lets the swarm repeatedly pass CI while making Codex-class 258k-context workflows worse. The rule that matters now is net loaded-surface direction: skill Markdown PRs should reduce or replace loaded workflow text, not merely stay below a per-file ceiling.

The Architectural Reality

• .agents/skills/skills.manifest.json currently defines defaults.perFilePayloadBudget, defaults.oversizedWorkflowMaps, and defaults.maxPositiveDeltaBytes.
• ai/scripts/lint/lint-skill-manifest.mjs already computes changed files against --base, reads base file sizes via git cat-file, and enforces positive-delta limits for oversizedWorkflowMaps.
• test/playwright/unit/ai/scripts/lint/lintSkillManifest.spec.mjs already has focused tests for checkOversizedWorkflowMaps.
• ADR 0008 declares the recursive Map vs World Atlas discipline and names lint-skill-manifest.mjs as the mechanical enforcement layer.

The Fix

Add a base-mode linter guard that measures the net byte delta across changed .agents/skills/**/*.md files and fails when the net skill Markdown delta is greater than defaults.maxPositiveDeltaBytes.

Expected behavior:

• Positive additions are allowed only up to the existing pointer allowance.
• Larger additions must be offset by reductions elsewhere in .agents/skills/**/*.md.
• Pure reductions pass.
• Renames/deletes do not create false positives.
• The error message must point authors toward net reduction or replacement, not "move it to another book."

This is deliberately mechanical enforcement, not another skill prose rule.

Contract Ledger Matrix

Decision Record impact

Aligned with ADR 0008. This tightens the existing mechanical enforcement layer; it does not amend the ADR.

Acceptance Criteria

• lint-skill-manifest.mjs --base <ref> fails when changed .agents/skills/**/*.md files have net positive growth above defaults.maxPositiveDeltaBytes.
• The same lint passes when a larger addition is offset by equal or greater skill Markdown reduction elsewhere.
• The same lint passes for pure reductions.
• Non-skill Markdown changes do not count toward the skill Markdown net delta.
• Existing oversizedWorkflowMaps, per-file budget, section-trigger, and reference-integrity checks still run.
• Focused unit tests cover the new guard.
• PR body reports exact wc -c / byte-delta evidence and confirms no new skill prose payload was added.

Out of Scope

• Compressing individual bloated workflows in this leaf.
• Creating new skills, new rule books, or new Atlas pages.
• Blocking all future skill additions forever; legitimate additions must pay for themselves by reducing or replacing existing skill Markdown.
• Changing MCP tool description budgets.
• Closing #10757.

Avoided Traps

• Adding another prose rule: rejected. The team already forgets the prose; this ticket targets CI/lint.
• Only adding more files to oversizedWorkflowMaps: rejected. That would repeat the allowlist miss from #13530.
• Per-file cap tightening only: rejected. It catches cliffs, not accretion.
• New config surface by default: rejected. Reuse maxPositiveDeltaBytes unless implementation proves a separate knob is necessary.

Related

• Parent: #10757
• ADR authority: learn/agentos/decisions/0008-skill-anatomy-and-authoring-contract.md
• Recent calibration PRs: #13523, #13529, #13530
• Existing linter: ai/scripts/lint/lint-skill-manifest.mjs
• Existing tests: test/playwright/unit/ai/scripts/lint/lintSkillManifest.spec.mjs

Origin Session ID: 0a1dbe52-d3d0-43c4-8eb5-53a9e8499236

Retrieval Hint: skill bloat maxPositiveDeltaBytes net skill Markdown delta #13523 #13529 #13530 #10757