Skip to content

imMamdouhaboammar/anti-slop-engineering / skills/repo-memory-and-invariant-steward

repo-memory-and-invariant-steward

Verified

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.

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


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.

slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall