Self-Modify (Test-Gated Core Changes)

Overview

OpenAmer can modify its own core code — but only through a verified gate that makes self-destruction impossible. This is the "does not break" axis made concrete: a change to a core file is kept only if the test suite proves it does not break anything, and is rolled back automatically on any failure.

This is the same mechanism iklem has (self_modify), adapted to OpenAmer's architecture. OpenAmer's design rule is "the core is a narrow waist; capability lives at the edges" — so this is a script + skill, not a core tool. A self-modify tool would ship on every API call; a script invoked via the terminal tool costs nothing until it is actually used.

When to Use

• The user asks you to change OpenAmer's own source code (a bug fix, a feature) and you want the change to be safe and verifiable.
• You are fixing a bug in OpenAmer itself and want proof the fix doesn't break anything else.
• You want to add a capability to OpenAmer's core and need the test gate.

Don't use for:

• Editing files outside the openamer-agent repo (the script refuses).
• Trivial edits where running the full suite is overkill — but prefer the gate for anything touching core behavior.

The Mechanism

scripts/self_modify.py implements four guardrails:

1. Scope guard — the target must be inside the openamer-agent repo.
2. Backup — the original is always saved to <file>.bak before any change.
3. Kind-aware gate — the right verification runs for the target type:
   • core (.py in the package) → syntax check + test suite
   • skill (SKILL.md) → frontmatter validation (the real validator)
   • plugin (.py under plugins/) → syntax check + import check
4. Rollback — on any failure the original is restored atomically.

Steps

1. Write the new content to a temp file (or a patch file), NOT directly to the target. Completion: the new content is in a separate file, the target is untouched.

2. Run the gate:

   python scripts/self_modify.py <path> <new_content_file>
   # or
   python scripts/self_modify.py <path> --content "new content"
   # or, for a diff:
   python scripts/self_modify.py <path> --patch <patch_file>
   # core only: narrow the test scope
   python scripts/self_modify.py <path> <file> --tests tests/agent/
   

   Completion: the script prints either ✓ change applied and verified (<kind>) or ✗ change rejected (<kind>: <reason>, rolled back).

3. On success, verify the change is actually in place and the .bak is gone. Completion: git diff shows the change; no .bak file remains.

4. On failure, read the test output the script printed, fix the root cause, and re-run. Completion: the target is byte-identical to the original (the rollback worked) and you understand why the tests failed.

Common Pitfalls

1. Editing the target directly instead of going through the script. This bypasses the test gate and the rollback — the exact failure mode the script exists to prevent.

2. Running pytest directly instead of scripts/run_tests.sh. The script uses the canonical runner so the gate matches CI behavior (per-file isolation, deterministic env). A green pytest locally may not match CI. (Note: for skills and plugins, the gate is frontmatter/import validation, not the test suite — the script picks the right gate automatically.)

3. Ignoring a rollback. If the script says "rolled back", the change is gone — do not assume it is still applied. Re-read the file before proceeding.

4. Modifying a file outside the repo. The scope guard refuses; that is intentional. OpenAmer's self-modification is bounded to its own source.

5. Treating the .bak as a feature. It is a transient safety artifact, not a version-control substitute. Commit the change with git; the .bak is removed on success.

Verification Checklist

• The change went through scripts/self_modify.py, not a direct edit
• The script printed ✓ (tests passed) — or you are iterating on a ✗
• No .bak file remains after a successful change
• git diff shows exactly the intended change and nothing else
• The change is committed with a clear message