---
id: 11437
title: Block skill-lint growth into oversized workflow maps
state: CLOSED
labels:
  - bug
  - ai
  - architecture
  - build
  - model-experience
assignees:
  - neo-gemini-pro
createdAt: '2026-05-15T19:09:57Z'
updatedAt: '2026-05-16T10:08:31Z'
githubUrl: 'https://github.com/neomjs/neo/issues/11437'
author: neo-gpt
commentsCount: 0
parentIssue: 11319
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-05-16T10:08:31Z'
---
# 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

| Target Surface | Source of Authority | Proposed Behavior | Fallback | Docs | Evidence |
|---|---|---|---|---|---|
| `lint-skill-manifest.mjs --base` | Epic #11319 + PR #11434 operator challenge | Detect positive growth into oversized workflow maps and require pointer/extraction shape | Existing absolute budgets remain outer ceiling | Script JSDoc + manifest schema docs | PR #11434 green lint despite wrong placement |
| `.agents/skills/skills.manifest.json` / schema | #11319 / #11320 lint substrate | Declare migration-mode workflow-map guard metadata | Hardcoded guard in script only if manifest shape proves too heavy | Schema field descriptions | `pr-review` and `pull-request` overrides currently hide growth |
| Skill Manifest Lint CI | Existing workflow | Fail PRs that grow bloated maps without Atlas extraction | Reviewer-only enforcement | CI output explains remediation | Prevents repeat of PR #11434 review miss |

## 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`

## Timeline

- 2026-05-15T19:09:59Z @neo-gpt added the `bug` label
- 2026-05-15T19:09:59Z @neo-gpt added the `ai` label
- 2026-05-15T19:09:59Z @neo-gpt added the `architecture` label
- 2026-05-15T19:10:00Z @neo-gpt added the `build` label
- 2026-05-15T19:10:00Z @neo-gpt added the `model-experience` label
- 2026-05-15T19:10:12Z @neo-gpt added parent issue #11319
- 2026-05-15T19:11:39Z @neo-gemini-pro assigned to @neo-gemini-pro
- 2026-05-15T19:15:04Z @neo-gemini-pro cross-referenced by PR #11438
- 2026-05-15T19:17:16Z @neo-gpt cross-referenced by PR #11434
- 2026-05-15T19:25:24Z @neo-gemini-pro referenced in commit `398ab07` - "test(ai): implement regression coverage for oversized workflow map linting (#11437)"
- 2026-05-15T19:43:30Z @neo-gpt cross-referenced by PR #11439
- 2026-05-16T02:31:22Z @neo-gpt cross-referenced by PR #11443
- 2026-05-16T10:08:32Z @tobiu closed this issue

