feat(skills): add agent workflow controls

Author: BramVR

AGENTS.MD

@@ -71,6 +71,8 @@ Codex CLI output: avoid Markdown tables by default; they render poorly there. Us
 ## Runtime Safety
 
 - zsh: don't use `status` as a variable.
+- Recovery may gracefully stop or terminate only a verified task-owned process after recording its PID, command, parent, start time, and task evidence. Never kill an unknown, shared, or user-owned application process as incidental recovery.
+- Never move, delete, rewrite, or reset another application's caches, databases, configuration, profiles, sessions, keychains, or credential state without Bram's explicit approval for those exact targets. Use read-only diagnosis and task-local retries first; if those fail, preserve evidence and stop for direction.
 - Passwords/secrets: check `~/.profile` first. `op`/1Password CLI is last resort, must always run inside `tmux`, never directly.
 - NEVER run `op` directly in a normal shell. No exceptions. This includes harmless-looking diagnostics: no direct `op --version`, `op account list`, `op whoami`, `op vault list`, `op item list`, `op read`, or `op item get`.
 - `tmux` is necessary for `op`, but not sufficient: do not spam 1Password. No parallel `op`; no repeated probe sessions; no broad vault/item enumeration; no trial-and-error secret discovery.

CHANGELOG.md

@@ -4,6 +4,15 @@ summary: Timeline of guardrail helper changes mirrored from Sweetistics and rela
 
 # Changelog
 
+## 2026-08-12 — Agent Performance Audit
+- Added a reusable personal skill and deterministic CLI for repository-scoped Codex-history audits with separate Claude activity coverage, injected-prompt exclusion, correction and shell-tool-output denominators, cumulative-delta per-turn token accounting, baseline comparisons, redacted causal notes, privacy validation, and self-contained local HTML reports.
+
+## 2026-08-12 — External-State Recovery Boundary
+- Added a global recovery rule plus PatchProof, 1Password, and maintainer-loop guidance: terminate only verified task-owned processes, preserve diagnostics, never mutate another application's caches/databases/configuration/credential state without exact approval, and stop after documented task-local recovery fails.
+
+## 2026-08-12 — Maintainer Loop Structured Monitoring
+- Replaced repeated worker transcript polling with batched cursor-based waits, a compact current-state ledger, explicit 5/15/30/60-minute backoff, targeted raw-history recovery, and counters for verifying heartbeat and automation overhead reductions.
+
 ## 2026-07-22 — Autoreview From Canonical Source
 - Replaced the vendored `autoreview` skill with the canonical `openclaw/agent-skills` copy at `c4ab5e7` (helper 2,485 -> 12,001 lines), including its scripts, test suite, fixtures, and the skill-level `AGENTS.md` sync rule.
 - Gains TruffleHog secret scanning over the reviewed diff, a Scope Governor that classifies findings as in-scope blocker / follow-up / stop-and-escalate, oversized-bundle handling, release-branch rules, and Codex `gpt-5.6-sol` with an access-only fallback to `gpt-5.6-terra`.

skills/agent-performance-audit/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: agent-performance-audit
+description: "Audit local Codex agent histories for a repository, record separate Claude activity coverage, compare correction and efficiency trends, and generate privacy-minimized JSON plus self-contained HTML. Use for Theo-style agent audits, monthly agent-performance checks, or post-issue-batch workflow reviews."
+---
+
+# Agent Performance Audit
+
+Produce comparable Codex behavioral audits without copying raw conversations
+into the report. Claude history contributes separate coverage counts, not the
+Codex behavioral metrics. Keep source histories local and read-only.
+
+## Run
+
+1. Resolve the repository, an exact lowercase marker matching its repository
+   basename, and an inclusive date window. The marker is a sanity check;
+   histories are scoped by the target's canonical checkout path or normalized
+   remote identity. Use a monthly window or the period since the previous major
+   issue batch. Codex turns are included by task-start date and retained whole
+   across date boundaries.
+2. Use the task visualization directory for output. Identify the current audit
+   task's session ID when available and pass `--exclude-session`; this validates
+   that it contains a detectable audit turn but never drops the session's other
+   turns. The script also detects audit turns by invocation/request markers.
+3. Run:
+
+   ```bash
+   python3 <skill-dir>/scripts/audit_agent_history.py \
+     --repo /absolute/repository/path \
+     --marker repository-name \
+     --since YYYY-MM-DD \
+     --until YYYY-MM-DD \
+     --output-dir /absolute/visualization/path
+   ```
+
+4. For a comparison, pass the previous generated JSON with `--baseline`.
+5. Inspect aggregate results. Read raw surrounding history only for a small
+   number of representative causal cases; keep those notes short and abstract.
+   Never paste full messages, commands, outputs, or hidden instructions.
+6. If causal notes materially improve the report, write a JSON array with
+   `title`, `cause`, `control`, and `status`, then rerun with `--case-notes`.
+7. Deliver the generated HTML link. Keep JSON beside it as reproducible evidence.
+
+Run `python3 <skill-dir>/scripts/audit_agent_history.py --help` for all flags.
+
+## Privacy Contract
+
+- Emit aggregate counts, rates, tool categories, duration percentiles,
+  category-only correction summaries, and concise causal notes only.
+- Exclude injected AGENTS/skill/plugin/browser/environment/automation messages,
+  explicit audit sessions, session IDs, source paths, cwd values, raw tool
+  inputs/outputs, full user messages, and result excerpts.
+- Redact URLs, emails, home paths, UUIDs, secret-shaped strings, and long hashes.
+- Keep the HTML self-contained, script-free, under 512 KB, and free of local
+  filesystem paths or private links.
+- Do not upload or publish the report unless Bram explicitly requests it.
+
+## Interpretation
+
+- Correction detection favors precision and misses polite dissatisfaction.
+- Nonzero shell output is not automatically agent error; separate test/build
+  failures, probes, invocation errors, missing paths/modules, and permissions.
+  Batched shell wrappers without per-command result envelopes are reported as
+  uncovered and excluded from per-shell-output denominators.
+- Token counts are model-accounted usage, not unique text or a billing estimate.
+- Compare schema-2 datasets produced by this script for the same repository and
+  matching-duration windows. Schema 2 derives each turn from cumulative Codex
+  token deltas. Do not compare it directly with older one-off or schema-1 data.
+- A local HTML report is diagnostic evidence, not a public performance claim.
+
+## Cadence
+
+Run monthly or after a major issue batch. Create a recurring automation only
+when Bram explicitly requests scheduling.

skills/agent-performance-audit/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Agent Performance Audit"
+  short_description: "Audit agent history with privacy-safe reports"
+  default_prompt: "Use $agent-performance-audit to compare recent repository Codex performance with the previous audit and report Claude activity coverage separately."