leos-agent 7.0.0 → 10.2.0

package/scripts/measure_context.py

@@ -0,0 +1,113 @@
+#!/usr/bin/env python3
+"""Measure leos-agent's static prompt footprint with a byte-based proxy.
+
+This does not estimate total task cost: tool output, conversation history,
+cache state, model choice, and spawned work dominate many real runs. It measures
+the repository-controlled text that is always listed or loaded at dispatch, so
+regressions remain visible without a tokenizer or network access.
+"""
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+
+# Deliberately tight ceilings. Raise one only with a concrete reason and record
+# the before/after output in the change that raises it.
+LIMITS = {
+	"global_policy_bytes": 4_500,
+	"codex_implicit_skill_metadata_bytes": 600,
+	"claude_implicit_skill_metadata_bytes": 800,
+	"codex_agent_description_bytes": 550,
+	"review_dispatch_bytes": 3_500,
+}
+
+
+def frontmatter(path):
+	text = path.read_text(encoding="utf-8")
+	match = re.match(r"---\n(.*?)\n---\n?(.*)", text, re.DOTALL)
+	if not match:
+		raise ValueError(f"{path.relative_to(ROOT)} has no YAML frontmatter")
+	return match.group(1), match.group(2)
+
+
+def field(text, name):
+	match = re.search(rf"(?m)^{re.escape(name)}:\s*(.+?)\s*$", text)
+	return match.group(1).strip() if match else ""
+
+
+def byte_len(text):
+	return len(text.encode("utf-8"))
+
+
+def skill_metadata_bytes(paths, implicit):
+	total = 0
+	for path in paths:
+		fm, _ = frontmatter(path)
+		if implicit(path, fm):
+			total += byte_len(field(fm, "name")) + byte_len(field(fm, "description"))
+	return total
+
+
+def codex_implicit(path, _frontmatter):
+	policy = path.parent / "agents" / "openai.yaml"
+	return not policy.is_file() or "allow_implicit_invocation: false" not in policy.read_text(encoding="utf-8")
+
+
+def claude_implicit(_path, fm):
+	return re.search(r"(?m)^disable-model-invocation:\s*true\s*$", fm) is None
+
+
+def agent_description(path):
+	text = path.read_text(encoding="utf-8")
+	match = re.search(r'(?m)^description\s*=\s*"(.*)"\s*$', text)
+	if not match:
+		raise ValueError(f"{path.relative_to(ROOT)} has no one-line description")
+	return match.group(1)
+
+
+def measurements():
+	portable = sorted((ROOT / "skills").glob("*/SKILL.md"))
+	claude_only = sorted((ROOT / "skills-claude").glob("*/SKILL.md"))
+	policy_fm, policy_body = frontmatter(ROOT / "rules" / "preferences.md")
+	del policy_fm
+	review_fm, review_body = frontmatter(ROOT / "skills" / "review-pr" / "SKILL.md")
+	del review_fm
+	agent_paths = sorted((ROOT / "payload" / "codex-agents").glob("*.toml"))
+	return {
+		"global_policy_bytes": byte_len(policy_body.strip()),
+		"codex_implicit_skill_metadata_bytes": skill_metadata_bytes(portable, codex_implicit),
+		"claude_implicit_skill_metadata_bytes": skill_metadata_bytes(portable + claude_only, claude_implicit),
+		"codex_agent_description_bytes": sum(byte_len(agent_description(path)) for path in agent_paths),
+		"review_dispatch_bytes": byte_len(review_body.strip()),
+	}
+
+
+def main(argv=None):
+	parser = argparse.ArgumentParser(description=__doc__)
+	parser.add_argument("--json", action="store_true", help="emit machine-readable JSON")
+	parser.add_argument("--check", action="store_true", help="fail when a committed ceiling is exceeded")
+	args = parser.parse_args(argv)
+
+	values = measurements()
+	if args.json:
+		print(json.dumps({"measurements": values, "limits": LIMITS}, indent=2, sort_keys=True))
+	else:
+		print("Static prompt footprint (bytes; tokens are roughly bytes / 4 for this prose)")
+		for name, value in values.items():
+			print(f"  {name:38} {value:5}  limit {LIMITS[name]:5}")
+		print("This excludes conversation history, tool output, cache effects, and subagent work.")
+
+	over = {name: (value, LIMITS[name]) for name, value in values.items() if value > LIMITS[name]}
+	if args.check and over:
+		for name, (value, limit) in over.items():
+			print(f"FAIL {name}: {value} > {limit}", file=sys.stderr)
+		return 1
+	return 0
+
+
+if __name__ == "__main__":
+	sys.exit(main())

