feat(codex): sync clear teardown + --remove mode

- sync.sh: add `clear` positional — teardown mode that uninstalls this marketplace's Claude plugins and the Codex Rig plugin, then strips the managed block from $CODEX_HOME/AGENTS.md; honors claude/codex scoping and leaves marketplace registrations plus external plugins in place
- install_global_agents.py: add `--remove` mode (marker-aware stripped_payload + remove_global_agents) — keeps a timestamped backup, deletes AGENTS.md when it held only the managed block, refuses a tampered block without writing; --source is now optional under --remove
- tests: 6 cases covering remove (delete-solely-ours, strip-preserving-user-content, absent no-op, refuse-tampered-block, arg validation) and the sync clear teardown wiring
- bump codex-rig 0.2.2 -> 0.3.0 (new capability)
- document `clear` teardown in root and codex-rig READMEs

package-manifest.json is intentionally left out — it is a generated artifact under concurrent edit; a single regen covering all changes lands separately.

---
Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com>

Author: Borda

README.md

@@ -304,7 +304,7 @@ Start a fresh session. The plugin uses exact role-card injection for parallel bl
 
 ### Product boundary
 
-`plugins/codex-rig/` is the installable source of truth for workflows, role cards, shared gates, calibration, hooks, lifecycle tooling, and an inert global-instructions template. Direct `codex plugin` installation leaves global and project instructions untouched. From this checkout, plain `bash sync.sh` performs the full Claude + Codex restore; `bash sync.sh codex` limits it to Codex. Both install or update one backup-protected block in `$CODEX_HOME/AGENTS.md` by default. Pass `--no-codex-global-agents` to skip it; `bash sync.sh claude` changes only Claude scope. Project `AGENTS.md` files and the installed plugin cache remain untouched. `--codex-ref REF` remains a Codex source selector.
+`plugins/codex-rig/` is the installable source of truth for workflows, role cards, shared gates, calibration, hooks, lifecycle tooling, and an inert global-instructions template. Direct `codex plugin` installation leaves global and project instructions untouched. From this checkout, plain `bash sync.sh` performs the full Claude + Codex restore; `bash sync.sh codex` limits it to Codex. Both install or update one backup-protected block in `$CODEX_HOME/AGENTS.md` by default. Pass `--no-codex-global-agents` to skip it; `bash sync.sh claude` changes only Claude scope. Project `AGENTS.md` files and the installed plugin cache remain untouched. `--codex-ref REF` remains a Codex source selector. `bash sync.sh clear` reverses a sync: it uninstalls this marketplace's Claude plugins and the Codex Rig plugin, then strips the managed `$CODEX_HOME/AGENTS.md` block (timestamped backup kept, user content preserved), honoring `claude`/`codex` scope and leaving marketplace registrations plus external plugins in place.
 
 Use `$codex-rig:sync` for a dry-run installation report and approval-gated marketplace refresh. Older AI-Rig versions copied files into `~/.codex/`; because those files had no durable ownership marker, they require a separate backup and ownership review before manual cleanup.
 

plugins/codex-rig/.codex-plugin/plugin.json

@@ -30,5 +30,5 @@
   "name": "codex-rig",
   "repository": "https://github.com/Borda/AI-Rig",
   "skills": "./skills/",
-  "version": "0.2.2"
+  "version": "0.3.0"
 }

plugins/codex-rig/README.md

@@ -57,10 +57,14 @@ From an AI-Rig checkout:
 bash sync.sh                                      # full Claude + Codex restore
 bash sync.sh codex                                # Codex scope only
 bash sync.sh codex --no-codex-global-agents       # skip global guidance
