agent-orchestrator-kit 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -4,6 +4,30 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.15.0] - 2026-09-08
+
+### Added
+- **`costUsdTotal` — one USD figure per change, phase, platform, model, and session.** Each session contributes its billed `costUsd` when present, otherwise its `costUsdEstimated`; sums are rounded to 4 decimals. A change that ran on Amp (billed `$14.48`) plus Claude (`~$5.16`) and Cursor (`~$1.43`) now carries `spend.costUsdTotal: 21.0779` instead of forcing a dashboard to pick `costUsd` and drop the estimated platforms. `costUsd` and `costUsdEstimated` stay separate fields and Amp credits stay out of every USD field. `metrics --summary-json` carries the field; the human `cost:` line prints `$21.08 ($14.48 billed + ~$6.60 est.)`.
+
+### Fixed
+- **Billed sums are rounded like estimates.** `spendByModel[].costUsd`, `spendByPlatform.*.costUsd`, `phases.*.costUsd`, and `spend.costUsd` stored raw float sums such as `4.4399999999999995` and `0.009000000000000001`; they are now `Math.round(x * 10000) / 10000`, the same rule `costUsdEstimated` already had.
+- **Cache-split cost estimates survive the session recompute.** `applyCollectedSessionFields` recomputed `byModel[].costUsdEstimated` from `inputTokens` + `outputTokens` alone and overwrote the value the adapters had already produced. Since `inputTokens` includes `cache_read_*` / `cache_creation_*`, every cached token was billed at the full input rate: a real Claude change with 3.5M tokens estimated `$30.11` instead of `$5.16`, and Cursor rows lost their own rate table to the Claude `$3/$15` fallback. The recompute now only fills rows that have no adapter estimate, so ESTIMATE-ALL still covers Amp rows without `Cost:` while `claude-opus-5` with 100k input + 900k cache read + 10k output stays at `$1.20`.
+
+## [0.14.1] - 2026-09-08
+
+### Fixed
+- **Memory graph survives `handoff` persist.** `loadMemoryItems` classified a memory file by its first character, so every JSONL graph (the format `@modelcontextprotocol/server-memory` reads and writes) was treated as an aggregate `{entities, relations}` document, failed to parse, and returned `[]` — the next persist then overwrote the whole file with just the current change's two entities. Everything the Memory MCP server had accumulated — all `Decision:*`, every other change, and all relations — was destroyed on each persist, leaving cross-session memory permanently one change deep. Detection is now by shape, `handoff --restore` reads JSONL graphs again instead of reporting "Memory JSON empty or missing", and a line that cannot be parsed is preserved verbatim rather than dropped.
+- **`/opsx:*` commands reach the IDEs.** `.agents/commands/` was installed and documented but synced nowhere. `sync` now writes `.cursor/commands/opsx-<phase>.md` (flat, `/opsx-<phase>`) and `.claude/commands/opsx/<phase>.md` (namespaced, so the documented `/opsx:<phase>` exists in Claude Code), with the same stale-file deletion as skills and subagents. `sync-local-agent-skills.sh` matches.
+- **`status` readiness mirrors the archive gates.** "ready to archive" was computed from `tasks.md` checkboxes alone, so it appeared on a change `archive` would refuse for a missing or non-APPROVE verdict. It now applies `require_spec_review` / `require_design_brief` and names the blockers.
+- **`gate-check` no longer passes silently.** When the git diff cannot be computed (shallow clone, missing base ref, no commits) the review gate is verified instead of skipped.
+- The next-thread prompt renders `- Change: <name>` instead of `- Change: - name: <name>`.
+
+### Removed
+- `templates/.cursor/memory.json` — an unused snapshot of the kit's own development memory. It was referenced by nothing (`init` writes an empty `.cursor/memory.json`), gitignored so it never showed up in a diff, yet the `files` allowlist still published it to npm. `files` now excludes `templates/.cursor` so it cannot ship again.
+
+### Added
+- `pipeline.src_glob` in `orchestrator.yaml` — the paths `gate-check` treats as product code. The hardcoded `src/` default silently disabled the review gate in repos whose code lives elsewhere; `--src-glob` still overrides.
+
 ## [0.14.0] - 2026-09-07
 
 ### Changed

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 (compact metrics schema v2, exhaustive Tier 2 punch list, bounded collection windows, Claude/Amp estimates, and dashboard JSON in v0.14.0):**
+**🔄 Already have the kit installed? Upgrade to latest (v0.15.0 adds `costUsdTotal`, one USD figure per change / phase / platform / model that sums billed Amp with estimated Cursor and Claude, rounds billed sums like estimates, and keeps cache-split Claude estimates from being re-billed at the full input rate):**
 
 ```bash
 npx agent-orchestrator-kit@latest update
@@ -189,7 +189,7 @@ your-project/
 |----------|----------|
 | Orchestration | 5-role pipeline, `AGENTS.md`, `orchestrator.yaml`, review command |
 | OpenSpec skills | All 7 skills for `/opsx:*` workflow |
-| IDE sync | Cursor + Claude Code sync script (`--delete` semantics — removes stale skills/subagents) |
+| IDE sync | Cursor + Claude Code sync script (`--delete` semantics — removes stale skills/subagents/commands) |
 | 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` / `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` |
@@ -816,7 +816,7 @@ Schema v2 stores compact `sourceIds`, `sourceTotals`, and `byModel` per session
 - **Locked client** — `--restore` records `pending.platform` and Amp `pending.threadId` before phase work. Persist follows that client’s flow even if persist runs in another shell (no `AMP_*` / `CURSOR_*`). Amp: `amp threads export` plus `amp threads usage --details` (`AOK_AMP_BIN`) and local `threads/*.json`. Export supplies `model` / tokens / `agentMode`; usage supplies billed `$`. If Amp runs tools over a pipe (`/dev/null`), thread id comes from `amp threads list`, not stale `session.json` `lastThreadId`. When env and Amp parent do not win, restore locks a fresh `session.json` `lastThreadId` as `amp-session-last`. Cursor: spend hook file. Claude: `~/.claude/projects`. `--collect` still runs all three adapters.
 - **Cursor spend hook (optional)** — Cursor never writes token usage to disk, so the kit can install `scripts/cursor-spend-hook.cjs` plus `.cursor/hooks.json` entries (`stop` / `subagentStop` / `afterAgentResponse`) in `init` / `update` / `sync` / `mcp-setup`: the hook appends each turn's tokens to gitignored `.agents/spend/cursor-usage.jsonl`. After a successful `stop` / `afterAgentResponse` append the hook runs leftover (fail-open, no stdout). Hook and collect resolve the consumer in a multi-root window (not the first cwd with `.agents` or `openspec`). Persist auto-reads that file when the locked client is Cursor. Persist and restore do not self-heal the hook. `sessionEnd` still runs `scripts/cursor-spend-collect.cjs`. Restart Cursor once after the first install. `status` shows a `Spend capture` section. Claude JSONL remains a fallback. Amp web/CLI spend is taken from `amp threads export` (tokens, model, `agentMode`) and `amp threads usage` (billed USD).
 