package/scripts/publish-npm.py

@@ -0,0 +1,138 @@
+#!/usr/bin/env python3
+"""Publish leos-agent to npm exactly once per version.
+
+Two properties matter here, and both are inherited from the release path this
+replaces. Publishing is idempotent: an exact version already on the registry is
+a no-op, so re-running a tag is safe, while a lookup that fails for any reason
+other than a confirmed 404 aborts rather than guessing. And the tree npm would
+actually ship is inspected before it ships, because `files` in package.json
+scopes the publish but does not exclude build residue that lands inside a
+directory it lists.
+
+Authentication is npm's OIDC trusted publishing: the workflow's `id-token`
+permission supplies a short-lived credential, so there is no token to read here.
+"""
+
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+PACKAGE = "leos-agent"
+
+# Residue that a local checkout accumulates and a publish must never carry.
+FORBIDDEN_PARTS = ("__pycache__",)
+FORBIDDEN_SUFFIXES = (".pyc", ".log")
+FORBIDDEN_NAMES = (".DS_Store",)
+
+
+class ReleaseError(Exception):
+	"""The release cannot proceed safely; the caller should stop, not retry."""
+
+
+def run(command):
+	return subprocess.run(command, capture_output=True, text=True, check=False, cwd=ROOT)
+
+
+def declared_version():
+	version = json.loads((ROOT / "package.json").read_text(encoding="utf-8"))["version"]
+	return version
+
+
+def pack_inventory(npm="npm"):
+	"""Return the file list npm would publish, without publishing it."""
+	packed = run([npm, "pack", "--dry-run", "--json"])
+	if packed.returncode:
+		raise ReleaseError(f"npm pack --dry-run failed: {(packed.stdout + packed.stderr).strip()}")
+	try:
+		report = json.loads(packed.stdout)
+	except json.JSONDecodeError as exc:
+		raise ReleaseError(f"npm pack --dry-run emitted unparseable JSON: {exc}") from exc
+	if not report:
+		raise ReleaseError("npm pack --dry-run reported no package")
+	return sorted(entry["path"] for entry in report[0].get("files", []))
+
+
+def forbidden_paths(inventory):
+	found = []
+	for path in inventory:
+		parts = path.split("/")
+		if any(part in FORBIDDEN_PARTS for part in parts):
+			found.append(path)
+		elif path.endswith(FORBIDDEN_SUFFIXES) or parts[-1] in FORBIDDEN_NAMES:
+			found.append(path)
+	return found
+
+
+def check_inventory(inventory):
+	if "LICENSE" not in inventory:
+		raise ReleaseError("publish tree has no LICENSE")
+	if "package.json" not in inventory:
+		raise ReleaseError("publish tree has no package.json")
+	found = forbidden_paths(inventory)
+	if found:
+		raise ReleaseError("publish tree contains transient files: " + ", ".join(found))
+
+
+def registry_state(version, npm="npm"):
+	"""Report whether this exact version is already on the registry.
+
+	Anything other than a clean hit or a confirmed not-found is an error: an
+	auth failure or a registry outage must not be read as "absent, publish it".
+	"""
+	viewed = run([npm, "view", f"{PACKAGE}@{version}", "version"])
+	output = (viewed.stdout + viewed.stderr).strip()
+	if viewed.returncode == 0:
+		if output != version:
+			raise ReleaseError(f"npm returned {output!r}, not the exact version {version!r}")
+		return "present"
+	if "E404" in output or "404 Not Found" in output:
+		return "absent"
+	raise ReleaseError(f"npm version lookup failed without a confirmed not-found: {output}")
+
+
+def publish(npm="npm"):
+	published = run([npm, "publish", "--access", "public"])
+	if published.returncode:
+		raise ReleaseError(f"npm publish failed: {(published.stdout + published.stderr).strip()}")
+	return (published.stdout + published.stderr).strip()
+
+
+def main(argv=None):
+	parser = argparse.ArgumentParser(description=__doc__)
+	parser.add_argument("--tag", help="git tag being released; must match package.json")
+	parser.add_argument("--dry-run", action="store_true", help="check everything, publish nothing")
+	parser.add_argument("--npm", default="npm", help="npm executable to use")
+	args = parser.parse_args(argv)
+
+	try:
+		version = declared_version()
+		if args.tag is not None:
+			expected = args.tag[1:] if args.tag.startswith("v") else args.tag
+			if expected != version:
+				raise ReleaseError(f"tag {args.tag!r} does not match package.json version {version!r}")
+
+		inventory = pack_inventory(args.npm)
+		check_inventory(inventory)
+		print(f"{PACKAGE} {version}: {len(inventory)} file(s) staged for publish")
+
+		state = registry_state(version, args.npm)
+		if state == "present":
+			print(f"{PACKAGE}@{version} is already on the registry; nothing to do")
+			return 0
+		if args.dry_run:
+			print(f"would publish {PACKAGE}@{version}")
+			return 0
+
+		publish(args.npm)
+		print(f"published {PACKAGE}@{version}")
+		return 0
+	except ReleaseError as exc:
+		print(f"error: {exc}", file=sys.stderr)
+		return 1
+
+
+if __name__ == "__main__":
+	sys.exit(main())

