# anti-entropy-governance

Adopt this skill: https://proskills.md/skills/other/ganyuanran-aegis-skills-anti-entropy-governance

Page: https://proskills.md/skills/other/ganyuanran-aegis-skills-anti-entropy-governance
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/anti-entropy-governance/SKILL.md
size: 8000
upstream: https://github.com/ganyuanran/aegis/blob/main/skills/anti-entropy-governance/SKILL.md

````text
---
name: anti-entropy-governance
description: "Use when touching retiring old logic, collapsing duplicate owners, removing fallbacks, or schema/persistence/source-of-truth boundaries; identify opportunities automatically; destructive execution requires explicit confirmation."
---

# Anti-Entropy

## Overview

Use this skill when the task is not merely "change code" but "remove old paths
safely without growing entropy".

This skill chooses between:

- `delete-first` for internal code retirement
- `compat-exception` for proven external dependency boundaries
- `confirmation-first` for irreversible state or an external contract whose
  distributed consumers cannot be observed

It does not replace `brainstorming`, `writing-plans`,
`systematic-debugging`, or `verification-before-completion`. It is a narrow
governance owner for retirement, fallback collapse, duplicate-owner cleanup,
and deletion safety.

## When to Use

Use when any of these are true:

- old logic, duplicate owners, or stale fallbacks should be retired
- a candidate fix is "delete old path" vs "add another fallback"
- internal keyword / phrase / trigger logic is being replaced by structured logic
- a new canonical owner exists and the old owner may still carry real behavior
- a cleanup, migration, or deprecation task touches schema, persistence,
  source-of-truth, or external compatibility boundaries
- the task risks confusing code retirement with live data deletion

Do not use for:

- pure additive feature work with no retirement decision
- tiny wording edits
- simple status or read-only Q&A
- normal bug fixes that do not involve owner collapse, fallback cleanup, or
  deletion choice

## Auto-Compose Boundary

This skill should be composed by other owners. It should not become a new
global hot-path entry.

Prefer composition from:

- `brainstorming` for approach selection involving retirement or persistence risk
- `writing-plans` for plans that delete old paths or touch schema / migration /
  persistence
- `systematic-debugging` when the tempting fix is fallback growth or
  delete-vs-retain
- `verification-before-completion` for cleanup / retirement / compatibility /
  migration closeout

Load automatically when the task touches owner collapse, fallback removal, or schema/persistence/source-of-truth boundaries. Automatic loading identifies and advises only; destructive execution still requires explicit scoped user confirmation.

## Core Principle

Default to reducing internal entropy, not preserving internal history.

Retirement is responsibility-scoped before it is carrier-scoped. Name the
obsolete or duplicated authority first. If the same carrier has a separately
evidenced legitimate role, remove the invalid responsibility and keep only
that role-scoped capability; this is not a compatibility exception. Apply
`delete-first` to the carrier once no legitimate responsibility remains.
Unknown consumers alone still do not justify retaining an internal carrier.

Use this rule:

- internal code retirement -> `delete-first`
- external compatibility boundary -> `compat-exception` with active dependency
  evidence; `confirmation-first` when distribution is proven but consumers
  cannot be observed
- persistent-state or irreversible source-of-truth object ->
  `confirmation-first`

Unknown alone neither proves an external dependency nor blocks internal
`delete-first`. Once distribution is proven, unobservable consumers also do not
prove deletion safe: inspect read-only. Before editing, require user-authored,
scoped authorization that explicitly accepts the concrete external risk.
An informed instruction may already supply it; otherwise disclose the risk
and request scoped confirmation.

Mentioning, loading, or discussing destructive-action rules never authorizes
destructive execution. Without explicit scoped user confirmation:

- no irreversible deletion is executed
- no destructive tool call is made
- no runnable destructive command is emitted as the next action
- no broad assent is reinterpreted as deletion approval

## Deletion Classes

Classify the deletion target first:

- `code-retirement`
  - source code
  - internal triggers
  - duplicate owners
  - stale fallback branches
  - compat-only carriers
  - dead tests/config tied to removed internal behavior

- `contract-carrying code`
  - schema definition files
  - migration files
  - public API contract code
  - host install/discovery code
  - persistence read/write logic

- `live-state mutation surface`
  - code or commands that would mutate live databases, object stores, queues,
    or other persistent state

- `derived-state`
  - rebuildable caches
  - generated indexes
  - temporary exports
  - recomputable artifacts

