agent-orchestrator-kit 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -4,6 +4,24 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-08-29
+
+### Added
+- **Mandatory Cursor spend hook** — `scripts/cursor-spend-hook.cjs` (fail-open, silent) appends per-turn token usage from Cursor `stop` / `subagentStop` hook payloads to gitignored `.agents/spend/cursor-usage.jsonl`; `ensureCursorSpendHook` installs the script and merges `.cursor/hooks.json` in `init`, `update`, `sync`, `mcp-setup`, and self-heals on every `handoff` restore/persist (persist reports to stderr only) so every kit project records Cursor spend without manual flags; `status` prints a `Spend capture` section (cursor hook state + record count, local Claude/Amp data presence)
+
+### Changed
+- **Change metrics** — `session.model` resolves `--model` → `AOK_MODEL` → `null` (stderr warning); persist/archive auto-collect local usage from Claude JSONL, Amp threads, and the Cursor spend hook file (`.agents/spend/cursor-usage.jsonl`) into separate `spendByPlatform` / `spendByModel` figures (flags override session totals only; never merge Amp credits into USD); human `metrics` table prints `roles` and `models` plus platform/model tables; `archive` always creates or finalizes `metrics.json` with an Archiver session; Session Exit protocol requires `--model <llm-product-id>`
+- **Cursor spend adapter** — replaced the dead `state.vscdb` probe (Cursor never writes token usage to its local DB) with reading the hook-generated `.agents/spend/cursor-usage.jsonl` (window by `at`, dedup by `generation_id`, cumulative loop repeats keep the largest record, `source: "cursor-hook"`)
+
+### Fixed
+- **Amp source ids** — `messageId` is a thread-local counter (1, 3, 5…), so dedup ids are now namespaced as `<threadId>:<messageId>` to prevent collisions across threads
+
+## [0.5.0] - 2026-08-29
+
+### Added
+- **Change metrics** — git-tracked `openspec/changes/<name>/metrics.json`: `handoff --restore` records the session start (`pending` marker), `handoff <name>` closes the session (duration, closed role → phase `explore|design|spec|review|apply|archive`, runtime, tasks snapshot, optional `--model` / `--input-tokens` / `--output-tokens` / `--total-tokens` / `--cost-usd`, `--started-at` when restore was skipped, `--no-metrics` to opt out), `archive <name>` sets `archivedAt`; per-phase and total aggregates (durations, tokens, cost, agents, models, `leadTimeMs`) are recomputed on every write and unreported values stay null-honest
+- **`npx agent-orchestrator-kit metrics [change-name] [--json]`** — human summary (phases table, spend, recent sessions) or raw JSON; resolves archived changes under `openspec/changes/archive/*-<name>` too
+
 ## [0.4.0] - 2026-08-28
 
 ### Added
@@ -193,6 +211,8 @@ All notable changes to this project will be documented in this file.
 ### Added
 - Initial release: 5-role orchestration pipeline, `/opsx:*` commands, IDE sync
 
+[0.6.0]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.5.0...v0.6.0
+[0.5.0]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.1.14...v0.2.0

package/README.md

