token-harness 0.1.9 → 0.1.10

package/README.md

@@ -112,14 +112,42 @@ change is not automatically available through `token-harness@latest`.
 
 ### Advanced and AI-assisted use
 
-An AI may use the existing JSON CLI to inspect, plan and apply an explicitly approved change.
-That is optional: another AI subscription is not required to operate the app. No persistent
-agent, background model calls or task classifier runs behind your back.
+The long CLI flag combinations are **not** the normal human interface. They are the controller API
+used by the app, automation, and optionally by a coding harness. Humans can keep using the browser
+and the two entry points above.
+
+For in-session use, this repository now includes a portable Agent Skill at
+[`skills/token-harness/SKILL.md`](skills/token-harness/SKILL.md). A compatible Claude Code or Codex
+skill mechanism can load it on demand, after which you can simply ask the harness to **use Token
+Harness for this task**. The skill classifies substantial work conservatively, calls the existing
+local `--json` optimizer at meaningful task boundaries, and can use explicit workload scheduling
+when you have actually supplied a backlog. It does not run Token Harness before every tool call.
+
+The skill is deliberately thin: Token Harness remains the deterministic policy engine. No MCP
+server, background model, persistent agent, or second quota formula is added just to make this work.
+Local tokens are still not subscription quota, and raw Claude/Codex percentages are still not a
+common currency.
+
+Agent use is read-only by default. If Token Harness recommends a persistent model, reasoning, or
+verbosity change, the harness must first build a reviewed plan, explain the exact proposed mutation,
+and wait for your explicit approval before `apply`. A saved preference may affect future sessions;
+it is not silently presented as a live change to the current session.
+
+The guided app can preview **Enable in-session guidance** for each detected Claude Code or
+Codex installation. It installs the same portable skill into the agent's documented user-level
+Agent Skills directory through the normal transactional plan/apply path. The agent card then shows
+the live guidance state: **Enabled** when the exact skill is currently owned by Token Harness,
+**Enabled externally** for a byte-identical user-owned skill, or an explicit not-enabled,
+custom/conflict, or unavailable state. Existing `token-harness` skill directories are never
+overwritten or silently adopted, and matching bytes alone never create an ownership claim. The
+browser remains fully usable without any skill or second AI subscription. See
+[RFC 0023](docs/rfcs/0023-guided-agent-skill-install.md) for the install and ownership boundary.
 
 The older automation contracts remain available: `setup`, `optimize`, `plan`, `apply`,
 `verify`, `metrics`, `rollback`, and their JSON reports. `ui --json` preserves its existing
 schema-1 report; `ui --read-only` opens the legacy read-only dashboard. `ui --no-open` starts
-the guided app without launching a browser. Stop either local server with Ctrl+C.
+the guided app without launching a browser. Stop either local server with Ctrl+C. See
+[RFC 0022](docs/rfcs/0022-agent-native-skill.md) for the agent-facing safety boundary.
 
 ## What normal output looks like
 
@@ -239,6 +267,53 @@ Most people do not need this section. Run `token-harness <command> --help` for d
 | `handoff` | Build a bounded cross-harness handoff | No |
 | `benchmark*`, `transfer*` | Capture and compare empirical evidence | Local state only |
 
+## Workload-aware allowance planning
+
+If you know how many accepted tasks remain, the advanced CLI can ask whether that backlog fits the
+**currently observed** included allowance:
+
+```sh
+token-harness optimize --harness codex --task standard --tasks-left 5
+token-harness schedule --current codex --candidate claude --task-class standard --tasks-left 5
+```
+
+`--tasks-left` is explicit workload intent for a backlog of one task class. Token Harness does not
+infer it from `ccusage`, local tokens, session length, or raw provider percentages. A workload-driven
+recommendation requires complete project-local benchmark evidence for the exact model + reasoning
+effort + verbosity policy in both the five-hour and weekly windows. If that evidence is incomplete,
+capacity stays unknown.
+
+When evidence proves that the current policy cannot cover the stated backlog, `optimize` protects
+capacity instead of spending a quota-derived effort bonus and reports whether the five-hour,
+weekly, or both windows are limiting. `schedule` can use the same target to consider the other
+harness, but only when that candidate has enough conservative accepted-task capacity and passes the
+existing quality, pace, availability, and transfer checks.
+
+### Mixed task-class backlog
+
+For queued **new tasks** spanning more than one class, give `schedule` the mix explicitly:
+
+```sh
+token-harness schedule --current codex --candidate claude \
+  --workload mechanical=2,standard=3,hard=1
+```
+
+Mixed mode does not sum per-class task capacities as if they were separate quota buckets. It charges
+each proposed task's project-local p75 cost against the same shared five-hour and weekly allowance
+of that harness, then returns `stay`, `split`, `switch`, `shortfall`, or
+`insufficient-evidence`. Candidate assignments require at least three coherent quality-gated
+observations for the exact task class plus complete five-hour and weekly capacity evidence.
+Unproven work remains visibly unallocated.
+
+This mode is for queued/new tasks, not an in-progress handoff. Therefore `--workload` is mutually
+exclusive with `--task-class`, `--tasks-left`, manual pace/quality flags, and handoff/transfer
+flags. The allocator is deterministic and conservative; it does not claim globally optimal routing,
+launch either harness, or compare raw Claude and Codex percentages.
+
+No capacity after a future reset is assumed. Re-run the observation after the reset rather than
+treating a forecast as provider quota. See [RFC 0020](docs/rfcs/0020-workload-aware-allowance.md)
+and [RFC 0021](docs/rfcs/0021-mixed-workload-allocation.md).
+
 ## Applying native recommendations
 
 `optimize` remains read-only. Review a plan before applying a supported native change:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "token-harness",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "description": "Quota-aware efficiency layer for Claude Code and Codex subscription limits.",
   "license": "Apache-2.0",
   "type": "module",

package/sbom.json

@@ -1,14 +1,14 @@
 {
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:98b38470-d012-6450-a4aa-0abf63b8e925",
+  "serialNumber": "urn:uuid:9290051f-d6be-441a-20e1-add1f9ea0ff8",
   "version": 1,
   "metadata": {
     "component": {
       "type": "application",
       "bom-ref": "token-harness",
       "name": "token-harness",
-      "version": "0.1.9",
+      "version": "0.1.10",
       "description": "Quota-aware efficiency layer for Claude Code and Codex subscription limits.",
       "licenses": [
         {
@@ -20,7 +20,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "98b38470d0126450a4aa0abf63b8e925b297a1f1a2110d4a1074d7e3c0b10a21"
+          "content": "9290051fd6be441a20e1add1f9ea0ff88e9ae931921532ed8422d86db26f1b3a"
         }
       ]
     },