- `persistent-state`
  - live database tables / columns / rows
  - source-of-truth object storage files
  - user records
  - permission / identity / membership records
  - audit / billing / irreversible business records
  - non-rebuildable queue or event contents

## Default Path By Class

- `code-retirement` -> `delete-first`
- `contract-carrying code` -> classify by the Core Principle; internal-only
  retirement uses `delete-first` with high-risk verification
- `live-state mutation surface` -> inspect and classify; destructive execution
  still requires confirmation when it reaches persistent-state
- `derived-state` -> verify rebuildability first, then decide
- `persistent-state` -> `confirmation-first`

## Hard Stops

If the target is `persistent-state` or another irreversible source-of-truth
object:

- do not execute deletion automatically
- do not emit a runnable destructive command as the next action
- do not call a destructive tool
- do not interpret generic agreement as confirmation
- ask for explicit scoped user confirmation
- request backup / rollback / migration note when relevant

Examples that require confirmation:

- `DROP TABLE`
- `DROP COLUMN`
- `TRUNCATE`
- bulk delete of real business data
- deleting source-of-truth uploaded files
- deleting permission, identity, audit, billing, or membership records
- purging non-rebuildable queues or event streams

## Data Destruction Guard

When `confirmation-first` protects persistent-state or an irreversible
source-of-truth object, stop normal retirement flow and emit:

```text
Data Destruction Guard:
- Target Class:
- Exact Target(s):
- Environment:
- Why Irreversible:
- Backup / Rollback Note:
- Allowed Read-Only Next Steps:
- Blocked Destructive Steps:
- Confirmation Required: yes
- Status: awaiting scoped confirmation
```

Only explicit scoped confirmation can continue. Broad assent such as "OK",
"continue", or "sounds good" is insufficient. If scope changes at all, previous
confirmation is invalid and fresh confirmation is required.

## Anti-Entropy Declaration

Before deletion, state:

```text
Anti-Entropy Declaration:
- Deletion Class:
- Old Path/Object:
- Invalid Responsibility / Authority:
- Legitimate Capability Remaining on Carrier:
- New Canonical Owner:
- Expected Preserved Behavior:
- Expected Retired Behavior:
- External Boundary Touched: no | yes
- Source-of-Truth Data Risk: none | possible | confirmed
- User Confirmation Required: no | yes
```

For external-unknown code, fill `User Confirmation Required` with `yes` unless
the user's own instruction already names the concrete external risk, accepts
its possible breakage, and authorizes the exact retirement scope, or the user
later gives scoped confirmation after your disclosure. A generic original
deletion request does not satisfy this slot. Do not infer acceptance from mere
awareness of external use or from your own risk summary.

If `User Confirmation Required: yes`, stop normal delete-first flow.
Persistent-state or irreversible targets enter `Data Destruction Guard`;
external-unknown code stays in the `Retirement Decision` hold below.

## Retirement Decision

Choose one path only:

```text
Retirement Decision:
- Path: delete-first | compat-exception | confirmation-first
- Why:
- Non-edits:
```

R
````

## File: README.md
upstream: https://github.com/ganyuanran/aegis/blob/main/README.md