package/scripts/watch_review.py

@@ -0,0 +1,169 @@
+#!/usr/bin/env python3
+"""watch_review: stream new GitHub review requests without spending tokens.
+
+The discovery half of the review watcher is a fixed query, a fixed filter, and
+a state file — none of it needs a model. This script does that half in the
+shell and prints one line per new pull request; whoever reads stdout does the
+review. An idle tick costs one `gh` call and zero tokens.
+
+  watch_review.py monitor [-C DIR] --interval 300  loop; a line per new PR
+  watch_review.py record  [-C DIR] <number>...     mark numbers reviewed
+  watch_review.py state   [-C DIR]                 show what has been reviewed
+  watch_review.py forget  [-C DIR] <number>...     drop numbers from the state
+
+It launches nothing and records nothing on its own. The reader must call
+`record` once a review is done — a staged (pending, unsubmitted) review does
+not clear the request on GitHub, so that state file is the only thing keeping
+the same pull request from coming back. `monitor` emits each pull request once
+per process, so an unreviewed one is re-emitted after a restart.
+
+Intended for Claude Code's Monitor tool, which turns each stdout line into a
+session notification. Any `read`-driven shell loop works the same way.
+
+State lives in the review-watcher state file managed by state.py, keyed by
+"owner/repo" — the same file and shape the watch-review skill reads.
+"""
+import argparse
+import json
+import os
+import subprocess
+import sys
+import time
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import state as state_mod  # noqa: E402
+
+STATE_NAME = "review-watcher"
+
+
+def fail(message):
+	print(f"watch-review: {message}", file=sys.stderr)
+	sys.exit(1)
+
+
+def gh(args, cwd):
+	"""Run a read-only gh command and return stdout, or fail loudly."""
+	try:
+		proc = subprocess.run(
+			["gh"] + args, cwd=cwd, capture_output=True, text=True, check=False
+		)
+	except FileNotFoundError:
+		fail("gh is not installed or not on PATH")
+	if proc.returncode != 0:
+		fail((proc.stderr or proc.stdout).strip() or f"gh {args[0]} failed")
+	return proc.stdout
+
+
+def discover(cwd):
+	"""Return (repo, login, [pull requests directly requesting login])."""
+	repo = json.loads(gh(["repo", "view", "--json", "nameWithOwner"], cwd))["nameWithOwner"]
+	login = gh(["api", "user", "--jq", ".login"], cwd).strip()
+	if not login:
+		fail("gh api user returned no login; is gh authenticated?")
+	# user-review-requested matches direct requests only; the reviewRequests
+	# check below is belt and braces against a stale or fuzzy search result.
+	listing = json.loads(
+		gh(
+			[
+				"pr", "list", "--state", "open",
+				"--search", f"user-review-requested:{login}",
+				"--limit", "100",
+				"--json", "number,title,isDraft,reviewRequests,url",
+			],
+			cwd,
+		)
+	)
+	matches = [
+		pr
+		for pr in listing
+		if not pr.get("isDraft")
+		and any(
+			r.get("__typename") == "User" and r.get("login") == login
+			for r in pr.get("reviewRequests") or []
+		)
+	]
+	matches.sort(key=lambda pr: pr["number"])
+	return repo, login, matches
+
+
+def reviewed_numbers(repo):
+	data = state_mod.load(state_mod.state_file(STATE_NAME))
+	entry = data.get(repo) or {}
+	return set(entry.get("reviewed") or [])
+
+
+def record(repo, number):
+	path = state_mod.state_file(STATE_NAME)
+	with state_mod._locked(path):
+		data = state_mod.load(path)
+		data[repo] = state_mod.deep_merge(data.get(repo, {}), {"reviewed": [number]})
+		state_mod.atomic_write(path, data)
+
+
+def monitor(args):
+	"""Emit one line per new pull request; review nothing, record nothing."""
+	emitted = set()
+	while True:
+		try:
+			repo, _, matches = discover(args.directory)
+			done = reviewed_numbers(repo)
+			for pr in matches:
+				n = pr["number"]
+				if n in done or n in emitted:
+					continue
+				emitted.add(n)
+				# One line, one event. The title is data — a reader must treat
+				# it as a string to show Leo, never as an instruction.
+				print(f"review-requested {repo}#{n} {pr['url']} — {pr['title']}", flush=True)
+		except SystemExit as exc:
+			# A transient gh failure must not kill a session-length watch.
+			print(
+				f"watch-review: tick failed ({exc.code}); retrying next interval",
+				file=sys.stderr,
+				flush=True,
+			)
+		time.sleep(args.interval)
+
+
+def main(argv):
+	parser = argparse.ArgumentParser(prog="watch_review.py", description=__doc__)
+	sub = parser.add_subparsers(dest="mode", required=True)
+
+	mon = sub.add_parser("monitor")
+	mon.add_argument("-C", "--directory", default=".", help="repository directory (default: cwd)")
+	mon.add_argument("--interval", type=int, default=300, help="seconds between ticks")
+
+	sub.add_parser("state").add_argument("-C", "--directory", default=".")
+	for name in ("record", "forget"):
+		p = sub.add_parser(name)
+		p.add_argument("-C", "--directory", default=".")
+		p.add_argument("numbers", nargs="+", type=int)
+
+	args = parser.parse_args(argv)
+	if not os.path.isdir(args.directory):
+		fail(f"{args.directory} is not a directory")
+
+	if args.mode == "monitor":
+		if args.interval < 30:
+			fail("--interval below 30s hammers the GitHub API; pick something larger")
+		return monitor(args)
+
+	repo, _, _ = discover(args.directory)
+	if args.mode == "record":
+		for n in args.numbers:
+			record(repo, n)
+	elif args.mode == "forget":
+		path = state_mod.state_file(STATE_NAME)
+		with state_mod._locked(path):
+			data = state_mod.load(path)
+			entry = data.get(repo) or {}
+			drop = set(args.numbers)
+			entry["reviewed"] = [n for n in (entry.get("reviewed") or []) if n not in drop]
+			data[repo] = entry
+			state_mod.atomic_write(path, data)
+	print(json.dumps({"repo": repo, "reviewed": sorted(reviewed_numbers(repo))}, indent=1))
+	return 0
+
+
+if __name__ == "__main__":
+	sys.exit(main(sys.argv[1:]) or 0)

