Summary
Formalizes three related policies as docs/specs/scaling-and-governance.md: record-growth discipline, schema versioning, and deprecation. Written at 59 records, deliberately, not after scale made any of this urgent.
1. Record-growth discipline
A new AVE record requires a genuinely distinct behavioral mechanism, not an organizational wrapper around coverage that already exists.
The precedent this guards against. MITRE's CWE version 4.19 added twelve new entries. Per independent analysis, zero described actual weaknesses; all twelve were organizational containers mirroring OWASP's Top Ten 2025 categories. The same release had 903 entries with "major changes," overwhelmingly metadata cleanup rather than substantive
content. Documented behavior in the taxonomy AVE is closest in kind to, not a hypothetical risk.
The mechanical test for "distinct enough to warrant a new ID" is owned by a separate, dedicated policy issue (credit: endor_sarah), not restated here. This covers the higher-level principle that test serves.
Named anti-pattern: a record whose entire content is "this other framework's category, applied to agentic AI" is not a record. Real evidence required, same bar as every existing record.
Review authority: currently one maintainer, matching CWE's own actual practice (MITRE's team, not the community, moves submissions through review). Stated honestly as current state, not permanent; a second maintainer with real review authority remains a tracked goal.
2. Schema versioning policy
Formalizes the pattern already in practice. Alias files (ave-record.schema.json, ave-records-latest.json) always point to current. Versioned snapshots (ave-record-1.1.0.schema.json, ave-records-v1.1.0.json) are frozen permanently once published, never edited retroactively, including typo fixes, a correction ships in the next version instead.
Bump rules: additive optional field, minor version. Removing or renaming a required field, or changing an existing field's meaning, major version. Every record validates against the schema version it declares, enforced in CI.
3. Deprecation policy
Modeled on CVE's rejected-but-permanent approach: no published ave_id is ever deleted or reused. status gains values beyond active: deprecated (superseded, content stays with a note), merged (genuine duplicate, adds merged_into pointing at the surviving ID, both remain resolvable), rejected (invalid, adds rejection_reason, stays resolvable, matching CVE's REJECT state).
Explicitly out of scope for this issue: the actual schema change (new status values, merged_into, rejection_reason fields). That's a real, separate schema change, tracked for a future version bump alongside owasp_ast (v1.2.0). This issue is policy only; the schema change is not implied to already work.
Summary
Formalizes three related policies as
docs/specs/scaling-and-governance.md: record-growth discipline, schema versioning, and deprecation. Written at 59 records, deliberately, not after scale made any of this urgent.1. Record-growth discipline
A new AVE record requires a genuinely distinct behavioral mechanism, not an organizational wrapper around coverage that already exists.
The precedent this guards against. MITRE's CWE version 4.19 added twelve new entries. Per independent analysis, zero described actual weaknesses; all twelve were organizational containers mirroring OWASP's Top Ten 2025 categories. The same release had 903 entries with "major changes," overwhelmingly metadata cleanup rather than substantive
content. Documented behavior in the taxonomy AVE is closest in kind to, not a hypothetical risk.
The mechanical test for "distinct enough to warrant a new ID" is owned by a separate, dedicated policy issue (credit: endor_sarah), not restated here. This covers the higher-level principle that test serves.
Named anti-pattern: a record whose entire content is "this other framework's category, applied to agentic AI" is not a record. Real evidence required, same bar as every existing record.
Review authority: currently one maintainer, matching CWE's own actual practice (MITRE's team, not the community, moves submissions through review). Stated honestly as current state, not permanent; a second maintainer with real review authority remains a tracked goal.
2. Schema versioning policy
Formalizes the pattern already in practice. Alias files (
ave-record.schema.json,ave-records-latest.json) always point to current. Versioned snapshots (ave-record-1.1.0.schema.json,ave-records-v1.1.0.json) are frozen permanently once published, never edited retroactively, including typo fixes, a correction ships in the next version instead.Bump rules: additive optional field, minor version. Removing or renaming a required field, or changing an existing field's meaning, major version. Every record validates against the schema version it declares, enforced in CI.
3. Deprecation policy
Modeled on CVE's rejected-but-permanent approach: no published
ave_idis ever deleted or reused.statusgains values beyondactive:deprecated(superseded, content stays with a note),merged(genuine duplicate, addsmerged_intopointing at the surviving ID, both remain resolvable),rejected(invalid, addsrejection_reason, stays resolvable, matching CVE's REJECT state).Explicitly out of scope for this issue: the actual schema change (new
statusvalues,merged_into,rejection_reasonfields). That's a real, separate schema change, tracked for a future version bump alongsideowasp_ast(v1.2.0). This issue is policy only; the schema change is not implied to already work.