v0.2: zero-friction usage governor

.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "codex-quota-optimizer",
-  "version": "0.1.0",
-  "description": "Reduce avoidable Codex usage with task-aware model routing, focused context, minimal changes, and layered verification.",
+  "version": "0.2.0",
+  "description": "A zero-friction Codex usage governor with task-aware routing, soft budgets, focused context, local audits, and layered verification.",
   "author": {
     "name": "Daniel Chen",
     "url": "https://github.com/ctdaniel"
@@ -20,7 +20,7 @@
   "interface": {
     "displayName": "Codex Quota Optimizer",
     "shortDescription": "Spend less Codex allowance without sacrificing engineering quality.",
-    "longDescription": "A lightweight Codex usage governor that routes tasks to the lowest adequate model and reasoning level, limits unnecessary context, keeps patches focused, and verifies in layers.",
+    "longDescription": "A zero-friction Codex usage governor that routes tasks economically, applies soft budgets without blocking execution, keeps context and patches focused, and offers optional local task audits.",
     "developerName": "Daniel Chen",
     "category": "Developer Tools",
     "capabilities": [

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

@@ -0,0 +1,29 @@
+name: Python CLI Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: Run unit tests
+        run: python3 -m unittest discover -s tests -v
+
+      - name: CLI smoke test
+        env:
+          CQO_HOME: ${{ runner.temp }}/cqo-home
+        run: |
+          python3 skills/codex-quota-optimizer/scripts/cqo.py start Fix checkout bug --mode economy
+          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

.gitignore

@@ -7,3 +7,4 @@ node_modules/
 dist/
 build/
 coverage/
+.cqo/

CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to this project will be documented here.
 
+## [0.2.0] - 2026-09-20
+
+### Added
+- Zero-friction runtime policy: no extra model call, no network dependency, no blocking budget gate, and no automatic subagents from CQO itself.
+- Optional local `cqo` CLI with `start`, `status`, `audit`, and `history`.
+- Local heuristic Task Classifier with English and Chinese risk/complexity signals.
+- Soft Session Budgets for discovery, implementation paths, reasoning, verification, and subagent use.
+- Local-only task journal under `~/.cqo` (or `CQO_HOME`) with no telemetry or private account scraping.
+- Task-level Usage Audit that reports local change surface and CQO policy guardrails without inventing token-savings percentages.
+- Python unit tests and CLI smoke-test CI.
+
+### Changed
+- Execution budgets are explicitly advisory and may expand automatically when correctness requires more context or verification.
+- The optional CLI is an inspection layer, not a runtime dependency.
+- Direct `install.sh` installs a convenient `cqo` command under `~/.local/bin`.
+
 ## [0.1.0] - 2026-09-18
 
 ### Added

README.md

@@ -46,6 +46,24 @@ It does **not** bypass limits, scrape private quota data, or weaken verification
 
 ---
 
+## v0.2 — Zero-friction usage governor
+
+> **The optimizer should not become the overhead.**
+
+v0.2 turns the original Skill policy into a lightweight usage governor while keeping normal Codex execution unobstructed.
+
+| v0.2 capability | How it behaves |
+|---|---|
+| **Task Classifier** | Classifies XS → XL inside the existing reasoning turn; the optional CLI can also classify locally with heuristics |
+| **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 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.
+
+---
+
 ## Install
 
 ### Option A — One-line Skill install · recommended
@@ -58,6 +76,16 @@ npx skills add ctdaniel/codex-quota-optimizer --skill codex-quota-optimizer
 
 This is the fastest path for Codex users and also makes the Skill discoverable through the wider Skills ecosystem.
 
+The Skill works immediately; the local `cqo` CLI is optional. If you also want the short `cqo` command after a Skills CLI install:
+
+```bash
+mkdir -p ~/.local/bin
+chmod +x ~/.agents/skills/codex-quota-optimizer/scripts/cqo.py
+ln -sfn ~/.agents/skills/codex-quota-optimizer/scripts/cqo.py ~/.local/bin/cqo
+```
+
+If `~/.local/bin` is not in your shell `PATH`, you can still run the script directly with Python.
+
 ### Option B — Direct global install
 
 Use the repository installer across all of your Codex projects:
@@ -68,12 +96,18 @@ cd codex-quota-optimizer
 ./install.sh
 ```
 
-It installs to:
+It installs the Skill to:
 
 ```text
 ~/.agents/skills/codex-quota-optimizer
 ```
 
+and creates the optional CLI shortcut at:
+
+```text
+~/.local/bin/cqo
+```
+
 Codex should detect the Skill automatically. Restart Codex if it does not appear immediately.
 
 ### Option C — Repository-local
@@ -230,9 +264,9 @@ A local change should not automatically pay the cost of Level 4.
 
 ---
 
-## Two small helper tools
+## Local tools
 
-The Skill works without these scripts, but they can reduce repository discovery overhead.
+The Skill works without any helper script. These tools are optional and local-only.
 
 ### Compact repository snapshot
 
@@ -250,7 +284,26 @@ python skills/codex-quota-optimizer/scripts/change_scope.py
 
 Summarizes the current Git change surface and suggests a sensible verification level.
 
-Both scripts are local-only and dependency-light.
+### Optional `cqo` usage governor CLI
+
+The CLI never sits in the Codex runtime path. Use it only when you want local task budgeting/history:
+
+```bash
+cqo start "Fix the checkout bug" --mode economy
+cqo status
+cqo audit
+cqo history
+```
+
+It uses the Python standard library only, performs no network requests, and writes task-level state to `~/.cqo` (or `CQO_HOME`).
+
+If the `cqo` shortcut is not installed, run:
+
+```bash
+python ~/.agents/skills/codex-quota-optimizer/scripts/cqo.py status
+```
+
+The repository snapshot and change-scope scripts are also local-only and dependency-light.
 
 ---
 
@@ -292,20 +345,24 @@ codex-quota-optimizer/
 │       ├── agents/openai.yaml
 │       ├── references/
 │       └── scripts/
+│           ├── cqo.py             # optional local usage governor CLI
+│           ├── change_scope.py
+│           └── repo_snapshot.py
+├── tests/                         # standard-library CLI tests
 ├── assets/                        # Plugin icon + README visuals
 ├── examples/
-├── install.sh                     # installs Skill to ~/.agents/skills
+├── install.sh                     # installs Skill + optional cqo shortcut
 └── README.zh-CN.md
 ```
 
 ---
 
 ## Roadmap
 
-- [ ] Local **Usage Journal** for task-level observations — no private account scraping
-- [ ] **Task Classifier** output: task size, recommended model role, reasoning, verification scope
-- [ ] **Session Budget** for discovery / coding / verification work
-- [ ] End-of-task **Usage Audit** showing avoidable work that was skipped
+- [x] Local **Usage Journal** for task-level observations — no private account scraping
+- [x] **Task Classifier** output: task size, recommended model role, reasoning, verification scope
+- [x] **Soft Session Budget** for discovery / coding / verification work
+- [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

README.zh-CN.md

@@ -46,6 +46,24 @@ Codex 的额度并不只花在“写代码”上。很多消耗其实来自：**
 
 ---
 
+## v0.2｜零阻塞 Usage Governor
+
+> **优化器本身不能成为额外负担。**
+
+v0.2 在原有 Skill 策略上增加了一个轻量的 Usage Governor，但不会挡在 Codex 的正常执行链路前。
+
+| v0.2 能力 | 工作方式 |
+|---|---|
+| **Task Classifier** | 在原本的推理过程中完成 XS → XL 判断；可选 CLI 也可以用本地启发式规则分类 |
+| **Soft Session Budget** | 给探索、推理、验证、Subagent 提供建议范围，但绝不阻塞任务 |
+| **Local Usage Journal** | 只在本地 `~/.cqo` 保存任务级信息；无 Telemetry、不抓私人账户数据 |
+| **Usage Audit** | 记录本地改动面和 CQO 的策略约束，不虚构 Token 节省比例 |
+| **`cqo` CLI** | 可选的 `start / status / audit / history` 查看层；Codex 不依赖它运行 |
+
+CQO 自身不会额外发起模型调用、不会访问网络、不会设置阻塞式 Budget Gate，也不会自动拉起 Subagent。只要正确性需要更多上下文或验证，Codex 应直接继续完成任务。
+
+---
+
 ## 安装
 
 ### 方式 A｜一行命令安装 Skill · 推荐
@@ -58,6 +76,16 @@ npx skills add ctdaniel/codex-quota-optimizer --skill codex-quota-optimizer
 
 这是 Codex 用户最快的安装方式，也能让这个 Skill 进入更广泛的 Skills 生态发现路径。
 
+Skill 安装后即可使用；本地 `cqo` CLI 完全可选。如果你也希望通过短命令 `cqo` 使用本地任务预算与历史：
+
+```bash
+mkdir -p ~/.local/bin
+chmod +x ~/.agents/skills/codex-quota-optimizer/scripts/cqo.py
+ln -sfn ~/.agents/skills/codex-quota-optimizer/scripts/cqo.py ~/.local/bin/cqo
+```
+
+如果 `~/.local/bin` 不在你的 `PATH` 中，也可以直接通过 Python 运行脚本。
+
 ### 方式 B｜直接全局安装
 
 如果你希望继续使用仓库自带安装脚本：
@@ -74,6 +102,12 @@ Skill 会被安装到：
 ~/.agents/skills/codex-quota-optimizer
 ```
 
+同时会创建可选 CLI 快捷命令：
+
+```text
+~/.local/bin/cqo
+```
+
 Codex 通常会自动检测新 Skill；如果没有出现，重启 Codex 即可。
 
 ### 方式 C｜项目级安装
@@ -232,9 +266,9 @@ Level 4     全量测试 / 发布前 Gate
 
 ---
 
-## 两个辅助脚本
+## 本地辅助工具
 
-Skill 不依赖它们也能工作，但在较大的项目中它们可以进一步减少探索开销。
+Skill 完全不依赖任何辅助脚本；下面这些工具都只是可选、本地运行。
 
 ### Compact Repository Snapshot
 
@@ -252,7 +286,26 @@ python skills/codex-quota-optimizer/scripts/change_scope.py
 
 总结当前 Git 改动范围，并给出合理的验证层级建议。
 
-两个工具都只在本地工作，不上传项目数据。
+### 可选 `cqo` Usage Governor CLI
+
+CLI 不会插入 Codex 的执行链路。只有你希望查看本地任务预算和历史时才需要运行：
+
+```bash
+cqo start "修复结算页 Bug" --mode economy
+cqo status
+cqo audit
+cqo history
+```
+
+它只使用 Python 标准库，不访问网络，任务级状态保存在 `~/.cqo`（或 `CQO_HOME`）。
+
+如果没有安装 `cqo` 快捷命令，也可以直接运行：
+
+```bash
+python ~/.agents/skills/codex-quota-optimizer/scripts/cqo.py status
+```
+
+Repository Snapshot 与 Change Scope 两个脚本同样只在本地运行，不上传项目数据。
 
 ---
 
@@ -294,20 +347,24 @@ codex-quota-optimizer/
 │       ├── agents/openai.yaml
 │       ├── references/
 │       └── scripts/
+│           ├── cqo.py             # 可选本地 Usage Governor CLI
+│           ├── change_scope.py
+│           └── repo_snapshot.py
+├── tests/                         # Python 标准库 CLI 测试
 ├── assets/                        # Plugin 图标 + README 视觉资源
 ├── examples/
-├── install.sh                     # 安装到 ~/.agents/skills
+├── install.sh                     # 安装 Skill + 可选 cqo 快捷命令
 └── README.zh-CN.md
 ```
 
 ---
 
 ## Roadmap
 
-- [ ] 本地 **Usage Journal**：记录任务级使用行为，不抓取私人账户数据
-- [ ] **Task Classifier**：输出任务规模、模型角色、推理档和测试建议
-- [ ] **Session Budget**：给探索 / 编码 / 验证分配任务级工作预算
-- [ ] **Usage Audit**：任务结束展示本次避免了哪些无效工作
+- [x] 本地 **Usage Journal**：记录任务级使用行为，不抓取私人账户数据
+- [x] **Task Classifier**：输出任务规模、模型角色、推理档和测试建议
+- [x] **Soft Session Budget**：给探索 / 编码 / 验证提供非阻塞式预算建议
+- [x] **Usage Audit**：任务结束输出诚实的本地任务级观察
 - [ ] 自动识别不同框架最合适的定向测试
 - [x] Plugin 打包：同时支持 Skill 直装与 Plugin 分发
 - [ ] HOL Codex Plugin Catalog 收录

install.sh

@@ -4,6 +4,9 @@ set -euo pipefail
 ROOT="$(cd "$(dirname "$0")" && pwd)"
 SRC="${ROOT}/skills/codex-quota-optimizer"
 DEST="${HOME}/.agents/skills/codex-quota-optimizer"
+BIN_DIR="${HOME}/.local/bin"
+CLI_SRC="${DEST}/scripts/cqo.py"
+CLI_DEST="${BIN_DIR}/cqo"
 
 if [[ ! -d "$SRC" ]]; then
   echo "Skill source not found: $SRC" >&2
@@ -14,5 +17,13 @@ mkdir -p "$(dirname "$DEST")"
 rm -rf "$DEST"
 cp -R "$SRC" "$DEST"
 
+mkdir -p "$BIN_DIR"
+chmod +x "$CLI_SRC"
+ln -sfn "$CLI_SRC" "$CLI_DEST"
+
 echo "Installed codex-quota-optimizer to $DEST"
+echo "Installed optional cqo CLI to $CLI_DEST"
+if [[ ":${PATH}:" != *":${BIN_DIR}:"* ]]; then
+  echo "Note: add $BIN_DIR to PATH to run 'cqo' directly."
+fi
 echo "Restart Codex if the skill does not appear immediately."

plugin.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "codex-quota-optimizer",
-  "version": "0.1.0",
-  "description": "Reduce avoidable Codex usage with task-aware model routing, focused context, minimal changes, and layered verification.",
+  "version": "0.2.0",
+  "description": "A zero-friction Codex usage governor with task-aware routing, soft budgets, focused context, local audits, and layered verification.",
   "author": {
     "name": "Daniel Chen",
     "url": "https://github.com/ctdaniel"