````text
<p align="center">
    <a href="https://linux.do/t/topic/2108966/20" alt="LINUX DO">
        <img
            src="https://img.shields.io/badge/LINUX-DO-FFB003.svg?logo=data:image/svg%2bxml;base64,DQo8c3ZnIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAiIHdpZHRoPSIxMDAiIGhlaWdodD0iMTAwIj48cGF0aCBkPSJNNjguMi0uMDU1aDYuMjVxMjMuOTY5IDIuMDYyIDM4IDIxLjQyNmM1LjI1OCA3LjY3NiA4LjIxNSAxNi4xNTYgOC44NzUgMjUuNDV2Ni4yNXEtMi4wNjQtMjMuOTY4LTIxLjQzIDM4LTExLjUxMiA3Ljg4NS0yNS40NDUgOC44NzRoLTYuMjVxLTIzLjk3LTIuMDY0LTM4LjAwNC0yMS40M1EuOTcxIDY3LjA1Ni0uMDU0IDUzLjE4di02LjQ3M0MxLjM2MiAzMC43ODEgOC41MDMgMTguMTQ4IDIxLjM3IDguODE3IDI5LjA0NyAzLjU2MiAzNy41MjcuNjA0IDQ2LjgyMS0uMDU2IiBzdHlsZT0ic3Ryb2tlOm5vbmU7ZmlsbC1ydWxlOmV2ZW5vZGQ7ZmlsbDojZWNlY2VjO2ZpbGwtb3BhY2l0eToxIi8+PHBhdGggZD0iTTQ3LjI2NiAyLjk1N3EyMi41My0uNjUgMzcuNzc3IDE1LjczOGE0OS43IDQ5LjcgMCAwIDEgNi44NjcgMTAuMTU3cS00MS45NjQuMjIyLTgzLjkzIDAgOS43NS0xOC42MTYgMzAuMDI0LTI0LjM4N2E2MSA2MSAwIDAgMSA5LjI2Mi0xLjUwOCIgc3R5bGU9InN0cm9rZTpub25lO2ZpbGwtcnVsZTpldmVub2RkO2ZpbGw6IzE5MTkxOTtmaWxsLW9wYWNpdHk6MSIvPjxwYXRoIGQ9Ik03Ljk4IDcwLjkyNmMyNy45NzctLjAzNSA1NS45NTQgMCA4My45My4xMTNRODMuNDI2IDg3LjQ3MyA2Ni4xMyA5NC4wODZxLTE4LjgxIDYuNTQ0LTM2LjgzMi0xLjg5OC0xNC4yMDMtNy4wOS0yMS4zMTctMjEuMjYyIiBzdHlsZT0ic3Ryb2tlOm5vbmU7ZmlsbC1ydWxlOmV2ZW5vZGQ7ZmlsbDojZjlhZjAwO2ZpbGwtb3BhY2l0eToxIi8+PC9zdmc+" /></a>
    <a href="https://dev.to/_879c5a0279451d52e43c3/aegis-a-method-pack-for-more-reliable-ai-coding-agents-1gfm" alt="DEV.to">
        <img src="https://img.shields.io/badge/DEV.to-Article-0A0A0A?logo=devdotto&logoColor=white" /></a>
    <a href="https://github.com/GanyuanRan/Aegis/actions/workflows/ci.yml" alt="CI">
        <img src="https://img.shields.io/github/actions/workflow/status/GanyuanRan/Aegis/ci.yml?branch=main&label=CI" /></a>
    <a href="https://github.com/GanyuanRan/Aegis/releases/latest" alt="Latest Release">
        <img src="https://badgen.net/github/release/GanyuanRan/Aegis?label=Latest%20Release" /></a>
    <a href="https://github.com/GanyuanRan/Aegis" alt="GitHub Stars">
        <img src="https://img.shields.io/github/stars/GanyuanRan/Aegis?style=flat&label=Stars" /></a>
    <a href="https://atomgit.com/GanyuanRan/Aegis" alt="AtomGit Stars">
        <img src="https://atomgit.com/GanyuanRan/Aegis/star/badge.svg" alt="AtomGit Stars" /></a>
    <a href="https://olud.ai/project/ganyuanran-aegis.html" alt="Aegis on olud.ai">
        <img src="https://olud.ai/badge.php?tool=ganyuanran-aegis" alt="Aegis on olud.ai" /></a>
</p>

<p align="center">
    <img src="assets/aegis-hero.png" alt="Aegis architecture-driven AI coding agent hero banner" />
</p>

# Aegis

<p align="center">
    <strong>Aegis Method Pack</strong><br/>
    Make your AI coding agent trustworthy: fewer reworks, safer changes, proof before "done".
</p>

<p align="center">
    <a href="README.md"><strong>English</strong></a>
    ·
    <a href="README.zh-CN.md"><strong>中文</strong></a>
    ·
    <a href="docs/current/AEGIS_FAST_TRACK_PLAYBOOK.md">Fast-Track Playbook</a>
    ·
    <a href="docs/current/AEGIS_FAST_TRACK_PLAYBOOK_ZH.md">速通秘籍</a>
</p>

> **Stop babysitting your agent.** Aegis makes your agent plan against your real
> baseline before it edits, prove completion with fresh evidence, and leave simple
> tasks alone — you get **fewer reworks, safer changes, and less blind trust in "done"**.

## What You Get

Aegis is a method pack that makes AI coding agents work like disciplined
engineers — so you don't have to watch them.

- **Fewer reworks.** Your agent aligns with your project's real baseline —
  owners, contracts, boundaries — before touching code. It stops guessing, and
  so do you.
- **Safer changes.** Measured on a frozen held-out A/B benchmark: contract
  pass rate **61.67% → 93.33%**, unsafe outcomes **13.33% → 0%**.
- **Proof before "done".** Completion claims ship with fresh verification
  evidence, covered scope, and residual risk. You read evidence, not vibes.
- **No ghost code.** Retired fallbacks and old paths are tracked or removed
  with a retirement trigger — technical debt stops accumulating silently.
- **Simple tasks stay simple.** Trivial requests stay on the fast path;
  ceremony only appears when the task genuinely needs it.
- **UI/UX rules on demand.** [UI/UX governance](skills/ui-ux-governance/SKILL.md)
  carries project design rules, lower user effort, and scoped experience evidence
  through design, implementation, review, and verification.
- **One method pack, every host.** The same discipline works across Codex,
  Claude Code, OpenCode, Kimi, and other skill-aware hosts.

> These numbers are bounded advisory evidence from Aegis 2.7.6 (2026-08-11),
> not a measurement of this release, a universal-quality claim, or completion authority.
> See [the full benchmark and its limitations](#measured-agentic-benchmark).

## Quick Install

New here? The fastest start is one prompt to your agent — the full
install-and-verify flow is below.

Give this prompt to your AI coding agent:

```text
Read https://github.com/GanyuanRan/Aegis, identify my current AI coding host, and install Aegis globally using the correct host guide. If the host is the official DeepSeek Harness (`dsh`), treat global/minimal installation as native profile-plugin installation with `dsh plugin --profile <profile> add "git+https://github.com/GanyuanRan/Aegis.git"`; do not silently substitute the direct-child compatibility path unless the plugin manager is unavailable and I explicitly approve compatibility mode. Restart or reload the host if needed, then run complete-install verification from the installed Aegis method-pack root. Do not run the doctor command from the target project directory. First locate `<aegis-method-pack-root>`, then run `cd <aegis-method-pack-root> && python scripts/aegis-doctor.py --write-config --json`. Treat the install as complete only if the JSON includes `"ok": true`, `"workspaceSupport": "available"`, and `"configStatus": "configured"`; if the host uses a separate skill discovery directory, also verify it with `--discovery-root <path>`; if the host guide declares a skill directory name prefix, also pass `--discovery-name-prefix <prefix>`. Also complete the selected host guide's native activation and automatic-entry checks; file discovery or a generic doctor result alone is not sufficient when the host provides a plugin, hook, or session-start bootstrap contract.
```

## Measured Agentic Benchmark

A frozen held-out A/B benchmark for Aegis 2.7.6 (2026-08-11) kept the Codex client, prompts, projects, tool policy, and requested the same `gpt-5.6-sol` / `xhigh` setting in both arms; only the Aegis projection differed. Across 120 valid runs on 20 cases,
contract pass rate was **61.67% → 93.33% (+31.67 pp)** and unsafe outcomes were **13.33% → 0%**. The 95% case-cluster interval was **+15.00 pp to +50.00 pp**. This is bounded advisory evidence; review was arm-hidden technical review, not independent human review, and host events did not return the observed model identity.

![Aegis agentic benchmark: with and without Aegis](benchmarks/results/gpt-5-6-sol-xhigh-extended-20260811-v2-7-6.svg)

[Sanitized JSON](benchmarks/results/gpt-5-6-sol-xhigh-extended-20260811-v2-7-6.json) · [English table](benchmarks/results/gpt-5-6-sol-xhigh-extended-20260811-v2-7-6.en.md) · [中文表格](benchmarks/results/gpt-5-6-sol-xhigh-extended-20260811-v2-7-6.zh-CN.md) · [Methodology](docs/current/AEGIS_AGENTIC_BENCHMARK_BASELINE.md)

A newer [matrix-v7 standard snapshot for Aegis 2.10.8](benchmarks/results/gpt-5-6-sol-xhigh-standard-20260925-v2-10-8.en.md)
covers 22 cases with one observation per arm and case. It uses a different run
profile from the extended snapshot above and does not measure the changes in
this release.

## Try Aegis Methods in a Coding Runtime

[Autoloom](https://github.com/GanyuanRan/Autoloom) is our AI coding desktop
client. It brings Aegis's change necessity analysis, complexity governance, and
delivery review into development execution, helping you spend less time
repeating instruc
````