-Aggregates are recomputed on every write: per-phase totals (`startedAt`, `endedAt`, `leadTimeMs` from that phase’s sessions, `durationMs` = sum of session work time — not `totals.leadTimeMs` and not `endedAt − startedAt`, tokens, `costUsd`, `costUsdEstimated` to 4 decimals, `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.
+Aggregates are recomputed on every write: per-phase totals (`startedAt`, `endedAt`, `leadTimeMs` from that phase’s sessions, `durationMs` = sum of session work time — not `totals.leadTimeMs` and not `endedAt − startedAt`, tokens, `costUsd`, `costUsdEstimated`, `costUsdTotal` to 4 decimals, `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. `costUsdTotal` is the one USD figure per change, phase, platform, model, and session: each session contributes its billed `costUsd` when present, otherwise its `costUsdEstimated`, so a change that ran on Amp (billed) plus Cursor and Claude (estimated) sums all three platforms instead of showing only the billed part. Amp credits never enter it. The human `cost:` line prints it as `$21.08 ($14.48 billed + ~$6.60 est.)`.
 
 Fill `## Metrics` in `handoff.md` **before** persist (unknown is fine; do not invent `0`):
 
@@ -843,7 +843,7 @@ npx agent-orchestrator-kit archive add-thing --sync      # finalize + the same t
 
 #### Для дашбордів
 
-Use only `phases.<phase>.startedAt`, `endedAt`, and `durationMs` for phase boundaries and duration. Use `totals.leadTimeMs` only for the whole change. Git log MUST NOT be used for phase boundaries; the kit does not provide per-phase commit counts. `metrics <name> --summary-json` returns only aggregate `totals`, `phases`, and spend maps, without sessions or commits.
+Use only `phases.<phase>.startedAt`, `endedAt`, and `durationMs` for phase boundaries and duration. Use `totals.leadTimeMs` only for the whole change. Git log MUST NOT be used for phase boundaries; the kit does not provide per-phase commit counts. `metrics <name> --summary-json` returns only aggregate `totals`, `phases`, and spend maps, without sessions or commits. For the headline cost use `spend.costUsdTotal` (and `phases.<phase>.costUsdTotal`, `spendByPlatform.<platform>.costUsdTotal`, `spendByModel[].costUsdTotal`): `costUsd` alone is only the billed part and `costUsdEstimated` alone is only the estimated part, so picking one of them drops every platform that reported the other.
 
 Recording is on by default and never a persist/archive/`gate-check` gate; opt out per persist with `--no-metrics`. Persist and archive collect the locked client without `--collect`; `--collect` runs every adapter. Flags (`--model`, `--platform`, `--input-tokens`, …) override session totals in `metrics.json` and do not rewrite the `## Metrics` section.
 
@@ -986,11 +986,13 @@ npx agent-orchestrator-kit metrics [change-name] [--json] [--collect]
   skills/                # Synced from .agents/skills/
   rules/                 # Synced from .agents/rules/
   agents/                # Synced from .agents/subagents/
+  commands/              # Synced from .agents/commands/ (flat — /opsx-apply)
   memory.json            # Memory MCP data
 
 .claude/                 # Local only — Claude Code runtime
   skills/                # Synced from .agents/skills/
   agents/                # Synced from .agents/subagents/
+  commands/opsx/         # Synced from .agents/commands/ (namespaced — /opsx:apply)
   CLAUDE.md              # Synced from root CLAUDE.md
 
 .amp/                    # Local only — Amp config
@@ -1015,6 +1017,16 @@ Phase bounds and non-goals: [`openspec/specs/agentic-factory-roadmap/spec.md`](o
 
 ## Changelog
 
+### 0.15.0
+- **`costUsdTotal`** on `spend`, `phases.*`, `spendByPlatform.*`, `spendByModel[]`, and sessions — billed `costUsd` when present, otherwise `costUsdEstimated`, per session; a change that ran on Amp (billed) plus Cursor and Claude (estimated) now sums all three platforms instead of showing only the billed part; the human `cost:` line prints `$21.08 ($14.48 billed + ~$6.60 est.)` and `--summary-json` carries the field
+- Billed `costUsd` aggregates are rounded to 4 decimals like estimates (no more `4.4399999999999995` in `spendByModel`)
+- Cache-split Claude cost estimates survive the session recompute instead of being re-billed at the full input rate (`$30.11` → `$5.16` on a 3.5M-token change)
+
+### 0.14.1
+- **Memory graph survives `handoff` persist** — JSONL graphs were misread as an aggregate document and returned empty, so each persist overwrote the file with only the current change; all `Decision:*`, other changes, and relations were lost
+- `/opsx:*` commands now sync to `.cursor/commands/` (flat) and `.claude/commands/opsx/` (namespaced), so the documented slash commands exist in both IDEs
+- `status` applies `require_spec_review` / `require_design_brief` before saying "ready to archive"; `gate-check` verifies the gate instead of exiting 0 when the diff is unknown, and reads `pipeline.src_glob` for code outside `src/`
+
 ### 0.14.0
 - **BREAKING: compact metrics schema v2** — sessions persist `sourceIds` / `sourceTotals` / `byModel` instead of `sources`; `metrics --migrate` is schema-only; `metrics --summary-json` for dashboards
 - Bounded persist/leftover windows, thread-scoped Amp usage + fresh Cost, Claude dedup/subagent capture, static Claude/Amp estimates

package/bin/agent-orchestrator.js

@@ -220,6 +220,47 @@ function copyDir(src, dest, opts = {}) {
   }
 }
 
+// `.agents/commands/opsx-<phase>.md` is the source of truth for the /opsx:*
+// role commands. Cursor reads `.cursor/commands/<file>.md` as `/<file>`, so it
+// gets a flat copy. Claude Code namespaces by subdirectory —
+// `.claude/commands/opsx/<phase>.md` is what makes the documented
+// `/opsx:<phase>` actually exist there.
+function syncCommands(projectDir, ideDir, { namespaced }) {
+  const src = join(projectDir, '.agents', 'commands');
+  const dest = join(projectDir, ideDir, 'commands');
+  if (!existsSync(src)) return;
+
+  const files = readdirSync(src).filter((f) => f.endsWith('.md'));
+  const written = new Set();
+  mkdirSync(dest, { recursive: true });
+
+  for (const file of files) {
+    const match = namespaced && file.match(/^([a-z0-9]+)-(.+\.md)$/i);
+    const rel = match ? join(match[1], match[2]) : file;
+    const destPath = join(dest, rel);
+    mkdirSync(dirname(destPath), { recursive: true });
+    copyFileSync(join(src, file), destPath);
+    written.add(rel);
+    log.ok(destPath.replace(process.cwd() + '/', ''));
+  }
+
+  // Drop commands a kit `update` removed, mirroring the skills/subagents sync.
+  const walk = (dir, prefix = '') => {
+    for (const entry of readdirSync(dir)) {
+      const full = join(dir, entry);
+      const rel = prefix ? join(prefix, entry) : entry;
+      if (statSync(full).isDirectory()) {
+        walk(full, rel);
+        if (readdirSync(full).length === 0) rmSync(full, { recursive: true, force: true });
+      } else if (!written.has(rel)) {
+        rmSync(full, { force: true });
+        log.warn(`removed stale: ${join(dest, rel).replace(process.cwd() + '/', '')}`);
+      }
+    }
+  };
+  walk(dest);
+}
+
 function gitignoreLines(content) {
   return content.split('\n').map((l) => l.trim()).filter(Boolean);
 }
@@ -960,6 +1001,26 @@ function parseHandoffMarkdown(content) {
   return sections;
 }
 
+// The `## Change` section is a bullet list (`- name: <x>`), but the next-thread
+// prompt inlines it after its own bullet. Flatten it so the prompt does not
+// read "- Change: - name: <x>".
+function inlineChangeLabel(value, fallbackName) {
+  const text = String(value || '').trim();
+  if (!text) return fallbackName;
+  const parts = text
+    .split('\n')
+    .map((line) => line.replace(/^\s*[-*]\s*/, '').trim())
+    .filter(Boolean);
+  if (parts.length === 0) return fallbackName;
+  const named = parts.find((p) => /^name:\s*/i.test(p));
+  if (named) {
+    const rest = parts.filter((p) => p !== named);
+    const label = named.replace(/^name:\s*/i, '').trim() || fallbackName;
+    return rest.length ? `${label} (${rest.join('; ')})` : label;
+  }
+  return parts.join('; ');
+}
+
 function firstLineCommand(value) {
   const match = String(value || '').match(/\/opsx:[^\s`]+(?:\s+[^\s`]+)?/);
   if (match) return match[0].trim();
@@ -1397,7 +1458,7 @@ function buildNextSessionPrompt(fields, agentLanguage) {
 
 ## Повний контекст попередньої сесії (самодостатній — не покладайся лише на Memory)
 - Закрита роль: ${fields.closedRole || 'не вказано'}
-- Зміна: ${fields.change || name}
+- Зміна: ${inlineChangeLabel(fields.change, name)}
 - Зроблено:
 ${fields.done || 'не вказано'}
 - Рішення:
@@ -1449,7 +1510,7 @@ Do not mix phases. Do not start the following role in this chat until this phase
 
 ## Full previous-session context (self-contained — do not rely on Memory alone)
 - Closed role: ${fields.closedRole || 'not set'}
-- Change: ${fields.change || name}
+- Change: ${inlineChangeLabel(fields.change, name)}
 - Done:
 ${fields.done || 'not set'}
 - Decisions:
@@ -1481,26 +1542,48 @@ function loadMemoryItems(filePath) {
   if (!existsSync(filePath)) return [];
   const raw = readFileSync(filePath, 'utf-8').trim();
   if (!raw) return [];
-  if (raw.startsWith('{')) {
-    try {
-      const parsed = JSON.parse(raw);
+
+  // Aggregate form is a single JSON document: { entities: [...], relations: [...] }.
+  // Every JSONL line is an object too, so the *shape* decides — not the first
+  // character. Keying off `{` classified every JSONL graph as an aggregate,
+  // parsed it as one document, failed, and returned [] — which made the next
+  // persist overwrite the whole graph with just the current change.
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed && !Array.isArray(parsed) && (Array.isArray(parsed.entities) || Array.isArray(parsed.relations))) {
       const entities = (parsed.entities || []).map((entity) => ({ type: 'entity', ...entity }));
       const relations = (parsed.relations || []).map((relation) => ({ type: 'relation', ...relation }));
       return [...entities, ...relations];
+    }
+  } catch {
+    // Not a single JSON document — fall through to JSONL.
+  }
+
+  // JSONL: the format @modelcontextprotocol/server-memory reads and writes,
+  // one entity or relation per line. A line we cannot parse is kept verbatim
+  // so a persist never drops memory it failed to understand.
+  const items = [];
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(trimmed);
     } catch {
-      return [];
+      items.push({ __raw: trimmed });
+      continue;
     }
+    if (parsed && typeof parsed === 'object' && parsed.type) items.push(parsed);
+    else items.push({ __raw: trimmed });
   }
-  return raw
-    .split('\n')
-    .map((line) => line.trim())
-    .filter(Boolean)
-    .map((line) => JSON.parse(line));
+  return items;
 }
 
 function saveMemoryItems(filePath, items) {
   mkdirSync(dirname(filePath), { recursive: true });
-  const body = items.map((item) => JSON.stringify(item)).join('\n');
+  const body = items
+    .map((item) => (item && item.__raw !== undefined ? item.__raw : JSON.stringify(item)))
+    .join('\n');
   writeFileSync(filePath, body ? `${body}\n` : '');
 }
 
