agentleFS
imMamdouhaboammarimMamdouhaboammar/anti-slop-engineering/skills/repo-memory-and-invariant-steward/SKILL.md

repo-memory-and-invariant-steward

Skill4 starsChanged 31 days agoMITView on GitHub

Maintains the repository's architectural memory and enforces invariant preservation across sessions. Use when syncing historical decision records into a living compact Invariant Ledger, checking PRs/branches for architectural drift, verifying Gate 0 invariant constraints, or validating formal Reassessment Triggers — even if they don't explicitly say "invariant steward". Do NOT use for routine cosmetic edits or non-consequential scripts.

The file

We split this skill into the rules it gives an agent

9 rules. About 0 are common, 6 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Compact Ledger Ingestion at Gate 0: Before writing or approving code, agents must consult the living Invariant Ledger to understand the …

    line 41
  2. Distinctive:

    Bidirectional Cryptographic Provenance: Every ledger entry must trace its lineage back to an authoritative record path and SHA-256 hash.

    line 42
  3. Very specific:

    Fail-Closed Drift Defense: If an incoming change touches an invariant-governed path and alters required patterns, introduces forbidden …

    line 43
  4. Very specific:

    Token-Thrifty TOON Generation: Every ledger sync must emit both a canonical JSON artifact (.anti-slop/invariant-ledger.json) and an …

    line 50
  5. Distinctive:

    Explicit Enforcement Scopes: Every invariant must declare governed file paths (globs), required patterns (tokens that must not be deleted), …

    line 51
  6. Distinctive:

    When an AI agent initializes Gate 0 for any task:

    line 70
  7. Very specific:

    Path Intersection Audit: Check whether any file in the planned change intersects with enforcement_scope.paths of any active invariant.

    line 73
  8. Distinctive:

    Reassessment Preflight: If the user request directly demands changing a behavior protected by an active invariant, halt immediately and …

    line 75
  9. Distinctive:

    Before approving a PR or concluding an architectural session:

    line 120

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Skill: Repo Memory & Invariant Steward (الذاكرة المعمارية للمنظومة)

Invariants outlive sessions. Never allow architectural decisions to evaporate into git history.

Why This Skill Is Needed & Target State

Autonomous AI agents generate exceptional decision records (decision-record.json, paranoid-record.json, rollout-record.json, etc.) in individual sessions. However, across sessions and multi-developer pull requests, repositories suffer from Architectural Amnesia:

  1. Agents start new sessions with a blank slate, ignoring hard-won architectural invariants and re-introducing banned anti-patterns.
  2. In-flight pull requests unknowingly violate past concurrency models, bypass zero-trust boundaries, break wire compatibility, or delete idempotency keys without opening an official Reassessment Trigger.
  3. Historical decisions remain scattered across dozens of individual JSON files rather than being indexed as an actionable, living constraint set for Gate 0 ingestion.

The target state is Persistent Architectural Memory: all approved architectural invariants are compiled into a compact, living Invariant Ledger (.anti-slop/invariant-ledger.json and .anti-slop/invariant-ledger.toon) read automatically during Gate 0, and every incoming PR or diff is evaluated for architectural drift before code reaches production.


Activation and Boundaries

SituationBehavior
Starting a new feature, refactor, or bugfix in Gate 0Ingest active invariants from .anti-slop/invariant-ledger.toon; map blast radius against governed paths
Concluding an architectural decision or adding a new recordRun Invariant Ledger Sync to index new invariants, assertions, and revisit triggers
Reviewing or opening a Pull Request / branch diffRun Drift Detection (steward drift --base HEAD); verify zero active invariants are violated or silently dropped
Legitimate evolution or retirement of a recorded invariantFile and validate a formal Reassessment Trigger (reassessment-trigger.json) before modifying protected contracts
Routine styling tweaks, local test fixtures, or docs typosDo not activate; use standard Anti-Slop Engineering BUILD/FIX gates