@@ -74,7 +74,7 @@ npx agent-orchestrator-kit@latest init --profile generic --ci gitlab --spec-veri
 
 See [Installation](#installation) for profile/CI options.
 
-**🔄 Already have the kit installed? Upgrade to latest (factory phases 1–3 in v0.4.0+, lean pipeline / archive CLI in v0.3.0+, handoff CLI in v0.1.14+, Figma PAT in v0.1.11+):**
+**🔄 Already have the kit installed? Upgrade to latest (auto-collect spend + Cursor hook in v0.6.0+, change metrics in v0.5.0+, factory phases 1–3 in v0.4.0+, lean pipeline / archive CLI in v0.3.0+, handoff CLI in v0.1.14+, Figma PAT in v0.1.11+):**
 
 ```bash
 npx agent-orchestrator-kit@latest update
@@ -191,7 +191,7 @@ your-project/
 | OpenSpec skills | All 7 skills for `/opsx:*` workflow |
 | IDE sync | Cursor + Claude Code sync script (`--delete` semantics — removes stale skills/subagents) |
 | Subagents | 12 exclusive routes: guide/setup/session-handoff, explore/design/propose/review/archive stage agents, and apply implementation/test/code-review agents — native in Cursor + Claude Code, isolated Amp `subagent-*` wrappers |
-| CLI gates | `npx agent-orchestrator-kit status` / `gate-check` / `archive` / `handoff` / `memory-setup` — deterministic review-gate, archive, and session-handoff (always via `npx`; see `cli-via-npm.mdc`) |
+| CLI gates | `npx agent-orchestrator-kit status` / `gate-check` / `archive` / `handoff` / `metrics` / `memory-setup` — deterministic review-gate, archive, session-handoff, and change metrics (always via `npx`; see `cli-via-npm.mdc`) |
 | CI | `agent-verify.yml` — GitHub (default) or GitLab fragment + `prebuild` hook, both run `gate-check` |
 | AI Spec Verifier | `spec-verify.yml` + verifier scripts — GitLab or GitHub, opt-in (`--spec-verify`) |
 | MCP templates | Memory MCP for Cursor and Amp |
@@ -797,6 +797,27 @@ npx agent-orchestrator-kit handoff <name> --cloud-check   # require exit 0
 
 Persist with `runtime: cloud` prints those four steps on stderr; stdout stays the pure `/opsx:` next-thread prompt. Local persist is unchanged.
 
+### Change metrics
+
+Every change accumulates git-tracked `openspec/changes/<name>/metrics.json` — the data source for planning the next feature: how long each phase took, how many sessions it needed, what it cost.
+
+- **`session.model`** — LLM product id. Primary from collected sources, otherwise `--model` → `AOK_MODEL` → `null` (stderr warning). Never a Closed role.
+- **Session start** — `handoff --restore` writes a `pending` marker (`startedAt`, expected role).
+- **Session end** — `handoff <name>` closes the pending session: duration, closed role, mapped phase (`explore` / `design` / `spec` / `review` / `apply` / `archive`), runtime (local/cloud), tasks snapshot (`n/m`), and persist/archive auto-collect local usage from Claude JSONL, Amp threads, and the Cursor spend hook file (.agents/spend/cursor-usage.jsonl). `--input-tokens` / `--output-tokens` / `--total-tokens` / `--cost-usd` override session totals only and do not wipe `spendByPlatform` / `spendByModel`. Never guess. Never invent USD from Amp credits. Never Cursor SDK / npm sqlite / a pricing table. No restore marker? Pass `--started-at <iso>` or the duration stays honestly `null`.
+- **Archive** — successful `archive <name>` always creates or finalizes `metrics.json`, sets `archivedAt`, appends an Archiver session, and runs collect unless `--no-collect`.
+- **Platform** — optional `--platform` / `AOK_PLATFORM` (`cursor|claude|amp` only). Invalid `--platform` fails before persist/move.
+- **Cursor spend hook (mandatory)** — Cursor never writes token usage to disk, so the kit installs `scripts/cursor-spend-hook.cjs` plus a `.cursor/hooks.json` entry (`stop` + `subagentStop`) in every project: the hook appends each turn's `input_tokens` / `output_tokens` / model from the hook payload to gitignored `.agents/spend/cursor-usage.jsonl`, and collect reads it (`source: "cursor-hook"`). Installed by `init` / `update` / `sync` / `mcp-setup` and self-healed on every `handoff` restore/persist — no manual step, no flags. Restart Cursor once after the first install. `status` shows a `Spend capture` section. Claude (`~/.claude/projects/*.jsonl`) and Amp (`~/.local/share/amp/threads/*.json`) already persist usage locally and need no hook.
+
+Aggregates are recomputed on every write: per-phase totals (`durationMs`, tokens, `costUsd`, `sessions`, `roles`, `models`) plus overall `totals` (`sessions`, `cloudSessions`, `durationMs` = sum of session work time, `leadTimeMs` = wall clock from first session start to last session end), `spend` (USD only), and separate **by platform** / **by model** tables. Numbers are null-honest: a metric nobody reported stays `null`, never a fake `0`. No single total that adds Amp credits to USD.
+
+```bash
+npx agent-orchestrator-kit handoff add-thing --input-tokens 12000 --output-tokens 3000 --cost-usd 0.42 --model claude-sonnet
+npx agent-orchestrator-kit metrics add-thing          # human summary: phases, tokens, cost, roles / models
+npx agent-orchestrator-kit metrics add-thing --json   # raw metrics.json (works for archived changes too)
+```
+
+Recording is on by default and never a persist/archive/`gate-check` gate; opt out per persist with `--no-metrics`. `--no-collect` skips adapters only.
+
 ### Skill inventory
 
 `.agents/orchestrator.yaml` carries a machine-readable `skills:` section (`kit` / `stack` / `external`) instead of hardcoded skill names in the CLI:
@@ -900,10 +921,21 @@ npx agent-orchestrator-kit archive <name> [--sync | --no-sync --force]
 
 npx agent-orchestrator-kit handoff [change-name] [options]
   --restore          Print the restore briefing instead of persisting
+                     (also records the session start into metrics.json)
   --runtime <value>  local | cloud (invalid values exit non-zero)
   --agent-id <id>    Cloud agent identifier (default: none)
   --cloud-check      Verify change artifacts are committed and pushed
                      (cloud: non-zero on failure; local: warning, exit 0)
+  --started-at <iso> Session start override when --restore was not run
+  --model <name>     Model used in this session (metrics.json)
+  --input-tokens <n> / --output-tokens <n> / --total-tokens <n>
+                     Token spend for this session (total defaults to in+out)
+  --cost-usd <usd>   Session cost in USD
+  --no-metrics       Skip recording this session into metrics.json
+
+npx agent-orchestrator-kit metrics [change-name] [--json]
+  Show recorded session metrics for a change (active or archived):
+  time per phase, sessions, tokens, cost, roles, models, lead time
 ```
 
 ## Directory Reference
@@ -936,7 +968,7 @@ CLAUDE.md                # Committed — synced to .claude/CLAUDE.md
 openspec/                # Committed — spec-driven workflow
   config.yaml            # Project context for AI
   specs/                 # Source of truth after archive
-  changes/               # Active work; <name>/handoff.md indexes session state
+  changes/               # Active work; <name>/handoff.md + metrics.json index session state
 ```
 
 ## Roadmap
@@ -950,6 +982,17 @@ Phase bounds and non-goals: [`openspec/specs/agentic-factory-roadmap/spec.md`](o
 
 ## Changelog
 
+### 0.6.0
+- **Mandatory Cursor spend hook** — `scripts/cursor-spend-hook.cjs` + `.cursor/hooks.json` (`stop` / `subagentStop`) write `.agents/spend/cursor-usage.jsonl`; installed by `init` / `update` / `sync` / `mcp-setup` and self-healed on `handoff`
+- Persist/archive auto-collect local usage from Claude JSONL, Amp threads, and the Cursor hook file into `spendByPlatform` / `spendByModel`
+- Amp source ids namespaced as `<threadId>:<messageId>` so thread-local counters do not collide
+- `status` prints a `Spend capture` section
+
+### 0.5.0
+- **Change metrics** — git-tracked `openspec/changes/<name>/metrics.json` (session start on `handoff --restore`, close on persist)
+- **`metrics` CLI** — human summary or `--json`; phases, tokens, cost, agents, models, lead time
+- Optional persist spend flags: `--model`, `--input-tokens`, `--output-tokens`, `--total-tokens`, `--cost-usd`, `--started-at`, `--no-metrics`
+
 ### 0.4.0
 - Factory phases 1–3: `hooks-setup` / `gate-check --staged`, `mcp-setup` (GitHub / GitLab / browser), MCP and Skill health in `status`
 - Git-canonical append-only `decisions.md`; Memory `Decision:*` is a file→Memory mirror