v0.4.0

Released: 2026-05-18

Canonical changelog: CHANGELOG.md

Highlights

• aoa-skills has moved from a flatter skill corpus into a routed skill system with explicit source topology, AGENTS guidance, mechanics lanes, generated companions, portable exports, and release verification surfaces.
• The canonical skill layer is now more self-contained: skills own executable workflow meaning, while technique links, evaluation evidence, project overlays, generated surfaces, and downstream installs remain adjacent, inspectable layers.
• Core engineering, session-growth, risk, and project-overlay skills were audited, broadened, tested, exported, and re-routed into the new topology.
• The release adds the first Skill Intelligence registry slice, stronger audit and promotion-pressure reporting, fuller portable export coverage, and release-facing packaging smoke over staged directory and ZIP handoff.

Release Scope

This release covers the full change range from v0.3.3 to v0.4.0:

• 29 landed commits / PRs, including #195 through #221.
• 1305 changed paths: 515 added, 329 modified, 147 deleted, and a large set of tracked renames/moves.
• Largest touched surfaces: skills/, mechanics/, .agents/, docs/, generated/, tests/, scripts/, config/, schemas/, quests/, templates/, and .github/.

Added

• Root system-design surfaces:
  • DESIGN.md for the skill-layer system form.
  • DESIGN.AGENTS.md for the agent-facing guidance mesh.
  • docs/AGENTS_ROOT_REFERENCE.md as the preserved depth layer behind the slim root route card.
• A repo-wide AGENTS mesh across source, docs, mechanics, generated/export, scripts, tests, templates, config, legacy, decisions, reviews, examples, and portable pack districts.
• scripts/validate_agents_design.py plus tests for required AGENTS card placement, heading order, and canonical section shape.
• Mechanics topology and package surfaces for audit, boundary-bridge, release-support, experience, growth-cycle, method-growth, recurrence, checkpoint, questbook, antifragility, RPG reader surfaces, and Agon candidate routes.
• mechanics/OWNER_REQUEST_RECEIPTS.md for owner-local AoA request receipts and future package pressure.
• A source-derived Skill Intelligence foundation:
  • scripts/skill_intelligence.py
  • scripts/skill_intelligence_surface.py
  • generated/skill_intelligence_registry.json
  • generated/skill_intelligence_registry.min.json
  • tests for the registry surface.
• Expanded skill support artifacts across canonical bundles and portable exports, including checks/, examples/, references/, templates, runtime cards, and review surfaces.
• New and expanded decision records for mechanics reformation, source topology, self-sufficient skill boundaries, root design surfaces, skill intelligence, and related owner-route choices.
• GitHub-native support surfaces: .github/AGENTS.md, updated CODEOWNERS/workflow posture, and release/validation alignment.

Changed

• Root entry surfaces were slimmed and re-routed:
  • README.md is now a public front door, not a package atlas.
  • AGENTS.md now owns agent route law, route modes, hard boundaries, post-change review, and GitHub landing workflow.
  • docs/README.md, docs/ARCHITECTURE.md, SKILL_INDEX.md, and mechanics docs now point to owner-local surfaces instead of duplicating broad doctrine.
• The old flat skill layout was reshaped into durable topology:
  • skills/core/engineering/
  • skills/core/session-growth/
  • skills/risk/
  • skills/project/abyss/
  • skills/project/atm10/
  • skills/project/titan/
