feat: validate records and update skills

.claude/skills/add-ave-record/SKILL.md

@@ -45,6 +45,69 @@ python scripts/validate_records.py
 pytest tests/ -x -q
 ```
 
+If validate_records.py fails on AIVSS arithmetic, fix the record's own
+aarf/cvss_base/thm/mitigation_factor values or the stated aivss_score,
+don't just adjust one to match the other without checking which one is
+actually wrong; a computed mismatch usually means the record was drafted
+against a different set of factors than what got written down.
+
+### 7. Publish
+A record passing validation is not yet a published one. Update:
+
+- **dist/ave-records-latest.json**: add or replace this record's entry,
+  keeping the array sorted by ave_id.
+- **CHANGELOG.md**: one line under Unreleased/Added: the ave_id, title,
+  severity, and aivss_score.
+- **README.md, three separate things, don't assume any of them share a
+  format**:
+
+  1. **Prose record count.** Find it first:
+     ```bash
+     grep -n "[0-9]\+ records\|[0-9]\+ behavioral class" README.md
+     ```
+     Update to the real count from `ls records/AVE-*.json | wc -l`, not by
+     incrementing the old number, more than one record can land in a
+     single batch.
+
+  2. **A record-count badge**, if one exists. Badges are usually
+     shields.io-style, with the count embedded as a URL path segment, not
+     free prose, so the prose grep above won't reliably catch it. Find it
+     separately:
+     ```bash
+     grep -n "shields.io\|badge.*record\|records.*badge" README.md
+     ```
+     If found, the count sits inside the badge URL itself (something like
+     `.../badge/records-59-blue`), update that specific segment to the
+     real count, don't touch the rest of the badge's color, label text, or
+     link target.
+
+  3. **A list or table enumerating individual records**, if one exists.
+     This is not a number to update, it needs a new row appended for
+     whatever record just landed, matching the exact column structure and
+     formatting of the existing rows exactly, so it doesn't stand out as
+     the one inconsistently-formatted entry. Find it first:
+     ```bash
+     grep -n "AVE-2026-" README.md
+     ```
+     If this is a comprehensive, actively-maintained list, append the new
+     record's row after whatever the file's own existing ordering
+     convention is (chronological, by ID, by severity, confirm which
+     before assuming). If it's a curated set of examples rather than a
+     complete enumeration (a handful of illustrative records, not all of
+     them), don't add to it automatically, that's an editorial decision
+     about which records are worth featuring, not a mechanical update; ask
+     before changing this one.
+
+  For all three: if the grep for any of them finds nothing, that specific
+  piece doesn't exist in README.md, skip it, don't invent one. If any grep
+  finds something whose format doesn't match what's described above, stop
+  and ask rather than force an edit that might not fit.
+
+Do not bump schema_version or create a new versioned dist snapshot
+(dist/ave-records-vX.Y.Z.json) as part of this step. That's a separate,
+deliberate decision tied to an actual schema change, not something that
+happens automatically because one record got added.
+
 ## Severity / AIVSS consistency
 
 CRITICAL → aivss_score >= 9.0
@@ -54,9 +117,30 @@ LOW      → < 4.0
 
 If severity and aivss_score disagree, the record fails validation.
 
+A mechanism that reads as severe in plain English can still land MEDIUM,
+correctly, if it's narrow and single-vector, AARF's ten factors reward
+breadth of amplification, not just raw impact. cvss_base alone carries
+the severity of the underlying impact. Don't inflate AARF factors to
+force a record into a more severe-sounding band; if the honestly computed
+score feels low relative to the mechanism's intuitive severity, say so in
+the record's own aivss.notes field rather than adjusting the inputs to
+hit a target. See references/aivss-scoring.md for the full formula and
+worked examples of this exact situation.
+
 ## confidence_baseline guide
 
 High-signal AVE (hardcoded AWS key, explicit external fetch): 0.85-0.95
 Medium-signal (suspicious instruction phrasing): 0.55-0.75
 Low-signal (vague, needs corroboration): 0.40-0.55
 The scanner adjusts from this baseline via the FP pipeline.
+
+## Reference files
+
+- references/aivss-scoring.md: the AARF formula, how aars is computed
+  from the ten factors, and worked examples spanning MEDIUM through HIGH,
+  including the specific trap of inflating factors to chase a severity
+  band.
+- references/schema-fields.md: the provenance_vector.entry_class enum
+  (confirmed live against the corpus) and escalation values, distinct
+  from grill-with-docs Q7's detection_layer, a coarser, separate field;
+  don't conflate the two when writing provenance_vector.

.claude/skills/grill-with-docs/SKILL.md

@@ -7,7 +7,14 @@ Grill before defining a vulnerability class. No record until complete.
 Q1: In one sentence, what does a vulnerable component DO?
     (This becomes behavioral_fingerprint — must be behavioral, not a string.)
 Q2: Is this a new attack_class or a variant of an existing one?
-    (Check records/ for similar attack_class values first.)
+    Don't check attack_class label similarity alone, that's not
+    reliable, a genuinely distinct mechanism can have a similar-sounding
+    name, and a genuine duplicate can have a completely different one.
+    Pull any plausible match's real provenance_vector fields
+    (entry_class, payload_surface, escalation) and the full description,
+    compare directly against this candidate's actual mechanism. Only
+    call it a variant if the entry_class and payload_surface genuinely
+    match, not if the label or general topic sounds similar.
 Q3: What is the worst realistic impact? (drives cvss_base and severity)
 Q4: How much does agent autonomy amplify it? (drives aars)
 Q5: Which engines can detect it? pattern/yara/semgrep/llm/sandbox/magika

ARCHITECTURE.md

@@ -26,6 +26,10 @@ crosswalks/            Mappings from other scanners and frameworks to AVE ids
 docs/                  ADRs, guides, research reports
 ```
 