The Five Absolute Laws

  1. The Invariant Permanence Axiom (Memory Survives Sessions): An architectural invariant recorded in an approved decision record remains legally binding on the repository until explicitly superseded, waived, or deprecated through a verified Reassessment Trigger. Time, session boundary, or agent model change does not decay an invariant.
  2. Zero Silent Overrides (Reassessment Before Mutation): Code modifications that conflict with an active recorded invariant are fatal defects. An agent cannot "silently clean up" or bypass an established architectural constraint because it seems inconvenient for the current task.
  3. Compact Ledger Ingestion at Gate 0: Before writing or approving code, agents must consult the living Invariant Ledger to understand the non-negotiable boundaries of the touched subsystems.
  4. Bidirectional Cryptographic Provenance: Every ledger entry must trace its lineage back to an authoritative record path and SHA-256 hash. Orphaning or forging invariants without backing evidence is strictly prohibited.
  5. Fail-Closed Drift Defense: If an incoming change touches an invariant-governed path and alters required patterns, introduces forbidden patterns, or removes contracts, the drift gate must block (exit code 2) until a valid Reassessment Trigger is supplied.

Invariant Rules

  1. Deterministic Ledger Sync: Historical records (*record*.json) must be parsed, deduplicated, and indexed by unique Invariant IDs (e.g. INV-PARANOID-001, INV-ROLLOUT-002).
  2. Token-Thrifty TOON Generation: Every ledger sync must emit both a canonical JSON artifact (.anti-slop/invariant-ledger.json) and an ultra-compact TOON representation (.anti-slop/invariant-ledger.toon) to minimize context consumption in Gate 0.
  3. Explicit Enforcement Scopes: Every invariant must declare governed file paths (globs), required patterns (tokens that must not be deleted), and forbidden patterns (anti-patterns that must not be introduced).
  4. Mandatory Reassessment Delta: A Reassessment Trigger cannot be a bare override; it must provide a structured trade_off_delta detailing what is gained, what operational risk is assumed, and what verification proof was gathered.
  5. No Ghost Waivers: A temporary waiver must declare an explicit expiry date or issue milestone. Permanent waivers are invalid; they must be structured as formal superseding records.

Execution Router

Task ShapePrimary WorkflowReference Contract
Compile or update living invariant indexSync LedgerLedger Contract
Scan PR or Git diff for architectural driftDrift AuditDrift Engine
Evolve, waive, or retire an existing invariantReassess InvariantReassessment Protocol
Gate 0 Agent context loading & blast radius checkGate 0 Integrationscripts/invariant_steward_guard.py

Gate 0 Ingestion Protocol

When an AI agent initializes Gate 0 for any task:

  1. Read Compact Memory: Ingest .anti-slop/invariant-ledger.toon (or run npx anti-slop-engineering steward sync if missing).
  2. Path Intersection Audit: Check whether any file in the planned change intersects with enforcement_scope.paths of any active invariant.
  3. Constraint Binding: Note all required patterns and forbidden patterns for the governed files into the task change contract (Gate 1).
  4. Reassessment Preflight: If the user request directly demands changing a behavior protected by an active invariant, halt immediately and prompt for or draft an official Reassessment Trigger before touching code.

PR Drift Detection & Violation Taxonomy

The Drift Detection engine classifies violations into three severity tiers:

                  Incoming PR / Git Diff
                            │
               ┌────────────┴────────────┐
               ▼                         ▼
     Touches Governed Path      Outside Governed Path
               │                         │
      ┌────────┴────────┐                ▼
      ▼                 ▼            Clean (Pass)
Forbidden Pattern   Required Pattern
  Introduced            Removed
      │                 │
      ▼                 ▼
  [BLOCKER]         [BLOCKER]
INV_FORBIDDEN_PAT  INV_PATTERN_REMOVED
      │                 │
      └────────┬────────┘
               ▼
   Is Reassessment Trigger Present & Valid?
         ├── YES ──► Waived / Superseded (Pass)
         └── NO  ──► Hard Gate Block (Exit Code 2)

