v0.2.1: polish local diagnostics and audit UX

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-quota-optimizer",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "A zero-friction Codex usage governor with task-aware routing, soft budgets, focused context, local audits, and layered verification.",
   "author": {
     "name": "Daniel Chen",

.github/workflows/python-cli-tests.yml

@@ -27,3 +27,4 @@ jobs:
           python3 skills/codex-quota-optimizer/scripts/cqo.py status
           python3 skills/codex-quota-optimizer/scripts/cqo.py audit --note ci-smoke
           python3 skills/codex-quota-optimizer/scripts/cqo.py history --limit 1
+          python3 skills/codex-quota-optimizer/scripts/cqo.py doctor

CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to this project will be documented here.
 
+## [0.2.1] - 2026-09-21
+
+### Added
+- `cqo doctor` for zero-network local installation diagnostics.
+- Doctor checks Python compatibility, Skill presence, journal writability, Git availability, CLI PATH visibility, and active-session state.
+
+### Changed
+- `cqo audit` output now separates observed local facts from CQO policy guarantees for clearer, more honest reporting.
+- README now reflects successful HOL Codex Plugin Catalog listing.
+
 ## [0.2.0] - 2026-09-20
 
 ### Added

README.md

@@ -58,7 +58,7 @@ v0.2 turns the original Skill policy into a lightweight usage governor while kee
 | **Soft Session Budget** | Suggests discovery, reasoning, verification and subagent scope without blocking execution |
 | **Local Usage Journal** | Stores task-level metadata locally under `~/.cqo`; no telemetry and no private account scraping |
 | **Usage Audit** | Records local change surface and CQO policy guardrails without inventing token-savings percentages |
-| **`cqo` CLI** | Optional `start / status / audit / history` inspection layer; Codex does not depend on it |
+| **`cqo` CLI** | Optional `start / status / audit / history / doctor` inspection layer; Codex does not depend on it |
 
 CQO itself adds **no automatic model call, no network request, no blocking budget gate, and no automatic subagent**. If correctness requires more context or verification than the suggested budget, Codex should simply continue.
 
@@ -293,6 +293,7 @@ cqo start "Fix the checkout bug" --mode economy
 cqo status
 cqo audit
 cqo history
+cqo doctor
 ```
 
 It uses the Python standard library only, performs no network requests, and writes task-level state to `~/.cqo` (or `CQO_HOME`).
@@ -303,6 +304,8 @@ If the `cqo` shortcut is not installed, run:
 python ~/.agents/skills/codex-quota-optimizer/scripts/cqo.py status
 ```
 
+Run `cqo doctor` any time to check Python compatibility, Skill installation, local journal writability, Git availability, and whether the `cqo` shortcut is on PATH — with zero network checks.
+
 The repository snapshot and change-scope scripts are also local-only and dependency-light.
 
 ---
@@ -365,7 +368,7 @@ codex-quota-optimizer/
 - [x] End-of-task **Usage Audit** with honest task-level local observations
 - [ ] Framework-aware focused-test discovery
 - [x] Plugin packaging for dual Skill / Plugin distribution
-- [ ] HOL Codex Plugin Catalog listing
+- [x] HOL Codex Plugin Catalog listing
 - [x] One-line Skills CLI installation
 - [ ] Benchmark suite comparing default and optimized workflows
 

README.zh-CN.md

@@ -58,7 +58,7 @@ v0.2 在原有 Skill 策略上增加了一个轻量的 Usage Governor，但不
 | **Soft Session Budget** | 给探索、推理、验证、Subagent 提供建议范围，但绝不阻塞任务 |
 | **Local Usage Journal** | 只在本地 `~/.cqo` 保存任务级信息；无 Telemetry、不抓私人账户数据 |
 | **Usage Audit** | 记录本地改动面和 CQO 的策略约束，不虚构 Token 节省比例 |
-| **`cqo` CLI** | 可选的 `start / status / audit / history` 查看层；Codex 不依赖它运行 |
+| **`cqo` CLI** | 可选的 `start / status / audit / history / doctor` 查看层；Codex 不依赖它运行 |
 
 CQO 自身不会额外发起模型调用、不会访问网络、不会设置阻塞式 Budget Gate，也不会自动拉起 Subagent。只要正确性需要更多上下文或验证，Codex 应直接继续完成任务。
 
@@ -295,6 +295,7 @@ cqo start "修复结算页 Bug" --mode economy
 cqo status
 cqo audit
 cqo history
+cqo doctor
 ```
 
 它只使用 Python 标准库，不访问网络，任务级状态保存在 `~/.cqo`（或 `CQO_HOME`）。
@@ -305,6 +306,8 @@ cqo history
 python ~/.agents/skills/codex-quota-optimizer/scripts/cqo.py status
 ```
 
+你可以随时运行 `cqo doctor` 检查 Python 版本、Skill 安装、本地 Journal 写入权限、Git 是否可用，以及 `cqo` 快捷命令是否已进入 PATH；整个检查过程 0 网络请求。
+
 Repository Snapshot 与 Change Scope 两个脚本同样只在本地运行，不上传项目数据。
 
 ---
@@ -367,7 +370,7 @@ codex-quota-optimizer/
 - [x] **Usage Audit**：任务结束输出诚实的本地任务级观察
 - [ ] 自动识别不同框架最合适的定向测试
 - [x] Plugin 打包：同时支持 Skill 直装与 Plugin 分发
-- [ ] HOL Codex Plugin Catalog 收录
+- [x] HOL Codex Plugin Catalog 收录
 - [x] Skills CLI 一行命令安装
 - [ ] Benchmark：对比默认工作流和优化工作流
 

plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "codex-quota-optimizer",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "A zero-friction Codex usage governor with task-aware routing, soft budgets, focused context, local audits, and layered verification.",
   "author": {
     "name": "Daniel Chen",

skills/codex-quota-optimizer/scripts/cqo.py

@@ -10,14 +10,15 @@
 import argparse
 import json
 import os
+import shutil
 import subprocess
 import sys
 import uuid
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
 
-VERSION = "0.2.0"
+VERSION = "0.2.1"
 
 HIGH_RISK_TERMS = {
     "security", "auth", "authentication", "authorization", "permission",
@@ -386,8 +387,18 @@ def print_audit(audit: dict[str, Any] | None) -> None:
     repo = audit["repo_at_audit"]
     print(f"CQO audit {audit['id']} · completed")
     print(f"Task: {audit['size']} · Risk: {audit['risk']} · Mode: {audit['mode']}")
-    print(f"Current repository change surface: {repo['changed_file_count']} file(s)")
-    print("CQO overhead: 0 network requests · 0 blocking gates · 0 automatic model calls")
+    print("Observed:")
+    print(f"- Local repository change surface: {repo['changed_file_count']} file(s)")
+    if repo.get("branch"):
+        print(f"- Branch: {repo['branch']}")
+    print("CQO guarantees:")
+    print("- No forced repository-wide scan")
+    print("- No forced full test suite")
+    print("- No automatic subagent")
+    print("- No automatic model escalation")
+    print("- 0 CQO network requests · 0 blocking gates · 0 automatic model calls")
+    if audit.get("note"):
+        print(f"Note: {audit['note']}")
     print(f"Recorded locally in {history_path()}")
 
 
@@ -406,6 +417,91 @@ def print_history(items: list[dict[str, Any]]) -> None:
         )
 
 
+
+def doctor_report() -> dict[str, Any]:
+    """Inspect the local CQO setup without network access."""
+    skill_root = Path(__file__).resolve().parents[1]
+    skill_file = skill_root / "SKILL.md"
+
+    home_ok = False
+    home_error: str | None = None
+    try:
+        ensure_home()
+        probe = cqo_home() / ".doctor-write-test"
+        probe.write_text("ok\n", encoding="utf-8")
+        probe.unlink()
+        home_ok = True
+    except OSError as exc:
+        home_error = str(exc)
+
+    python_ok = sys.version_info >= (3, 10)
+    cli_path = shutil.which("cqo")
+    git_path = shutil.which("git")
+
+    required_ok = python_ok and skill_file.is_file() and home_ok
+    return {
+        "version": VERSION,
+        "ok": required_ok,
+        "python": {
+            "version": ".".join(map(str, sys.version_info[:3])),
+            "ok": python_ok,
+            "required": ">=3.10",
+        },
+        "skill": {
+            "root": str(skill_root),
+            "skill_md": str(skill_file),
+            "ok": skill_file.is_file(),
+        },
+        "journal": {
+            "home": str(cqo_home()),
+            "writable": home_ok,
+            "error": home_error,
+        },
+        "git": {
+            "path": git_path,
+            "available": bool(git_path),
+            "required": False,
+        },
+        "cli": {
+            "path": cli_path,
+            "on_path": bool(cli_path),
+            "required": False,
+        },
+        "active_session": bool(read_current()),
+        "network_checks": 0,
+    }
+
+
+def print_doctor(report: dict[str, Any]) -> None:
+    mark = lambda ok: "OK" if ok else "WARN"
+    print(f"CQO doctor · v{report['version']}")
+    print(
+        f"[{mark(report['python']['ok'])}] Python "
+        f"{report['python']['version']} (required {report['python']['required']})"
+    )
+    print(
+        f"[{mark(report['skill']['ok'])}] Skill "
+        f"{report['skill']['skill_md']}"
+    )
+    print(
+        f"[{mark(report['journal']['writable'])}] Local journal "
+        f"{report['journal']['home']}"
+    )
+    print(
+        f"[{mark(report['git']['available'])}] Git "
+        f"{report['git']['path'] or 'not found'} (optional for CLI)"
+    )
+    print(
+        f"[{mark(report['cli']['on_path'])}] cqo shortcut "
+        f"{report['cli']['path'] or 'not on PATH'} (optional)"
+    )
+    print(
+        "Zero-friction check: 0 network requests · "
+        "0 model calls · 0 blocking gates"
+    )
+    print("Required setup: ready" if report["ok"] else "Required setup: needs attention")
+
+
 def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         prog="cqo",
@@ -448,6 +544,12 @@ def build_parser() -> argparse.ArgumentParser:
     history.add_argument("--limit", type=int, default=10)
     history.add_argument("--json", action="store_true")
 
+    doctor = sub.add_parser(
+        "doctor",
+        help="Check local CQO installation and optional CLI setup.",
+    )
+    doctor.add_argument("--json", action="store_true")
+
     return parser
 
 
@@ -483,6 +585,14 @@ def main(argv: list[str] | None = None) -> int:
             print_history(items)
         return 0
 
+    if args.command == "doctor":
+        report = doctor_report()
+        if args.json:
+            print_json(report)
+        else:
+            print_doctor(report)
+        return 0 if report["ok"] else 1
+
     return 2
 
 

tests/test_cqo.py

@@ -63,6 +63,16 @@ def test_local_session_lifecycle(self):
                 self.assertEqual(len(history), 1)
                 self.assertEqual(history[0]["note"], "unit-test")
 
+    def test_doctor_reports_required_setup(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            with patch.dict(os.environ, {"CQO_HOME": tmp}, clear=False):
+                report = cqo.doctor_report()
+                self.assertTrue(report["python"]["ok"])
+                self.assertTrue(report["skill"]["ok"])
+                self.assertTrue(report["journal"]["writable"])
+                self.assertEqual(report["network_checks"], 0)
+                self.assertTrue(report["ok"])
+
 
 if __name__ == "__main__":
     unittest.main()