@@ -1627,12 +1710,18 @@ function roundUsd4(x) {
   return Math.round(Number(x) * 10000) / 10000;
 }
 
+function costUsdTotalOf(obj) {
+  const billed = numOrNull(obj && obj.costUsd);
+  if (billed != null) return billed;
+  return numOrNull(obj && obj.costUsdEstimated);
+}
+
 function metricsFilePath(projectDir, changeName) {
   return join(projectDir, 'openspec', 'changes', changeName, 'metrics.json');
 }
 
 function emptySpendTotals() {
-  return { inputTokens: null, outputTokens: null, totalTokens: null, costUsd: null, costUsdEstimated: null };
+  return { inputTokens: null, outputTokens: null, totalTokens: null, costUsd: null, costUsdEstimated: null, costUsdTotal: null };
 }
 
 function emptyPlatformSpend(source = 'none') {
@@ -1643,6 +1732,7 @@ function emptyPlatformSpend(source = 'none') {
     costUsd: null,
     ampCredits: null,
     costUsdEstimated: null,
+    costUsdTotal: null,
     source,
   };
 }
@@ -2383,6 +2473,9 @@ function applyCollectedSessionFields(session, sources, resolvedModel, opts, repo
   if (session.costUsd == null) {
     for (const row of session.byModel) {
       if (row.costUsd != null) continue;
+      // adapters already estimated with the cache-read / cache-write split; do not
+      // overwrite it with the coarse input+output estimate below
+      if (row.costUsdEstimated != null) continue;
       const described = describeClaudeCostEstimate({
         model: String(row.model || '').replace(/^Claude\s+/i, 'claude-').replaceAll(' ', '-').toLowerCase(),
         inputTokens: row.inputTokens,
@@ -2463,6 +2556,7 @@ function spendTuple(obj) {
     costUsd: numOrNull(obj && obj.costUsd),
     ampCredits: numOrNull(obj && obj.ampCredits),
     costUsdEstimated: numOrNull(obj && obj.costUsdEstimated),
+    costUsdTotal: numOrNull(obj && obj.costUsdTotal) ?? costUsdTotalOf(obj),
   };
 }
 
@@ -2482,6 +2576,7 @@ function addSpendNums(target, nums) {
   target.costUsd = addNullable(target.costUsd, nums.costUsd);
   target.ampCredits = addNullable(target.ampCredits, nums.ampCredits);
   target.costUsdEstimated = addNullable(target.costUsdEstimated, nums.costUsdEstimated);
+  target.costUsdTotal = addNullable(target.costUsdTotal, nums.costUsdTotal);
 }
 
 function recomputeSpendMaps(metrics) {
@@ -2500,6 +2595,7 @@ function recomputeSpendMaps(metrics) {
       costUsd: null,
       ampCredits: null,
       costUsdEstimated: null,
+      costUsdTotal: null,
     };
     addSpendNums(row, nums);
     byModel.set(key, row);
@@ -2520,10 +2616,14 @@ function recomputeSpendMaps(metrics) {
     }
   }
   for (const key of Object.keys(byPlatform)) {
+    byPlatform[key].costUsd = roundUsd4(byPlatform[key].costUsd);
     byPlatform[key].costUsdEstimated = roundUsd4(byPlatform[key].costUsdEstimated);
+    byPlatform[key].costUsdTotal = roundUsd4(byPlatform[key].costUsdTotal);
   }
   for (const row of byModel.values()) {
+    row.costUsd = roundUsd4(row.costUsd);
     row.costUsdEstimated = roundUsd4(row.costUsdEstimated);
+    row.costUsdTotal = roundUsd4(row.costUsdTotal);
   }
   metrics.spendByPlatform = byPlatform;
   metrics.spendByModel = [...byModel.values()];
@@ -2575,6 +2675,13 @@ function recomputeMetricsAggregates(metrics) {
       phase[spendKey] = addNullable(phase[spendKey], value);
       spend[spendKey] = addNullable(spend[spendKey], value);
     }
+    const sessionCostUsdTotal = costUsdTotalOf({
+      costUsd: sessionFieldOrSources(session, 'costUsd'),
+      costUsdEstimated: sessionFieldOrSources(session, 'costUsdEstimated'),
+    });
+    session.costUsdTotal = roundUsd4(sessionCostUsdTotal);
+    phase.costUsdTotal = addNullable(phase.costUsdTotal, sessionCostUsdTotal);
+    spend.costUsdTotal = addNullable(spend.costUsdTotal, sessionCostUsdTotal);
     if (session.role && !phase.agents.includes(session.role)) phase.agents.push(session.role);
     if (session.model && !phase.models.includes(session.model)) phase.models.push(session.model);
     if (Array.isArray(session.models)) {
@@ -2593,9 +2700,13 @@ function recomputeMetricsAggregates(metrics) {
     phase.leadTimeMs = Number.isFinite(startMs) && Number.isFinite(endMs)
       ? Math.max(0, endMs - startMs)
       : null;
+    phase.costUsd = roundUsd4(phase.costUsd);
     phase.costUsdEstimated = roundUsd4(phase.costUsdEstimated);
+    phase.costUsdTotal = roundUsd4(phase.costUsdTotal);
   }
+  spend.costUsd = roundUsd4(spend.costUsd);
   spend.costUsdEstimated = roundUsd4(spend.costUsdEstimated);
+  spend.costUsdTotal = roundUsd4(spend.costUsdTotal);
   metrics.phases = phases;
   metrics.totals = totals;
   metrics.spend = spend;
@@ -2822,7 +2933,8 @@ function formatMetricsCostLine(spend) {
   const estimated = spend && spend.costUsdEstimated;
   if (billed == null && estimated == null) return '—';
   if (billed != null && estimated != null) {
-    return `${formatMetricsCost(billed)} billed + ~${formatMetricsCost(estimated)} est.`;
+    const total = spend.costUsdTotal != null ? spend.costUsdTotal : billed + estimated;
+    return `${formatMetricsCost(total)} (${formatMetricsCost(billed)} billed + ~${formatMetricsCost(estimated)} est.)`;
   }
   if (billed != null) return formatMetricsCost(billed);
   return `~${formatMetricsCost(estimated)} est.`;
@@ -3055,11 +3167,13 @@ function readPipelineConfig(projectDir) {
   const requireBriefMatch = content.match(/require_design_brief:\s*(true|false)/);
   const maxActiveMatch = content.match(/max_active_changes:\s*(\d+)/);
   const taskContractMatch = content.match(/task_contract:\s*(warn|strict|off)/);
+  const srcGlobMatch = content.match(/src_glob:\s*["']?([^"'\s#]+)["']?/);
   return {
     requireSpecReview: requireReviewMatch ? requireReviewMatch[1] === 'true' : true,
     requireDesignBrief: requireBriefMatch ? requireBriefMatch[1] === 'true' : false,
     maxActiveChanges: maxActiveMatch ? parseInt(maxActiveMatch[1], 10) : null,
     taskContract: taskContractMatch ? taskContractMatch[1] : 'warn',
+    srcGlob: srcGlobMatch ? srcGlobMatch[1] : null,
   };
 }
 
@@ -3891,6 +4005,7 @@ program
       }
       copyDir(join(projectDir, '.agents', 'rules'), join(projectDir, '.cursor', 'rules'), { overwrite: true, delete: true });
       copyDir(join(projectDir, '.agents', 'subagents'), join(projectDir, '.cursor', 'agents'), { overwrite: true, delete: true });
+      syncCommands(projectDir, '.cursor', { namespaced: false });
     }
 
     if (syncClaude) {
@@ -3900,6 +4015,7 @@ program
         rmSync(join(projectDir, '.claude', 'skills', wrapper), { recursive: true, force: true });
       }
       copyDir(join(projectDir, '.agents', 'subagents'), join(projectDir, '.claude', 'agents'), { overwrite: true, delete: true });
+      syncCommands(projectDir, '.claude', { namespaced: true });
 
       const claudeMd = join(projectDir, 'CLAUDE.md');
       const claudeDir = join(projectDir, '.claude');
@@ -3937,6 +4053,13 @@ program
     if (changes.length === 0) {
       log.info('No active changes');
     } else {
+      // Readiness must mirror the gates `archive` actually enforces — reporting
+      // "ready" on task count alone told the conductor to archive a change the
+      // CLI would then refuse.
+      const config = readPipelineConfig(projectDir);
+      const requireReview = config ? config.requireSpecReview : true;
+      const requireBrief = config ? config.requireDesignBrief : false;
+
       for (const name of changes) {
         const changeDir = join(projectDir, 'openspec', 'changes', name);
         const progress = parseTasksProgress(changeDir);
@@ -3944,13 +4067,24 @@ program
         const hasBrief = parseDesignBrief(changeDir);
         const progressStr = progress ? `${progress.done}/${progress.total} tasks` : 'no tasks.md';
         const verdictStr = verdict || 'none';
-        const readyToArchive = Boolean(progress && progress.total > 0 && progress.done === progress.total);
+
+        const blockers = [];
+        if (!(progress && progress.total > 0 && progress.done === progress.total)) {
+          blockers.push('tasks incomplete');
+        }
+        if (requireReview && !(verdict && /^APPROVE/i.test(verdict))) {
+          blockers.push(verdict ? `review verdict "${verdict}" (need APPROVE)` : 'no review.md');
+        }
+        if (requireBrief && !hasBrief && !hasDesignOptOut(changeDir)) {
+          blockers.push('no design-brief.md');
+        }
 
         console.log(`\n${pc.bold(name)}`);
         console.log(`  tasks:  ${progressStr}`);
         console.log(`  review: ${verdictStr}`);
         console.log(`  brief:  ${hasBrief ? 'yes' : 'no'}`);
-        if (readyToArchive) log.ok('ready to archive');
+        if (blockers.length === 0) log.ok('ready to archive');
+        else log.info(`not ready to archive — ${blockers.join('; ')}`);
       }
       console.log('');
     }
@@ -3963,7 +4097,7 @@ program
 program
   .command('gate-check [change-name]')
   .description('Deterministically check the review gate before apply/merge (exit non-zero if unmet)')
-  .option('--src-glob <glob>', 'source path filter used to detect code changes', 'src/')
+  .option('--src-glob <glob>', 'source path filter used to detect code changes (default: pipeline.src_glob, else src/)')
   .option('--base <ref>', 'git ref to diff against', 'HEAD~1')
   .option('--staged', 'check staged files (git diff --cached) instead of --base...HEAD', false)
   .option('--tasks <name>', 'lint task contracts (Files/Do/Done-when) of a change')
@@ -4019,16 +4153,21 @@ program
       return;
     }
 
+    // A repo whose code does not live in src/ used to fall through to
+    // "nothing to gate" on every run, silently disabling the review gate.
+    const srcGlob = opts.srcGlob || config.srcGlob || 'src/';
+
     const touchesSrc = opts.staged
-      ? gitStagedTouchesGlob(projectDir, opts.srcGlob)
-      : gitDiffTouchesGlob(projectDir, opts.base, opts.srcGlob);
+      ? gitStagedTouchesGlob(projectDir, srcGlob)
+      : gitDiffTouchesGlob(projectDir, opts.base, srcGlob);
     if (touchesSrc === false) {
-      log.ok(`no ${opts.staged ? 'staged ' : ''}changes under ${opts.srcGlob} — nothing to gate`);
+      log.ok(`no ${opts.staged ? 'staged ' : ''}changes under ${srcGlob} — nothing to gate`);
       return;
     }
     if (touchesSrc === null) {
-      log.warn(`could not compute git ${opts.staged ? 'staged ' : ''}diff — skipping gate-check`);
-      return;
+      // Cannot prove nothing changed (shallow clone, missing base ref, no
+      // commits yet) — verify the gate instead of passing a blocking check.
+      log.warn(`could not compute git ${opts.staged ? 'staged ' : ''}diff — verifying the review gate anyway`);
     }
 
     const changes = listActiveChanges(projectDir);
@@ -4039,7 +4178,7 @@ program
     let target = changeName;
     if (!target) {
       if (changes.length === 0) {
-        log.warn(`${opts.srcGlob} changed but no active OpenSpec change found — cannot verify review gate`);
+        log.warn(`${srcGlob} changed but no active OpenSpec change found — cannot verify review gate`);
         return;
       }
       target = changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-orchestrator-kit",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Universal AI agent orchestration kit for Cursor, Claude Code, and Amp Code — spec-driven OpenSpec pipeline, conductor subagents, durable session handoff, factory gates and MCP setup, cloud-agent handoff, and optional local Figma PAT setup",
   "keywords": [
     "ai-agent",
@@ -35,6 +35,7 @@
   "files": [
     "bin/",
     "templates/",
+    "!templates/.cursor",
     "profiles/",
     "README.md",
     "CHANGELOG.md",

package/profiles/generic/orchestrator.yaml

@@ -11,6 +11,9 @@ pipeline:
   max_active_changes: 1
   archive_after_merge: true
   task_contract: warn
+  # Paths gate-check treats as product code. Widen it when code lives
+  # outside src/ (e.g. "{src,lib,app}/") or the review gate never fires.
+  src_glob: "src/"
 
 roles:
   explorer:

package/profiles/mvp/orchestrator.yaml

@@ -16,6 +16,9 @@ pipeline:
   archive_after_merge: false
   quick_mode_enabled: true
   task_contract: off
+  # Paths gate-check treats as product code. Widen it when code lives
+  # outside src/ (e.g. "{src,lib,app}/") or the review gate never fires.
+  src_glob: "src/"
 
 roles:
   explorer:

package/profiles/node/orchestrator.yaml

@@ -14,6 +14,9 @@ pipeline:
   max_active_changes: 1
   archive_after_merge: true
   task_contract: warn
+  # Paths gate-check treats as product code. Widen it when code lives
+  # outside src/ (e.g. "{src,lib,app}/") or the review gate never fires.
+  src_glob: "src/"
 
 roles:
   explorer:

package/profiles/vue3/orchestrator.yaml

@@ -14,6 +14,9 @@ pipeline:
   max_active_changes: 1
   archive_after_merge: true
   task_contract: warn
+  # Paths gate-check treats as product code. Widen it when code lives
+  # outside src/ (e.g. "{src,lib,app}/") or the review gate never fires.
+  src_glob: "src/"
 
 roles:
   explorer:

package/templates/orchestrator.yaml

@@ -13,6 +13,9 @@ pipeline:
   max_active_changes: 1
   archive_after_merge: true
   task_contract: warn
+  # Paths gate-check treats as product code. Widen it when code lives
+  # outside src/ (e.g. "{src,lib,app}/") or the review gate never fires.
+  src_glob: "src/"
 
 roles:
   explorer:

package/templates/scripts/cursor-spend-collect.cjs

@@ -23,6 +23,12 @@ function roundUsd4(x) {
   return Math.round(Number(x) * 10000) / 10000;
 }
 
+function costUsdTotalOf(obj) {
+  const billed = numOrNull(obj && obj.costUsd);
+  if (billed != null) return billed;
+  return numOrNull(obj && obj.costUsdEstimated);
+}
+
 function timestampMs(value) {
   if (value == null || value === '') return NaN;
   const ms = Date.parse(value);
@@ -435,6 +441,7 @@ function emptyPlatform(source = 'none') {
     costUsd: null,
     ampCredits: null,
     costUsdEstimated: null,
+    costUsdTotal: null,
     source,
   };
 }
@@ -442,7 +449,7 @@ function emptyPlatform(source = 'none') {
 function recompute(metrics) {
   const phases = {};
   const totals = { sessions: 0, durationMs: null, leadTimeMs: null, cloudSessions: 0 };
-  const spend = { inputTokens: null, outputTokens: null, totalTokens: null, costUsd: null, costUsdEstimated: null };
+  const spend = { inputTokens: null, outputTokens: null, totalTokens: null, costUsd: null, costUsdEstimated: null, costUsdTotal: null };
   const byPlatform = {
     cursor: emptyPlatform(),
     claude: emptyPlatform(),
@@ -477,6 +484,7 @@ function recompute(metrics) {
       totalTokens: null,
       costUsd: null,
       costUsdEstimated: null,
+      costUsdTotal: null,
       agents: [],
       models: [],
     };
@@ -493,6 +501,10 @@ function recompute(metrics) {
       phase[spendKey] = addNullable(phase[spendKey], value);
       spend[spendKey] = addNullable(spend[spendKey], value);
     }
+    const sessionCostUsdTotal = costUsdTotalOf(session);
+    session.costUsdTotal = roundUsd4(sessionCostUsdTotal);
+    phase.costUsdTotal = addNullable(phase.costUsdTotal, sessionCostUsdTotal);
+    spend.costUsdTotal = addNullable(spend.costUsdTotal, sessionCostUsdTotal);
     if (session.role && !phase.agents.includes(session.role)) phase.agents.push(session.role);
     if (session.model && !phase.models.includes(session.model)) phase.models.push(session.model);
     if (Array.isArray(session.models)) {
@@ -508,6 +520,7 @@ function recompute(metrics) {
       for (const key of ['inputTokens', 'outputTokens', 'totalTokens', 'costUsd', 'ampCredits', 'costUsdEstimated']) {
         bucket[key] = addNullable(bucket[key], numOrNull(session[key]));
       }
+      bucket.costUsdTotal = addNullable(bucket.costUsdTotal, sessionCostUsdTotal);
       if ((session.sourceIds || []).length) bucket.source = platform === 'cursor' ? 'cursor-hook' : `${platform}-jsonl`;
     }
     const modelRows = (session.byModel || []).length ? session.byModel : [session];
@@ -523,6 +536,7 @@ function recompute(metrics) {
           costUsd: null,
           ampCredits: null,
           costUsdEstimated: null,
+          costUsdTotal: null,
         };
         row.inputTokens = addNullable(row.inputTokens, numOrNull(src.inputTokens));
         row.outputTokens = addNullable(row.outputTokens, numOrNull(src.outputTokens));
@@ -530,6 +544,7 @@ function recompute(metrics) {
         row.costUsd = addNullable(row.costUsd, numOrNull(src.costUsd));
         row.ampCredits = addNullable(row.ampCredits, numOrNull(src.ampCredits));
         row.costUsdEstimated = addNullable(row.costUsdEstimated, numOrNull(src.costUsdEstimated));
+        row.costUsdTotal = addNullable(row.costUsdTotal, costUsdTotalOf(src));
         byModel.set(modelKey, row);
       }
     }
@@ -544,14 +559,22 @@ function recompute(metrics) {
     phase.leadTimeMs = Number.isFinite(startMs) && Number.isFinite(endMs)
       ? Math.max(0, endMs - startMs)
       : null;
+    phase.costUsd = roundUsd4(phase.costUsd);
     phase.costUsdEstimated = roundUsd4(phase.costUsdEstimated);
+    phase.costUsdTotal = roundUsd4(phase.costUsdTotal);
   }
+  spend.costUsd = roundUsd4(spend.costUsd);
   spend.costUsdEstimated = roundUsd4(spend.costUsdEstimated);
+  spend.costUsdTotal = roundUsd4(spend.costUsdTotal);
   for (const bucket of Object.values(byPlatform)) {
+    bucket.costUsd = roundUsd4(bucket.costUsd);
     bucket.costUsdEstimated = roundUsd4(bucket.costUsdEstimated);
+    bucket.costUsdTotal = roundUsd4(bucket.costUsdTotal);
   }
   for (const row of byModel.values()) {
+    row.costUsd = roundUsd4(row.costUsd);
     row.costUsdEstimated = roundUsd4(row.costUsdEstimated);
+    row.costUsdTotal = roundUsd4(row.costUsdTotal);
   }
   metrics.phases = phases;
   metrics.totals = totals;

package/templates/scripts/sync-local-agent-skills.sh

@@ -76,6 +76,13 @@ if [ -d .agents/subagents ]; then
   ok ".cursor/agents/"
 fi
 
+# Cursor reads .cursor/commands/<file>.md as /<file> — flat copy.
+if [ -d .agents/commands ]; then
+  mkdir -p .cursor/commands
+  rsync -a --delete .agents/commands/ .cursor/commands/
+  ok ".cursor/commands/"
+fi
+
 if [ ! -f .mcp.json ] && [ -f .agents/mcp.json.example ]; then
   cp .agents/mcp.json.example .mcp.json
   ok ".mcp.json created from example"
@@ -97,6 +104,26 @@ if [ -d .agents/subagents ]; then
   ok ".claude/agents/"
 fi
 
+# Claude Code namespaces commands by subdirectory: .claude/commands/opsx/apply.md
+# is what makes the documented /opsx:apply exist.
+if [ -d .agents/commands ]; then
+  rm -rf .claude/commands
+  mkdir -p .claude/commands
+  for cmd in .agents/commands/*.md; do
+    [ -f "$cmd" ] || continue
+    BASE="$(basename "$cmd" .md)"
+    NS="${BASE%%-*}"
+    REST="${BASE#*-}"
+    if [ "$NS" != "$BASE" ] && [ -n "$REST" ]; then
+      mkdir -p ".claude/commands/$NS"
+      cp "$cmd" ".claude/commands/$NS/$REST.md"
+    else
+      cp "$cmd" ".claude/commands/$BASE.md"
+    fi
+  done
+  ok ".claude/commands/"
+fi
+
 if [ -f CLAUDE.md ]; then
   cp CLAUDE.md .claude/CLAUDE.md
   ok ".claude/CLAUDE.md"

package/templates/.cursor/memory.json

@@ -1,11 +0,0 @@
-{"type":"entity","name":"Change:add-factory-memory-and-skills","entityType":"Change","observations":["status: archived","tasks: 9/9","last_role: Archiver","review: APPROVE","summary: archived to openspec/changes/archive/2026-08-27-add-factory-memory-and-skills"]}
-{"type":"entity","name":"Handoff:add-factory-memory-and-skills","entityType":"Handoff","observations":["next_role: none","next_command: none","summary: archived to openspec/changes/archive/2026-08-27-add-factory-memory-and-skills","blocked: none"]}
-{"type":"entity","name":"Decision:apply-complete","entityType":"Decision","observations":["all 9 tasks implemented and verified (npm test 101/101, openspec validate --strict, gate-check --tasks)","change: add-factory-memory-and-skills","date: 2026-08-27"]}
-{"type":"entity","name":"Decision:m1-followed","entityType":"Decision","observations":["task 2.3 Skill health stale/missing verified in a temporary init+sync project (smoke test), not in the kit repo","change: add-factory-memory-and-skills","date: 2026-08-27"]}
-{"type":"entity","name":"Decision:m2-followed","entityType":"Decision","observations":["skills.kit drift test iterates all five orchestrator.yaml files against templates/.agents/skills/","change: add-factory-memory-and-skills","date: 2026-08-27"]}
-{"type":"entity","name":"Decision:i1-honored","entityType":"Decision","observations":["did not change templates/orchestrator.yaml handoff.spawn_handoff_subagent (still false)","change: add-factory-memory-and-skills","date: 2026-08-27"]}
-{"type":"relation","from":"Change:add-factory-memory-and-skills","to":"Handoff:add-factory-memory-and-skills","relationType":"hasHandoff"}
-{"type":"relation","from":"Change:add-factory-memory-and-skills","to":"Decision:apply-complete","relationType":"hasDecision"}
-{"type":"relation","from":"Change:add-factory-memory-and-skills","to":"Decision:m1-followed","relationType":"hasDecision"}
-{"type":"relation","from":"Change:add-factory-memory-and-skills","to":"Decision:m2-followed","relationType":"hasDecision"}
-{"type":"relation","from":"Change:add-factory-memory-and-skills","to":"Decision:i1-honored","relationType":"hasDecision"}