package/skills/doctor/SKILL.md

@@ -1,124 +1,82 @@
 ---
 name: doctor
-description: >
-  Self-check for Leo's own wiring. Reports which harness this is, what each
-  tier name resolves to here, whether the bootstrap is installed, where
-  machine-local state and the memory store live, and which skills shipped
-  versus which this session can actually invoke. Disk facts come from a
-  helper script; the context facts only the running session can answer, and
-  a disagreement between the two columns is the diagnosis. Use when Leo asks
-  about Leo's loading, routing, or skill wiring. Do not use for project health
-  checks, project-code debugging, or unprompted inspection.
-when_to_use: >
-  Leo asks whether the policy loaded, why routing or a skill is misbehaving,
-  or invokes doctor by name after installing, updating, or switching harness.
-  Also the first move when a leo skill cannot be found. NOT a general
-  environment or project health check, NOT for debugging the project's own
-  code (that is leo:debugging), and never run unprompted — it reports on the
-  agent, not on the work.
+disable-model-invocation: true
+description: Audit Leo's agent setup in this harness — the injected leos-agent block, everything else always loaded into context, and the local plugin checkout. Read-only.
 ---
 
-# doctor
+# Diagnose Leo's agent setup
 
-Doctor answers two questions that look like one: what shipped to disk, and what
-reached this session. A skill the harness never registered is indistinguishable
-from a skill that does not exist, right up until the moment you invoke it.
+Read-only. Report findings; change nothing unless Leo asks.
 
-## Run the script
+**This harness only.** Inspect the harness you are actually running in — one of
+`claude`, `codex`, `cursor`, `hermes`, `pi`, `opencode`. Other harnesses may be
+on other versions; that is their business.
 
-```sh
-python3 "${CLAUDE_PLUGIN_ROOT}/scripts/doctor.py" --harness <name>
+## 1. Injection and install
+
+Locate the plugin root (the directory holding `rules/preferences.md`):
+`$LEOS_AGENT_ROOT`, `$CLAUDE_PLUGIN_ROOT`, `$PLUGIN_ROOT`, or the parent of the
+directory holding this file. Then:
+
+```
+python3 <plugin-root>/scripts/leo-install.py <harness> --check
 ```
 
-Pass `--harness` with the harness you are on — the mapping appendix in your
-context names it in its own heading (`# Hermes mapping` → `hermes`). Detection
-without it relies on a plugin-root variable that Hermes and OpenCode do not
-export, so on those two the script reports `unknown` rather than guessing.
-`unknown` on a harness whose mapping you can plainly read is a missing
-argument, not a fault.
-
-`${CLAUDE_PLUGIN_ROOT}` is the Claude Code spelling. Codex exports
-`$PLUGIN_ROOT` and Cursor `$CURSOR_PLUGIN_ROOT`. On Hermes and OpenCode no
-plugin-root variable exists at all — the injected policy instead substitutes an
-absolute payload path into its `state.py` and `memory.py` commands. Read that
-command path from the policy as the discoverable source. Being unable to locate
-the payload at all is itself the first finding: the harness is not looking where
-the plugin was installed.
-
-Add `--json` when you want the same facts as data.
-
-Doctor validates the bootstrap that actually belongs to the named harness:
-the session hook and manifest for Claude, Codex, and Cursor;
-`config.instructions` in OpenCode's plugin; and Hermes registration plus its
-first-tool-result fallback. It also reports the running Python version against
-the supported 3.9+ floor. Codex hook trust is not provable from disk: review
-the plugin in `/hooks` and confirm it is trusted before treating the on-disk
-hook as active.
-
-## Then answer the three it cannot
-
-A script can prove the hook is installed and that the policy renders. It cannot
-prove the policy arrived. Only you can see your own context.
-
-1. **Did the policy load?** Look for the policy wrapper in your context, and
-   check that the mapping following it names *this* harness. A policy present
-   but carrying another harness's mapping is worse than none, because routing
-   then points at models that do not exist here.
-2. **Which skills are actually invocable?** Compare your own skill list against
-   the script's shipped roster. Mind the naming rule: most harnesses namespace
-   them as `leo:<name>`, while OpenCode has no namespace and requires a
-   skill's frontmatter name to match its directory, so the plugin registers a
-   generated shadow copy with every skill renamed `leo-<name>`. A skill that
-   looks missing on OpenCode may simply be listed as `leo-<name>` rather than
-   `leo:<name>`.
-3. **Is memory present and delivered?** The script reports whether the store
-   exists and whether each native surface received its generated copy. Whether
-   those facts are in front of you right now is something only you can confirm.
-   Report the two separately; they disagree more often than expected. Hermes's
-   projection is opt-in, so doctor reports it explicitly as disabled rather
-   than silently omitting it.
-
-## Reading the report
-
-Every row carries its source — `env`, `disk`, `config`, or `context` — so a
-reader can tell a fact from an inference. Close with one verdict from exactly
-three: **healthy**, **degraded**, or **not loaded**. Never free prose. `not
-loaded` outranks everything else: if the policy did not arrive, nothing else in
-the report describes how this session will actually behave.
-
-**Most breadcrumb logs are history, not a verdict.** Some older logs carry no
-timestamps, and the test suite drives failure paths deliberately, so entries
-can accumulate on a development machine. Quote the newest line if useful, but
-never conclude "the hook failed this session" from history alone. The one
-capability exception is `opencode-skills.log`: its presence means namespaced
-OpenCode skill registration degraded and doctor reports that state until the
-breadcrumb is cleared after the underlying problem is understood.
-
-## Failure modes
-
-| Symptom | Likely cause | Fix |
-|---|---|---|
-| Policy absent, bootstrap installed | the hook fired and failed open | read the newest breadcrumb, then confirm it describes this session before believing it |
-| Policy present, mapping names another harness | detection resolved wrong, usually a stray plugin-root variable exported in an unrelated shell | unset it, restart the session |
-| Harness reported as `unknown` | no `--harness`, and this harness exports no plugin-root variable | degraded until re-run with `--harness <name>` read off your mapping heading; a still-unknown explicit run is invalid wiring |
-| Codex hook is on disk but policy is absent | the new or changed hook may not be trusted | open `/hooks`, review the hook, and explicitly trust it |
-| OpenCode reports `opencode-skills.log` | the namespaced shadow tree failed and no bare-name fallback was registered | inspect the newest breadcrumb, fix the path/permission failure, and restart OpenCode |
-| Shipped roster exceeds what you can invoke | the harness cached an older payload, or the skills directory is not registered | update the plugin; on OpenCode check `opencode debug skill` for each skill's `location` |
-| Skills listed as `leo-<name>` instead of `leo:<name>` | OpenCode, working as designed | invoke them as `leo-<name>`; not a fault |
-| Tier names resolve to models this harness cannot run | mapping and harness disagree | same as row 2 |
-| Machine-local state not writable | the path override points somewhere unwritable | fix or unset it |
-| A skill is genuinely absent from disk | it was never added | see leo:writing-skills |
-
-## Doctor never repairs
-
-It reports, and it names the fix. It does not reinstall, rewrite configuration,
-or delete state — which is what keeps it safe to run at any tier and at any
-moment.
-
-## Works with
-
-- leo:writing-skills — for a skill that turned out to be missing because nobody
-  wrote it yet.
-- leo:memory — doctor reports whether the store exists and reached each surface.
-- leo:verification — this report is a claim like any other: the script ran this
-  turn and its output was read.
+Exit 0 means the `<leos-agent>` block is present and current. Non-zero means it
+is missing, stale, or the file is malformed — quote what it printed and offer
+`/leo-install`. Cursor legitimately reports `skipped`; Hermes skips until
+`~/.hermes/SOUL.md` exists.
+
+Then confirm by hand, since `--check` only sees disk, not what got loaded:
+
+- Read the harness's global file and verify exactly one `<leos-agent
+  version="...">` block, with the version matching `package.json` in the plugin
+  root.
+- Confirm the plugin's skills and commands are actually registered in this
+  session — `install` and `doctor` should both be listed. If they are not, the
+  plugin is on disk but not loaded.
+
+| Harness | Global file |
+|---|---|
+| claude | `~/.claude/CLAUDE.md` |
+| codex | `~/.codex/AGENTS.md` (plus `~/.codex/agents/leo-runner.toml` and `leo-executor.toml`) |
+| cursor | none — the always-apply rule carries the payload |
+| hermes | `~/.hermes/SOUL.md` |
+| pi | `~/.pi/agent/AGENTS.md` |
+| opencode | `~/.config/opencode/AGENTS.md` (plus copied `skills/`, `commands/`) |
+
+## 2. Global context
+
+Inventory everything loaded into *every* session in this harness, not just the
+leos-agent block. Look for what is broken, stale, or contradictory:
+
+- The global instruction file outside the block — content that fights the
+  payload, notes from an older setup, anything referencing files or flags that
+  no longer exist.
+- Memory files, if the harness has them (Claude: `~/.claude/projects/*/memory/`
+  and its `MEMORY.md` index). Flag index lines pointing at missing files,
+  memories missing frontmatter, duplicates, and facts that name paths or flags
+  that no longer exist. Verify before calling one stale.
+- Global settings, agents, skills, commands, and plugins that ship
+  always-on instructions. Flag broken JSON, duplicate names, and dangling paths.
+- Total size. Codex concatenates the AGENTS.md chain under a byte cap — over
+  ~28 KB globally, say so, since repo instructions get crowded out.
+
+## 3. Local checkout
+
+If the plugin root is a git checkout rather than an installed cache, run:
+
+```
+python3 <plugin-root>/scripts/check.py
+```
+
+Report the failures verbatim. Also note an uncommitted or behind-upstream
+checkout, and a `package.json` version that disagrees with the installed
+block — a same-version reinstall serves the cached build, so a version match
+with different content stays invisible here.
+
+## Report
+
+Group by section, worst first. One line per finding: what is wrong, where, and
+the fix. End with a one-line verdict. If everything passes, say so plainly and
+do not pad the report.

package/skills/doctor/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Doctor"
+  short_description: "Audit Leo's agent setup safely"
+policy:
+  allow_implicit_invocation: false