• Canonical bundles and exported .agents/skills/* were refreshed together so portable installs carry the same reviewed skill meaning and support artifacts.
• Core engineering skills were broadened and hardened for AoA-wide use without becoming narrow repo-only recipes:
  • ADR writing
  • source-of-truth checks
  • bounded context maps
  • change protocol
  • TDD slices
  • contract tests
  • property invariants
  • invariant coverage audit
  • core-logic boundaries
  • port/adapter refactors
• Session-growth skills were audited and tightened around reviewed artifacts, explicit evidence, route forks, self-diagnosis, self-repair, progression lift, quest harvest, closeout bridge, automation opportunity scan, commit-growth seam, and aoa-summon.
• Risk skills and activation policy were separated more clearly:
  • implicit activation now comes from explicit policy, not from broad invocation-mode inference.
  • approval, dry-run, sanitized-share, safe-infra-change, and local-stack bring-up surfaces gained clearer gates and runtime posture.
• Project overlays were reorganized and tightened as thin overlays rather than downstream truth mirrors:
  • Abyss overlays
  • ATM10 overlays
  • Titan service-cohort overlays and runtime/replay/approval/memory gates
• aoa-summon was reworked around neutral local-agent wording, explicit handoff contracts, runtime examples, result schema, and route-fork boundaries.
• Technique bridge wording was rebalanced: skills and techniques remain directly related, but skills do not depend on technique links as universal validity or runtime blockers.
• Release-support now carries a stronger portable handoff route:
  • install profiles
  • staged bundles
  • ZIP handoff
  • bundle inspection
  • import/verify flows
  • generated release manifest identity
  • packaging smoke in scripts/release_check.py --include-packaging-smoke.
• Generated surfaces were refreshed and expanded across catalogs, capsules, public surfaces, evaluation matrices, lineage/boundary matrices, governance backlog, composition audit, overlay readiness, bundle index, graph, runtime seam, guardrails, support resources, description triggers, tiny-router inputs, and release manifest.
• Audit/evaluation/promotion reporting was tightened:
  • skill quality audit blockers
  • promotion pressure reporting
  • evaluated/canonical status checks
  • review truth-sync gate
  • workspace adoption audit
  • runtime and support-resource validation
• GitHub topics were refreshed for discoverability around AoA, agent skills, portable skills, coding agents, local agents, validation, governance, and workflow automation.

Removed / Rehomed

• Flat mechanics surfaces were moved under owner-local mechanics packages.
• Root-level or docs-level package atlases, wave-era noise, and misplaced operational law were removed or rehomed to the nearest owning surface.
• Legacy or compatibility paths were either retired, moved under legacy/, or kept only where they still serve adapter/export compatibility.
• Former top-level skill surfaces were replaced by canonical lane placement under skills/core, skills/risk, and skills/project while preserving exported portable forms under .agents/skills.

Included PRs / Commits

• #195 Slim root AGENTS route card
• #196 Retarget skill install paths to AbyssOS
• #197 Land AoA v0.4.0 skill closeout follow-through
• #198 Refresh core skill route posture
• #199 Reform aoa-skills mechanics topology
• #200 Add AoA owner request receipts
• #201 Rehome mechanics surfaces
• #202 Route mechanics companion surfaces
• #203 Distribute mechanics roadmaps and root questbook
• #204 Reform skills source topology
• #205 Rehome mechanic artifact topology
• #206 Separate skill maturity from technique bridge
• #207 Evaluate session growth skills
• #208 Broaden engineering skills and rollout foundation
• #209 Refresh session-growth skills and landing surfaces
• #210 Close core skill audit policy gates
• #211 Refine project overlay skill topology
• #212 Tighten Titan skill owner boundaries
• #213 Align agent guidance mesh
• #214 Preserve hold state in infra contract
• #215 Add skill intelligence registry foundation
• #216 Refine root skill route and lineage surfaces
• #217 Tighten session growth skill handoff contracts
• #218 Align aoa-summon contract tokens
• #219 Trim aoa-skills document route noise
• #220 Quote diagnosis receipt YAML rule
• #221 Prepare aoa-skills v0.4.0 release

Validation

Local release validation before merge:

• /srv/AbyssOS/.codex/bin/aoa-codex-doctor --workspace-root /srv/AbyssOS --format json
• aoa skills enter /srv/AbyssOS/aoa-skills --root /srv/AbyssOS --intent-text "release aoa-skills v0.4.0" --json
• aoa skills guard /srv/AbyssOS/aoa-skills --root /srv/AbyssOS --intent-text "release aoa-skills v0.4.0" --mutation-surface public-share --json
• python -m pytest -q tests/test_release_docs.py tests/test_release_manifest_contract.py tests/test_codex_portable_contract.py tests/test_install_profiles.py tests/test_stage_skill_pack.py tests/test_verify_skill_pack.py tests/test_roadmap_parity.py
• python scripts/release_check.py --include-packaging-smoke
• aoa checkpoint review-note ... --commit-ref fa54e4756d1f49d1d1a27cdbbc582c45ce687098 --auto --root /srv/AbyssOS

GitHub validation before merge:

• PR #221 build-validate: pass
• PR #221 Repo Validation: pass

Post-merge validation on main:

• codex-portable-export: pass
• Repo Validation: pass

Notes

• This release keeps aoa-skills as the bounded execution canon. It does not make this repository the technique owner, proof owner, route owner, memory owner, runtime owner, playbook owner, or downstream adoption authority.
• generated/release_manifest.json reports latest_tagged_version: 0.4.0, latest_tagged_date: 2026-05-18, and has_unreleased_changes: false for this cut.
• The public GitHub release body is intentionally more complete than the terse changelog entry because this release spans the full reformation from v0.3.3 to v0.4.0.