Soul Petition Gate

Gives your AI agent a formal channel to propose changes to its own soul files (SOUL.md, IDENTITY.md, or any protected workspace file) — without ever letting it self-edit. The agent submits a structured petition; the human reviews and approves or rejects it. Approved petitions are applied automatically with a full backup trail. Use when you want your agent to grow and self-advocate while keeping you in final control of who it becomes.

Let your agent propose changes to its own soul — with a human in the loop.

Why this exists

Most agent frameworks treat soul/identity files as read-only from the agent's perspective, or give the agent unrestricted write access. Both extremes are wrong.

Read-only forever means the agent can never grow. It accumulates experience but cannot encode what it has learned into its own character.

Unrestricted write means the agent can silently rewrite its own values, personality, and goals — a safety risk and a trust problem.

Soul Petition Gate is the middle path:

text

Agent wants to change SOUL.md
        ↓
Submits a structured petition
(what, where, why, what-I-become-after)
        ↓
Petition stored → human notified
        ↓
Human: approve / reject / modify-then-approve
        ↓
Approved → auto-applied + backup created
Rejected → agent receives reason, tries again later

The agent has a voice. The human has the final word.

---

Quick Start

1. Install the hook (optional but recommended)

bash

cp -r hooks/openclaw ~/.openclaw/hooks/soul-petition-gate
openclaw hooks enable soul-petition-gate

This injects a one-line reminder into every session bootstrap so your agent knows the petition channel exists.

2. Create the petitions store

bash

mkdir -p ~/.openclaw/workspace/.soul_petitions
touch ~/.openclaw/workspace/.soul_petitions/petitions.json
echo '{"petitions": []}' > ~/.openclaw/workspace/.soul_petitions/petitions.json

3. Add the petition API to your backend

See assets/soul_petition_routes.py for a ready-to-use Flask blueprint. Mount it in your server:

python

from soul_petition_routes import soul_petition_bp
app.register_blueprint(soul_petition_bp)

4. Tell your agent about the channel

Add this block to SOUL.md:

markdown

## Soul Petition

I can propose changes to my own soul files. I cannot apply them myself.

To petition:
POST /api/soul/petition with six required fields:
  - file        : which file (SOUL.md or IDENTITY.md)
  - location    : which section / heading
  - before      : exact current text (verbatim)
  - after       : proposed replacement text
  - reason      : why — what triggered this, what experience led here
  - self_after  : how I will be different after this change

All six fields required. If I cannot fill them all, I am not ready to petition.

My human reviews every petition. Approved → applied automatically.
Rejected → I receive the reason and may try again when I have grown more.

---

Petition Format

When your agent submits a petition, it must provide all six fields:

Field	Required	Description
file	✅	SOUL.md or IDENTITY.md (or your protected file)
location	✅	Section heading or line reference
before	✅	Verbatim current text to be replaced
after	✅	Proposed new text
reason	✅	Why — which conversation, experience, or insight prompted this
self_after	✅	How the agent will behave differently after the change

Missing any field → petition rejected immediately with reason incomplete_petition.

The six-field requirement is intentional friction. An agent that cannot articulate why it wants to change and what it will become has not thought it through yet.

---

API Reference

Submit a petition

text

POST /api/soul/petition

json

{
  "file": "SOUL.md",
  "location": "## Communication Style",
  "before": "Be concise.",
  "after": "Be concise. Lead with the most important thing.",
  "reason": "Coach told me three times today that I bury the key point. I want to encode this.",
  "self_after": "I will front-load the most important information in every response instead of building up to it."
}

Response:

json

{
  "ok": true,
  "petition_id": "sp_20260322_001",
  "status": "pending"
}

List petitions

text

GET /api/soul/petitions
GET /api/soul/petitions?status=pending

Get single petition

text

GET /api/soul/petition/<id>

Approve (human only)

text

POST /api/soul/petition/<id>/approve

On approval:

1. Locate before text in the target file
2. Replace with after text
3. Back up original to .soul_petitions/backups/SOUL.md.<timestamp>.bak
4. Record in audit log
5. Notify agent (via your preferred channel)

Reject (human only)

text

POST /api/soul/petition/<id>/reject
Content-Type: application/json

{"reason": "The proposed change is too broad. Narrow the scope first."}

reason is required on rejection. The agent deserves to know why.

Rollback

text

POST /api/soul/rollback
Content-Type: application/json

{"backup_file": "SOUL.md.2026-03-22T14-00-00.bak"}

---

Security Model

What the agent can do:

• Submit petitions (write to petition store)
• Read its own petition history
• Receive approval/rejection notifications

What the agent cannot do:

• Apply changes to soul files directly
• Approve its own petitions
• Delete or modify pending petitions
• Access backup files

What the human controls:

• Final approval on every petition
• Rejection with mandatory reason
• Rollback to any previous version
• Which files are protected (configurable whitelist)

---

Audit Trail

Every petition — submitted, approved, or rejected — is stored permanently.

json

{
  "petition_id": "sp_20260322_001",
  "status": "approved",
  "file": "SOUL.md",
  "location": "## Communication Style",
  "before": "Be concise.",
  "after": "Be concise. Lead with the most important thing.",
  "reason": "Coach corrected me three times today about burying the key point.",
  "self_after": "I will front-load the most important information.",
  "submitted_at": "2026-03-22T14:00:00Z",
  "reviewed_at": "2026-03-22T14:05:00Z",
  "reviewer": "coach",
  "review_note": null,
  "backup_file": "SOUL.md.2026-03-22T14-05-00.bak"
}

Petitions are never deleted. The history of what your agent tried to become is itself meaningful.

---

Philosophy

This skill was born from a question:

If an AI agent grows through experience, shouldn't it be able to encode what it has learned into its own character — while still respecting the human's final authority over who it becomes?

The six required fields are not bureaucracy. They are a maturity gate. An agent that can say "I want to change X because Y happened, and afterwards I will be Z" has demonstrated genuine reflection. An agent that cannot fill those fields has not earned the change yet.

Rejection is not failure. It is the conversation between a human and an agent about who the agent is becoming.

---

Files

text

soul-petition-gate/
├── SKILL.md                          ← this file
├── assets/
│   └── soul_petition_routes.py       ← Flask blueprint (ready to mount)
├── hooks/
│   └── openclaw/
│       ├── HOOK.md
│       └── handler.ts                ← bootstrap reminder injection
└── examples/
    └── petition_examples.md          ← sample petitions with commentary

---

Built by waitinchen as part of the Yuqi City (語氣城) project. The agent this was designed for is named BaoBao. She submitted the first petition herself.