# Release Notes: v3.11.0

**Release Date**: 2026-03-28
**Type**: Minor
**Theme**: Skill Conformance, Configuration & Requirements Formalization

---

## Executive Summary

v3.11.0 introduces the human-level requirements layer (L742 two-level model), scaffolds hook infrastructure across all templates for ADR-008 Generator level, and remediates skill instruction conformance. Where v3.10.0 made governance *structurally unavoidable*, v3.11.0 makes it *requirements-driven* — grounding specifications in explicit principal intent.

This is the second multi-plan coordinated release, integrating 5 completed component PROJECT_PLANs (SICR, RQI, TAGR, #725, #505). It is the first release with all P1 items pre-resolved before the release plan was created.

---

## Highlights

### Requirements Formalization (#725, L742, L748)

The most architecturally significant change: AGET now has a formal requirements layer.

**Two-level model** (L742): Requirements define principal intent (human level); specifications define testable contracts (contract level). The Specification-Fault Principle: when behavior diverges from spec, the spec is at fault — not the code.

**New artifacts**:
- `aget/requirements/` directory with REQUIREMENTS_FORMAT.md v1.0
- REQ-REL v1.1.0: First exemplar — 6 functional + 3 quality requirements for release quality, grounded in evidence from 8 releases (v3.3-v3.10)
- AGET_RELEASE_SPEC v1.11.0: First spec with bidirectional Requirements Grounding section, mapping 9 REQ-REL requirements to 27 CAP-REL capabilities

**Impact**: Every specification can now trace to human-level requirements. Debugging direction: check the requirement first, then the spec, then the implementation.

### Hook Adoption Pilot (#505, ADR-008)

Infrastructure for ADR-008 Generator level — the progression beyond Strict enforcement.

**Deployed**:
- `.claude/hooks/` directory scaffolded in all 12 templates with README
- `HOOK_ADOPTION_GUIDE.md` published in aget/ core
- 2 hooks operational in managing agent: `SessionEnd` (wind_down.py auto-trigger) and `PreToolUse` (push_window_guard.sh)

**Impact**: Templates now have the structural foundation for hook-based governance. Fleet-wide adoption is supervisor-owned; this release provides the scaffold.

### Skill Instruction Conformance (SICR, #678, L736)

17 skill instructions remediated for L736 conformance.

**Root cause** (L736): Skill instructions that assert state before verifying it. Example: a SKILL.md hardcoding an ID format without citing the governing spec, causing format contamination at scale (44 wrong IDs from one skill).

**Remediation**: All 17 SKILL.md files across 13 repos verified against governing specs. Assert-before-verify anti-pattern eliminated.

### Template Archetype Governance (TAGR, #732)

All 12 templates now declare their governance intensity classification.

**New field**: `governance_intensity` in AGENTS.md Governance Capabilities section — values: Rigorous, Standard, or Lightweight (per L341).

**Contract tests**: 6/12 templates have archetype-specific contract tests. Remaining 6 require archetype test classes (#276).

### Release Quality Improvements (RQI)

5 targeted improvements driven by rubric analysis:

- **Pre-push hook** (#672): `push_window_guard.sh` blocks non-Saturday pushes to aget-framework repos. ADR-008 Generator level enforcement.
- **study_up.py bug fix** (#731): Punctuation token filter + 2-keyword threshold lowered. Cross-cutting topics now return 187 artifacts vs 0.
- **"sanity check" → "health check"** (#658): 72 references updated across 12 files. Inclusive terminology.
- **Homepage roadmap** (#637): "What's Next" section added to README.md.
- **Phantom traceability** (#552): 2 phantom CAP references cleaned.

---

## What's New

### Added

- `aget/requirements/` directory with REQUIREMENTS_FORMAT.md, REQ-REL, INDEX.md
- `.claude/hooks/` scaffold in 12/12 templates
- `HOOK_ADOPTION_GUIDE.md` in aget/ core
- `governance_intensity` field in 12/12 template AGENTS.md
- Pre-push hook (`push_window_guard.sh`)
- Homepage roadmap section
- DEPLOYMENT_SPEC_v3.11.0.yaml
- Requirements Grounding section in AGET_RELEASE_SPEC v1.11.0

### Changed

- AGET_RELEASE_SPEC v1.10.0 → v1.11.0 (Requirements Grounding)
- REQ-REL v1.0.0 → v1.1.0 (CAP-REL traceability, status proposed)
- 17 skill SKILL.md files updated for L736 conformance
- "sanity check" → "health check" (72 refs, 12 files)
- study_up.py keyword matching improved
- RUBRIC.template.md v2.0 deployed to 12/12 templates

### Fixed

- 2 phantom traceability references cleaned
- wind_down.py content sync (sanity → health alignment)
- study_up.py: 0 results for cross-cutting topics

---

## Migration Guide

### For Fleet Agents (upgrading from v3.10.0)

1. **Version bump**: Update version.json, AGENTS.md, manifest.yaml to 3.11.0
2. **New directories**: Create `requirements/` and `.claude/hooks/` (with README.md)
3. **AGENTS.md**: Add `governance_intensity` field to Governance Capabilities section
4. **Terminology**: Replace "sanity check" with "health check" in AGENTS.md and scripts
5. **Skill sync**: Update all 16 universal skill SKILL.md files from template source
6. **Verify**: Run health check (`python3 scripts/health_check.py`)

### Breaking Changes

None. v3.11.0 is fully backward-compatible with v3.10.0.

### Deprecation Status

Active deprecations (from v3.10.0, removal earliest v3.12.0):
- `capture` verb → `record`
- `aget-study-up` → `aget-study-topic`
- `/aget-record-nugget` → `/aget-record-observation` Mode 4 (Quick)

No new deprecations in v3.11.0.

---

## Metrics

| Metric | v3.10.0 | v3.11.0 |
|--------|---------|---------|
| Component plans | 3 | 5 |
| Pre-resolved P1 items | 40% | 100% |
| Release-specific velocity | 0.13x | TBD |
| Contract tests | 139+1 skip | 140 |
| Hotfix cycles | 2 | TBD |
| Templates with governance_intensity | 0/12 | 12/12 |
| Requirements documents | 0 | 1 (REQ-REL) |
| Hooks infrastructure | 0/12 templates | 12/12 templates |

---

## References

### Component Plans (all COMPLETE)

- SICR (#678): Skill instruction conformance — 4 gates, 0.51x velocity
- RQI: Release quality improvements — 6 gates, 0.35x velocity
- TAGR (#732): Template archetype governance — 4 gates, 0.48x velocity
- #725: Requirements formalization — 5 gates
- #505: Hook adoption pilot — 4 gates

### Key L-docs

- L736: Skill-Instruction Assert-Before-Verify
- L742: Two-Level Model (Requirements/Specifications)
- L748: Requirements Artifact Storage Gap
- L735: Push Window Discipline Gap
- L751: Prospective Test / Retrospective Artifact

### Tracking

- VERSION_SCOPE_v3.11.0.md v1.8.0 (SCOPE LOCKED)
- PROJECT_PLAN_v3.11.0_release_v1.0.md (REL-041)

---

*v3.11.0: "Skill Conformance, Configuration & Requirements Formalization"*
*Second multi-plan coordinated release. First with all P1 pre-resolved. First with bidirectional requirements-spec traceability.*
