Block skill-lint growth into oversized workflow maps

Context

PR #11434 exposed a concrete failure in the current Skill Manifest Lint enforcement. The PR adds substantive FAIR-band rule body into the two largest workflow-map files:

• .agents/skills/pr-review/references/pr-review-guide.md — currently 58,793 bytes
• .agents/skills/pull-request/references/pull-request-workflow.md — currently 37,414 bytes

node ai/scripts/lint-skill-manifest.mjs --base origin/dev still reports [lint-skill-manifest] OK.

This is exactly the risk Epic #11319 was created to address: recursive Map vs World Atlas enforcement for workflow files. The current implementation catches some file-size and trigger-comment cases, but it misses high-risk incremental growth into the known oversized workflow maps.

The Problem

The current linter is too permissive for the highest-risk skill payloads:

1. pr-review and pull-request carry temporary perFilePayloadBudget overrides (66000 and 38000) above the default 25KB ceiling.
2. Those overrides allow the already-bloated workflow maps to grow further while CI stays green.
3. checkSectionTriggers() only flags large sections that already declare trigger comments with rare-pattern text. It does not catch new substantive sections/rows added directly into bloated workflow maps without a trigger pointer.
4. The linter therefore validates syntax and existing budget overrides, but not the actual Map-vs-World-Atlas intent.

Operator framing from PR #11434 review cycle: "pr review and pull request are the biggest and heavily most bloated skill workflows we have. adding substantially more in there. FRICTION -> why do we have a skill linter CI if it lets that one pass as green. completely useless. needs work."

The Architectural Reality

Related substrate:

• Epic #11319 — Trigger-Aware Workflows: recursive Map vs World Atlas
• #11320 / #11399 — shipped section-trigger heuristic
• .agents/skills/create-skill/references/skill-authoring-guide.md — workflow files recursively become Maps for sub-rules
• ADR 0007 — Compaction Taxonomy, compress-to-trigger default for detailed memory-substrate rules
• #11427 / ADR 0008 lane — skill anatomy and authoring contract
• PR #11434 — empirical bypass: green Skill Manifest Lint while adding new rule body into bloated maps

The linter needs a delta-aware guard for known oversized workflow-map files, not only absolute per-file ceilings and declared rare-trigger sections.

The Fix

Extend ai/scripts/lint-skill-manifest.mjs and .agents/skills/skills.manifest.json so CI can block net-new substantive growth into oversized workflow maps unless the PR explicitly extracts or points to a granular Atlas payload.

Candidate shape:

1. Add manifest metadata for workflow-map files that are in migration mode, for example:
   • workflowMapBudget
   • maxPositiveDeltaBytes
   • requiresTriggerPointerForPositiveDelta
   • or a dedicated oversizedWorkflowMaps list per skill
2. When --base is provided, compute per-file byte/line delta for changed workflow-map files.
3. If a file is above the default per-file budget and the PR adds net-positive substantive content, fail unless the delta is a recognized one-line trigger pointer or accompanies extraction to a sibling payload.
4. Add focused unit coverage for the PR #11434 shape: adding a multi-line section to pull-request-workflow.md or a long anti-pattern row to pr-review-guide.md must fail lint while an extraction + pointer shape passes.
5. Keep the existing per-file and section-trigger checks; this is an additional delta guard, not a replacement.

Contract Ledger Matrix

Acceptance Criteria

• Linter detects net-positive substantive additions to known oversized workflow-map files when --base is provided.
• pr-review-guide.md and pull-request-workflow.md are covered as initial high-risk workflow maps.
• A one-line trigger pointer plus sibling Atlas extraction passes.
• A PR #11434-style inline addition to pull-request-workflow.md fails in a focused regression test.
• A PR #11434-style long anti-pattern row addition to pr-review-guide.md fails in a focused regression test.
• Existing absolute payloadBudget / perFilePayloadBudget checks continue to run.
• Error messages explain the remediation: extract detailed rule body to references/<sub-rule>.md or references/audits/<sub-rule>.md and leave only a trigger pointer in the workflow map.
• PR body cites PR #11434 as the empirical friction anchor.

Out of Scope

• Migrating pr-review-guide.md or pull-request-workflow.md themselves; those are separate migration PRs under #11319.
• Removing all temporary per-file overrides immediately.
• Semantic LLM scoring of prose quality.
• Enforcing AGENTS.md byte budget; that belongs to the substrate-size guard lineage.

Avoided Traps / Gold Standards Rejected

• Absolute cap only: rejected because temporary overrides are necessary during migration, but they must not permit further growth.
• Reviewer-only enforcement: rejected because PR #11434 proves review discipline can miss the placement defect.
• Trigger-comment-only heuristic: rejected because it only catches sections that already opted into the trigger syntax; wrong-shape additions usually omit the trigger pointer entirely.
• Bundling migration with guard: rejected per #11319’s one-skill-per-PR migration discipline; this ticket is the guardrail fix.

Related

• Parent Epic: #11319
• Shipped lint primitive: #11320 / #11399
• SkillSource follow-up: #11334
• Skill anatomy ADR lane: #11427
• Empirical anchor: PR #11434 Cycle 3 review correction

Origin Session ID: e03c75a3-6468-4e23-bd05-b1ce8a4a563e

Handoff Retrieval Hint: PR #11434 green skill-manifest lint oversized workflow maps perFilePayloadBudget override Map vs World Atlas