wallaby-agent-rules 1.4.2 adds deterministic governance for agent memory changes and the documents each change affects, with lossless CLI upgrades for existing installs. It verifies changes without editing your documents. Eighteen regression tests pass. In our old-install test, it replaced one CLI and left MEMORY.md, NOW.md, receipts, configs, and every other project file byte-for-byte unchanged. The old CLI was backed up first.
That upgrade is the entry point, not the whole system. The governance pack maps each change to its dependent documents. It also checks premise failures and preserves the history when one statement replaces another. One Python file. JSON for state. No model calls. A fresh install takes about a minute.
The upgrade should not touch the memory
Run the new CLI against the existing project. Without --apply, it only previews the change:
python3 /path/to/newer/memory_governance.py \
--target /path/to/your-project upgrade
The preview prints the current and available versions plus the backup path. It changes nothing and refuses a downgrade. After reviewing it, run the same command with --apply.
An applied upgrade replaces only scripts/memory_governance.py. The previous CLI goes to .memory/backups/; the new one must start and report the expected version. If that validation fails, the original CLI is restored. No data migration is needed.
This is deliberately narrower than a project migration. MEMORY.md, NOW.md, .memory/ configs, receipts, and your other documents stay untouched.
A rename is not done when one file changes
Suppose you retire old-component. Tell the governance CLI which event happened and which term should disappear:
python3 scripts/memory_governance.py impact \
--event file_move \
--terms "old-component" \
--record
In our clean-project demo, the scan found one remaining reference in README.md and created receipt R-000001. Verification failed:
NOT VERIFIED R-000001: 1 unresolved and 0 unread file(s)
README.md (1)
A log entry saying “renamed” would have missed that reference. After fixing it, run verify again. If another mention is intentional history, allow that exact path instead of deleting the record:
python3 scripts/memory_governance.py verify \
--receipt R-000001 \
--allow "archive/**"
Impact scans and later verifications stay separate in .memory/receipts.jsonl. Each receipt is append-only evidence of what was found and what was eventually accepted.
Nine event types ship in .memory/impact.json: feature, mechanism, document, external_copy, automation, decision, skill, file_move, and closure. Each maps to the surfaces that need review. You can edit that map to match your project. doctor rejects malformed rules rather than quietly ignoring them.
Document contents stay out of the report. The scanner returns paths and match counts, skips .git, .credentials, .memory, dependency directories, and build output, and never edits your documents. Unreadable or oversized files block verification; a skipped file cannot become evidence that old references are gone.
Premises need a way to fail
Some rules depend on a relationship staying true. A required file must exist. A JSON field must keep a specific value. A forbidden artifact must stay absent. The pack turns those relationships into four deterministic checks: file_missing, file_exists, text_contains, and json_equals. It does not execute shell commands from the config.
Each premise has a failure signal and a level:
| Level | What happens when the signal fires |
|---|---|
P0 |
Stop the action, exit 2 |
P1 |
Require human review, exit 1 |
P2 |
Warn without blocking routine work |
Run the checks with:
python3 scripts/memory_governance.py premise check
A manual signal at P0 or P1 returns UNVERIFIED until someone supplies evidence. It cannot produce a silent green result. A premise without an observable failure signal is a note for discussion, not a reliable check.
Contradictions keep the losing side
When a new statement replaces an old one, record both and the evidence:
python3 scripts/memory_governance.py contradict add \
--old "INDEX.md is optional" \
--new "INDEX.md changes with files" \
--evidence "DECISION-42"
Open contradictions make doctor return nonzero. Resolving one appends the decision and its source to the history; it does not erase the earlier claim. That gives a reviewer somewhere to look when two documents still disagree about which rule applies.
The weekly pass is a separate habit
Impact receipts tell you whether one change propagated. A weekly reconciliation asks whether the memory process is still healthy across a wider window. The creation guide starts with three commands:
python3 scripts/health_check.py
python3 scripts/reconcile.py
python3 scripts/memory_governance.py doctor
They cover different gaps. health_check.py checks file and memory hygiene. reconcile.py looks for completion claims that conflict with current state or lack evidence. doctor checks premise failures, open contradictions, and pending impact receipts.
A useful weekly pass has a fixed scope, usually seven days. Run the deterministic checks first, then inspect recent changes along with premises and contradictions. Finish by reading a small sample of high-impact changes yourself. Live systems need fresh evidence at review time; an old snapshot does not prove current production state.
Assign every finding an owner and a review condition. Dead links and stale state can be quick fixes; disputed sources need a decision. Intentional history needs an explicit exception. A fourth bucket belongs to the checker itself when its rules cannot answer the question. This complements the earlier weekly audit between the log and current state, rather than replacing it with another dashboard.
What 18 tests prove, and what they do not
The regression suite covers installation and all nine event types. It also checks premise exit codes and contradiction history, with explicit cases for scan limits and false-green prevention. Upgrade tests exercise dry runs and data preservation, plus downgrade refusal and backup creation. A separate case restores the original CLI after a failed upgrade. We reran all 18 tests for this post.
Those are compatibility and behavior checks. They do not demonstrate better memory accuracy across other projects, and they do not measure adoption outcomes. The scanner matches terms; a person still decides whether a match is stale or intentional, and whether it belongs outside the current scope.
Install it, or preview the upgrade
From the repository:
python3 extras/memory-governance/memory_governance.py \
--target /path/to/your-project init
cd /path/to/your-project
python3 scripts/memory_governance.py doctor
init never overwrites an existing config or script. You can add the pack beside existing MEMORY.md, NOW.md, and INDEX.md files. A fresh doctor run ends with DOCTOR OK.
The wallaby-agent-rules repository has the full CLI and weekly guide, plus example JSON files and tests. If you are investigating the write side first, start with why an agent can say it saved but did not. If you already use the core memory system, the L0 install prompt is the shorter entry point.
Start with doctor, or preview an upgrade before applying it.
Disclosure: Wallaby Token builds open-weight inference infrastructure and develops wallaby-agent-rules. We use file-based memory and this governance pack on our own projects.