Prohibited Anti-Patterns (Instant Rejection List)

  1. Silent Invariant Dropping: Removing a database index, timeout, or auth guard because "it simplified the test."
  2. Ghost Overrides: Modifying a contract without citing or creating a reassessment-trigger.json.
  3. Split-Brain Ledgers: Committing multiple conflicting ledger files instead of a unified single source of truth.
  4. Vague Invariants: Registering broad slogans ("make it fast") without actionable assertions, paths, or patterns.
  5. Unverified Waivers: Claiming an invariant is waived without providing empirical verification proof in the trigger record.

Mandatory Pre-Execution Interrogation Matrix

Before approving a PR or concluding an architectural session:

  • Memory Check: Did this session create new architectural rules? If yes, was steward sync executed to capture them?
  • Drift Check: Did any modified line in this PR touch an invariant-governed file? Did steward drift --base HEAD return 0?
  • Pattern Check: Were any required safety tokens (e.g. Idempotency-Key, AbortSignal.timeout, timingSafeEqual) deleted from governed modules?
  • Authority Check: Does every active invariant trace back to a valid, committed decision record with a matching SHA-256?

Required CLI Commands

# Sync all historical records into living Invariant Ledger & TOON
npx anti-slop-engineering steward sync
# or: python3 scripts/invariant_steward_guard.py sync --records skills docs .anti-slop

# Check working tree or branch diff for architectural drift
npx anti-slop-engineering steward drift --base HEAD
# or: python3 scripts/invariant_steward_guard.py drift --base HEAD

# Validate an Invariant Ledger structural integrity
npx anti-slop-engineering steward audit .anti-slop/invariant-ledger.json
# or: python3 scripts/invariant_steward_guard.py audit .anti-slop/invariant-ledger.json

# Validate an official Reassessment Trigger record
npx anti-slop-engineering steward reassess reassessment-trigger.json
# or: python3 scripts/invariant_steward_guard.py reassess reassessment-trigger.json

Domain References

  • Playbook Suite Overview: Central operational index for architectural memory stewardship.
  • The Invariant Steward Playbook: Syncing, Gate 0 memory indexing, and ledger lifecycle.
  • Drift Triage & Remediation Playbook: Handling drift alerts, investigating root causes, and resolving conflicts.
  • Memory Anti-Patterns Catalog: Forensic failure modes: architectural amnesia, phantom overrides, and split-brain states.
  • Invariant Ledger Contract: Schema specification for the living Invariant Ledger.
  • Drift Detection Engine: Diff parsing heuristics, AST matching, and fail-closed gates.
  • Reassessment Protocol: Legitimate evolution, superseding, and deprecation mechanics.
  • Gate 0 Memory Integration: Agent instructions for zero-drift execution.

Failure Taxonomy

Failure ModeObservable SignalRemediation
Architectural AmnesiaNew PR re-implements banned pattern or drops auth boundaryIngest ledger at Gate 0; reject PR via steward drift
Phantom OverrideInvariant assertion deleted without reassessment recordFile formal reassessment-trigger.json or revert deletion
Stale LedgerDecision records committed without syncing to ledgerExecute steward sync in pre-commit hook or CI pipeline
Unanchored InvariantInvariant record missing authority.record_sha256Re-sync from authoritative source record
Context ExplosionLedger exceeds token budget in agent promptEnforce compact .anti-slop/invariant-ledger.toon representation

Delegated Skills

  • anti-slop-engineering: Follow Gate 0 discovery and baseline locking across all coding changes.
  • decision-guard: Produce initial decision records with explicit trade-offs and revisit triggers.
  • paranoid-principal-architect: Supply zero-trust and 10M scale invariants into the memory ledger.
  • safe-evolution-and-rollout-choreographer: Supply wire-compatibility and dark launch invariants.
  • observability-and-slo-architect: Supply telemetry cardinality and SLO budget invariants.

Completion and Limits

The stewardship task is complete when all active decision records are synced into .anti-slop/invariant-ledger.json and .anti-slop/invariant-ledger.toon, the ledger passes structural audit with 0 findings, and steward drift --base HEAD confirms that no active invariants were broken or dropped without an approved Reassessment Trigger.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.