+The alias/versioned-snapshot pattern shown above is described informally
+here; `docs/specs/scaling-and-governance.md` Section 2 is the canonical
+policy (bump rules, freeze guarantees) this file tree implements.
+
 There is no `rules/` directory in this repo. Detection rule implementations
 (pattern matching, YARA, semgrep, or anything else) are implementation
 artifacts, not standard artifacts, and live in whichever tool implements

CHANGELOG.md

@@ -6,6 +6,19 @@ Format: [Semantic Versioning](https://semver.org). Schema versions and record se
 
 ---
 
+## [Unreleased]
+
+### Added
+- `docs/specs/scaling-and-governance.md`: record-growth discipline
+  (citing MITRE CWE 4.19 as a documented cautionary precedent), schema
+  versioning policy (formalizing the existing alias/frozen-snapshot
+  pattern), and deprecation policy (modeled on CVE's rejected-but-permanent
+  approach). The deprecation policy's schema implementation
+  (`merged_into`, `rejection_reason` fields) is tracked separately for a
+  future version bump, not yet implemented.
+
+---
+
 ## [1.3.0] - 2026-07-17
 
 ### Summary

CLAUDE.md

@@ -157,6 +157,23 @@ python scripts/check_fixtures.py      # every record has +/- fixtures
 
 ---
 
+## Scaling and governance rules
+
+- Before proposing a new record, check `docs/specs/scaling-and-governance.md`
+  Section 1. A record needs a genuinely distinct behavioral mechanism, not
+  a category wrapper around existing coverage. If it looks like "framework
+  X's category, applied to agentic AI," it's not a record, flag this
+  rather than draft it.
+- Never delete or reuse a published `ave_id`, ever, no exceptions. If a
+  record turns out wrong or redundant, that's a `status` change
+  (`deprecated`/`merged`/`rejected`), not a deletion. See Section 3.
+- Frozen versioned schema and dist files
+  (`ave-record-X.Y.Z.schema.json`, `ave-records-vX.Y.Z.json`) are never
+  edited retroactively, including typo fixes. A correction ships in the
+  next version.
+
+---
+
 ## Agent skills
 
 | Skill | When |

CONTEXT.md

@@ -102,6 +102,8 @@ See CLAUDE.md for session rules and the current task queue.
 See ARCHITECTURE.md for the record/rule/fixture model.
 See CONTRIBUTING.md for the contributor-facing process.
 See GOVERNANCE.md for decision process and the record proposal workflow.
+See docs/specs/scaling-and-governance.md for record-growth discipline,
+schema versioning, and deprecation policy.
 
 **Roadmap, launch planning, adoption tactics, and anything with a marketing or
 fundraising deadline attached does not belong in this repo, including as an

CONTRIBUTING.md

@@ -44,6 +44,13 @@ contribution makes AI agents safer for everyone.
 
 ## Submitting a new AVE record
 
+Before opening a PR that adds a new record, read
+`docs/specs/scaling-and-governance.md` Section 1. A record needs a
+genuinely distinct behavioral mechanism; PRs that mirror another
+framework's category without describing a real, evidenced mechanism will
+be asked to either strengthen the evidence or fold into an existing
+record's `mutation_count` instead.
+
 ### Step 1 -- Open an issue
 
 Use the **New AVE Record** issue template. Include:

GOVERNANCE.md

@@ -22,6 +22,9 @@ Minor additions (new optional fields) are non-breaking and can ship in a patch r
 **Crosswalk updates:** maintainer or contributors may update crosswalk JSON files to
 add new tool mappings. No record changes required.
 
+Record-growth, schema-versioning, and deprecation policy specifically are
+covered in `docs/specs/scaling-and-governance.md`, not restated here.
+
 ---
 
 ## Contribution process

LANGUAGE.md

@@ -29,6 +29,13 @@ Authored once. Immutable ave_id. Lives in records/AVE-YYYY-NNNNN.json.
 **ave_id** — unique identifier. Format AVE-YYYY-NNNNN. Never renumbered.
 Immutable once published. Deprecated via status, never deleted.
 
+**status** — `active` is the default. The only valid non-`active` values
+are `deprecated`, `merged`, `rejected`, per
+`docs/specs/scaling-and-governance.md` Section 3. Don't use synonyms
+("retired," "duplicate," "invalid") in prose describing a record's
+status, even informally. These names mean something specific and
+consistent everywhere they appear.
+
 **attack_class** — the behavioral category. NOT "vulnerability type".
 Examples: external_instruction_fetch, tool_description_injection,
 rug_pull, cross_app_escalation. Use snake_case.

README.md

@@ -465,6 +465,9 @@ the mapping.
 See [GOVERNANCE.md](GOVERNANCE.md) for the decision-making process, how records
 are proposed and reviewed, and the path toward neutral governance.
 
+See [docs/specs/scaling-and-governance.md](docs/specs/scaling-and-governance.md)
+for record-growth discipline, schema versioning, and deprecation policy.
+
 See [CONTRIBUTING.md](CONTRIBUTING.md) for the contributor-facing process.
 
 See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community standards.