+bash sync.sh clear                                # teardown: uninstall plugins + strip managed block
+bash sync.sh clear codex                          # teardown Codex scope only
 ```
 
 `bash sync.sh claude` changes only Claude scope. `--codex-ref REF` selects a Codex source revision; it does not change product scope.
 
+`bash sync.sh clear` reverses a sync instead of installing: it uninstalls this marketplace's Claude plugins and the Codex Rig plugin, then strips the managed block from `${CODEX_HOME:-$HOME/.codex}/AGENTS.md`, keeping a timestamped backup and preserving user-owned content byte-for-byte. It honors `claude`/`codex` scoping and leaves marketplace registrations plus external plugins in place. A tampered managed block makes the strip fail without writing, exactly like install.
+
 Codex sync uses the template from the installed marketplace revision. A missing global file is created as one SHA-256-authenticated managed block. Existing user instructions are backed up and preserved byte-for-byte outside that block. An exact unmarked copy from an older sync is adopted without duplication. Later runs update only an unmodified managed block and otherwise fail without writing when markers are missing, duplicated, malformed, or manually changed.
 
 Marketplace/plugin refresh can finish before a later global-instruction merge fails; resolve the reported target state and rerun sync. Avoid concurrent edits during restoration. The installer rechecks observed bytes immediately before atomic replacement, but portable filesystems provide no universal compare-and-swap operation.

plugins/codex-rig/scripts/install_global_agents.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Safely install or update Codex Rig's managed global-instruction block."""
+"""Safely install, update, or remove Codex Rig's managed global-instruction block."""
 
 from __future__ import annotations
 
@@ -74,6 +74,38 @@ def merged_payload(existing: bytes, block: bytes) -> tuple[bytes, str]:
     return updated, "already current" if updated == existing else "updated"
 
 
+def stripped_payload(existing: bytes) -> tuple[bytes, str]:
+    """Remove one authenticated managed block, preserving every external byte."""
+    try:
+        existing.decode("utf-8")
+    except UnicodeDecodeError as error:
+        raise UnsafeGlobalAgentsState("existing AGENTS.md is not UTF-8; refusing write") from error
+
+    begin_count = existing.count(BEGIN_PREFIX)
+    end_count = existing.count(END_MARKER.rstrip(b"\n"))
+    if begin_count == 0 and end_count == 0:
+        return existing, "absent"
+    if begin_count != 1 or end_count != 1:
+        raise UnsafeGlobalAgentsState("managed markers are malformed or duplicated; refusing write")
+
+    begin_match = BEGIN_PATTERN.search(existing)
+    if begin_match is None:
+        raise UnsafeGlobalAgentsState("managed begin marker is malformed; refusing write")
+    end_index = existing.find(END_MARKER, begin_match.end())
+    if end_index < 0:
+        raise UnsafeGlobalAgentsState("managed end marker is malformed; refusing write")
+    body = existing[begin_match.end() : end_index]
+    if sha256(body) != begin_match.group(1).decode("ascii"):
+        raise UnsafeGlobalAgentsState("managed block was modified; refusing write")
+
+    block_end = end_index + len(END_MARKER)
+    updated = existing[: begin_match.start()] + existing[block_end:]
+    # collapse the single separator install prepended so removal leaves no doubled blank line
+    if updated.endswith(b"\n\n") and existing[: begin_match.start()].endswith(b"\n\n"):
+        updated = updated[:-1]
+    return updated, "removed"
+
+
 def backup_target(target: Path, codex_home: Path, payload: bytes) -> Path:
     """Create and verify a unique backup before changing an existing target."""
     backup_root = codex_home / "backups" / "codex-rig"
@@ -140,19 +172,50 @@ def install_global_agents(source: Path, codex_home: Path) -> tuple[str, Path, Pa
     return action, target, backup
 
 
+def remove_global_agents(codex_home: Path) -> tuple[str, Path, Path | None]:
+    """Strip Codex Rig's managed block from AGENTS.md without touching user content."""
+    target = codex_home / "AGENTS.md"
+    if not target.exists():
+        return "absent", target, None
+    if target.is_symlink():
+        raise UnsafeGlobalAgentsState(f"target is a symlink; refusing write: {target}")
+    if not target.is_file():
+        raise UnsafeGlobalAgentsState(f"target is not an ordinary file; refusing write: {target}")
+
+    existing = target.read_bytes()
+    updated, action = stripped_payload(existing)
+    if action == "absent":
+        return "absent", target, None
+
+    backup = backup_target(target, codex_home, existing)
+    if updated.strip() == b"":
+        target.unlink()  # file held only our block — remove it entirely
+        return "removed-file", target, backup
+    mode = stat.S_IMODE(target.stat().st_mode)
+    atomic_write(target, updated, mode, existing)
+    return "removed-block", target, backup
+
+
 def parse_args() -> argparse.Namespace:
     """Parse explicit source and Codex-home paths."""
     parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument("--source", type=Path, required=True, help="packaged assets/AGENTS.md template")
+    parser.add_argument("--source", type=Path, help="packaged assets/AGENTS.md template (required unless --remove)")
     parser.add_argument("--codex-home", type=Path, required=True, help="target Codex home")
-    return parser.parse_args()
+    parser.add_argument("--remove", action="store_true", help="strip the managed block instead of installing it")
+    args = parser.parse_args()
+    if not args.remove and args.source is None:
+        parser.error("--source is required unless --remove is given")
+    return args
 
 
 def main() -> int:
-    """Run one fail-closed global-instruction installation."""
+    """Run one fail-closed global-instruction installation or removal."""
     args = parse_args()
     try:
-        action, target, backup = install_global_agents(args.source, args.codex_home)
+        if args.remove:
+            action, target, backup = remove_global_agents(args.codex_home)
+        else:
+            action, target, backup = install_global_agents(args.source, args.codex_home)
     except UnsafeGlobalAgentsState as error:
         print(f"global-agents-error: {error}", file=sys.stderr)
         return 4

plugins/codex-rig/tests/test_global_agents_installer.py

@@ -36,6 +36,16 @@ def run_installer(
     )
 
 
+def run_remover(codex_home: Path) -> subprocess.CompletedProcess[str]:
+    """Run the packaged installer in --remove mode against one isolated Codex home."""
+    return subprocess.run(
+        [sys.executable, str(INSTALLER), "--remove", "--codex-home", str(codex_home)],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+
+
 def managed_body(payload: bytes) -> tuple[str, bytes]:
     """Return the recorded digest and exact body bytes from one managed block."""
     begin_prefix = BEGIN_PREFIX.encode("ascii")
@@ -222,6 +232,102 @@ def test_atomic_write_refuses_target_drift_before_replace(tmp_path: Path) -> Non
     assert target.read_bytes() == b"concurrent edit\n"
 
 
+def test_remove_deletes_file_that_held_only_managed_block(tmp_path: Path) -> None:
+    """Prove teardown deletes an AGENTS.md that Codex Rig alone created."""
+    source = tmp_path / "template.md"
+    source.write_text("managed policy\n", encoding="utf-8")
+    codex_home = tmp_path / "codex-home"
+    assert run_installer(source, codex_home).returncode == 0
+    target = codex_home / "AGENTS.md"
+    original = target.read_bytes()
+
+    result = run_remover(codex_home)
+
+    assert result.returncode == 0, result.stderr
+    assert not target.exists()
+    assert "removed-file" in result.stdout
+    backups = list((codex_home / "backups" / "codex-rig").glob("*-AGENTS.md"))
+    assert len(backups) == 1
+    assert backups[0].read_bytes() == original
+
+
+def test_remove_strips_block_and_preserves_user_content(tmp_path: Path) -> None:
+    """Prove teardown removes only the managed block, keeping user-owned guidance."""
+    source = tmp_path / "template.md"
+    source.write_text("managed policy\n", encoding="utf-8")
+    codex_home = tmp_path / "codex-home"
+    codex_home.mkdir()
+    target = codex_home / "AGENTS.md"
+    user_content = "# User policy\n\nKeep this exactly.\n"
+    target.write_text(user_content, encoding="utf-8")
+    assert run_installer(source, codex_home).returncode == 0
+
+    result = run_remover(codex_home)
+
+    assert result.returncode == 0, result.stderr
+    assert target.read_text(encoding="utf-8") == user_content
+    assert BEGIN_PREFIX not in target.read_text(encoding="utf-8")
+    assert "removed-block" in result.stdout
+
+
+def test_remove_is_noop_when_no_managed_block_present(tmp_path: Path) -> None:
+    """Prove teardown leaves an unmanaged AGENTS.md untouched and reports absent."""
+    codex_home = tmp_path / "codex-home"
+    codex_home.mkdir()
+    target = codex_home / "AGENTS.md"
+    target.write_text("# only user content\n", encoding="utf-8")
+    before = target.read_bytes()
+
+    result = run_remover(codex_home)
+
+    assert result.returncode == 0, result.stderr
+    assert target.read_bytes() == before
+    assert "absent" in result.stdout
+
+
+def test_remove_refuses_modified_managed_block(tmp_path: Path) -> None:
+    """Fail without writes when the managed block was tampered with before teardown."""
+    source = tmp_path / "template.md"
+    source.write_text("managed policy\n", encoding="utf-8")
+    codex_home = tmp_path / "codex-home"
+    assert run_installer(source, codex_home).returncode == 0
+    target = codex_home / "AGENTS.md"
+    target.write_text(
+        target.read_text(encoding="utf-8").replace("managed policy", "manually changed"), encoding="utf-8"
+    )
+    before = target.read_bytes()
+
+    result = run_remover(codex_home)
+
+    assert result.returncode == 4
+    assert target.read_bytes() == before
+    assert "refusing" in result.stderr.lower()
+
+
+def test_remove_requires_no_source_argument(tmp_path: Path) -> None:
+    """Prove --remove needs only --codex-home while install still requires --source."""
+    missing_source = subprocess.run(
+        [sys.executable, str(INSTALLER), "--codex-home", str(tmp_path)],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+
+    assert missing_source.returncode == 2
+    assert "--source is required unless --remove" in missing_source.stderr
+
+
+def test_sync_clear_teardown_wiring() -> None:
+    """Bind the clear teardown path (plugin uninstall + AGENTS.md strip) to installed sync bytes."""
+    sync_path = PLUGIN_ROOT.parents[1] / "sync.sh"
+    script = sync_path.read_text(encoding="utf-8")
+    assert "clear)      CLEAR=true ;;" in script
+    assert "if $CLEAR; then" in script
+    assert 'claude plugin uninstall "${p}@${MARKETPLACE}"' in script
+    assert 'codex plugin remove "$CODEX_PLUGIN"' in script
+    assert '--remove --codex-home "${CODEX_HOME:-$HOME/.codex}"' in script
+
+
 def test_sync_global_agents_defaults_on_with_negative_opt_out() -> None:
     """Bind full-restore defaults and opt-out wiring to installed-plugin bytes."""
     sync_path = PLUGIN_ROOT.parents[1] / "sync.sh"

sync.sh

@@ -1,11 +1,15 @@
 #!/usr/bin/env bash
 # Install AI-Rig plugins for Claude Code and/or Codex from the GitHub remote.
 # Remote installs use pushed state — commit and push before running; release tags are optional pins.
-# Run from the project root: bash sync.sh [claude] [codex] [--no-clean] [--codex-ref REF] [--no-codex-global-agents]
+# Run from the project root: bash sync.sh [claude] [codex] [clear] [--no-clean] [--codex-ref REF] [--no-codex-global-agents]
 #
 # Arguments (order-independent):
 #   claude   — sync Claude plugins + foundry:setup (default: both)
 #   codex    — install or update the Codex Rig plugin (default: both)
+#   clear    — teardown instead of install: uninstall this marketplace's Claude plugins
+#              + the Codex Rig plugin, and strip the managed block from $CODEX_HOME/AGENTS.md
+#              (a timestamped backup is kept). Honors claude/codex scoping (default: both sides).
+#              Leaves marketplace registrations and external plugins (caveman/ponytail/openai-codex) in place.
 #   --no-clean — skip uninstall before reinstalling (default: uninstall first)
 #   --codex-ref REF — pin Codex Rig to one Git ref (default: latest default branch)
 #   --no-codex-global-agents — skip Codex Rig's managed block in $CODEX_HOME/AGENTS.md
@@ -17,13 +21,15 @@ set -e
 SYNC_CLAUDE=false
 SYNC_CODEX=false
 CLEAN=true
+CLEAR=false
 CODEX_REF=""
 INSTALL_CODEX_GLOBAL_AGENTS=true
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
         claude)     SYNC_CLAUDE=true ;;
         codex)      SYNC_CODEX=true ;;
+        clear)      CLEAR=true ;;
         --no-clean) CLEAN=false ;;
         --codex-ref)
             shift
@@ -72,6 +78,32 @@ CODEX_MARKETPLACE="borda-ai-rig"
 CODEX_MARKETPLACE_SOURCE="Borda/AI-Rig"
 CODEX_PLUGIN="codex-rig@${CODEX_MARKETPLACE}"
 
+if $CLEAR; then
+    if $SYNC_CLAUDE; then
+        echo "Clearing Claude marketplace plugins..."
+        for p in "${PLUGINS[@]}"; do
+            claude plugin uninstall "${p}@${MARKETPLACE}" 2>/dev/null && echo "  ✓ uninstalled ${p}" || echo "  – ${p} not installed, skipping"
+        done
+    fi
+    if $SYNC_CODEX; then
+        echo "Clearing Codex Rig..."
+        if command -v codex >/dev/null 2>&1; then
+            codex plugin remove "$CODEX_PLUGIN" 2>/dev/null && echo "  ✓ removed $CODEX_PLUGIN" || echo "  – $CODEX_PLUGIN not installed, skipping"
+        else
+            echo "  – codex CLI not found, skipping plugin removal"
+        fi
+        # strip the managed AGENTS.md block via the local script — no --source needed for --remove
+        REMOVE_SCRIPT="$PROJECT_DIR/plugins/codex-rig/scripts/install_global_agents.py"
+        if command -v python3 >/dev/null 2>&1 && [[ -f "$REMOVE_SCRIPT" ]]; then
+            python3 "$REMOVE_SCRIPT" --remove --codex-home "${CODEX_HOME:-$HOME/.codex}"
+        else
+            echo "  – cannot strip \$CODEX_HOME/AGENTS.md (python3 or script missing)"
+        fi
+    fi
+    echo "✓ Cleared (Standard: plugins uninstalled; marketplace registrations + external plugins left in place)"
+    exit 0
+fi
+
 print_claude_plugin_identity() {
     local plugin_id="$1"
     local identity