agent-orchestrator-kit 0.12.0 → 0.14.0

package/bin/claude-cost-estimate.js

@@ -0,0 +1,51 @@
+function numOrNull(value) {
+  if (value == null || value === '') return null;
+  const n = Number(value);
+  return Number.isFinite(n) ? n : null;
+}
+
+const RATES = {
+  'claude-fable-5': { input: 10, cacheRead: 0.25, cacheWrite: 12.5, output: 50 },
+  'claude-opus': { input: 5, cacheRead: 0.5, cacheWrite: 6.25, output: 25 },
+  'claude-sonnet-5': { input: 2, cacheRead: 0.2, cacheWrite: 2.5, output: 10 },
+  'claude-sonnet-4-6': { input: 3, cacheRead: 0.3, cacheWrite: 3.75, output: 15 },
+  'claude-haiku-4-5': { input: 1, cacheRead: 0.1, cacheWrite: 1.25, output: 5 },
+};
+
+function ratesForModel(model) {
+  const id = String(model || '').toLowerCase();
+  return Object.entries(RATES)
+    .sort(([a], [b]) => b.length - a.length)
+    .find(([prefix]) => id.startsWith(prefix))?.[1] || null;
+}
+
+export function estimateClaudeCostUsd({
+  model,
+  inputTokens,
+  cacheReadTokens,
+  cacheCreationTokens,
+  outputTokens,
+} = {}) {
+  const input = numOrNull(inputTokens);
+  const cacheRead = numOrNull(cacheReadTokens);
+  const cacheWrite = numOrNull(cacheCreationTokens);
+  const output = numOrNull(outputTokens);
+  if (input == null && cacheRead == null && cacheWrite == null && output == null) return null;
+  const rates = ratesForModel(model);
+  const usd = rates
+    ? ((input ?? 0) * rates.input
+      + (cacheRead ?? 0) * rates.cacheRead
+      + (cacheWrite ?? 0) * rates.cacheWrite
+      + (output ?? 0) * rates.output) / 1e6
+    : (((input ?? 0) + (cacheRead ?? 0) + (cacheWrite ?? 0)) * 3 + (output ?? 0) * 15) / 1e6;
+  return Math.round(usd * 10000) / 10000;
+}
+
+export function describeClaudeCostEstimate(args = {}) {
+  const usd = estimateClaudeCostUsd(args);
+  if (usd == null) return null;
+  return {
+    usd,
+    costSource: ratesForModel(args.model) ? 'api-estimate' : 'api-estimate-fallback',
+  };
+}

package/bin/session-client.js

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, readlinkSync } from 'fs';
+import { existsSync, readFileSync, readlinkSync, statSync } from 'fs';
 import { join } from 'path';
 import { homedir as osHomedir } from 'os';
 import { execFileSync } from 'child_process';
@@ -114,28 +114,68 @@ function isFreshTimestamp(value, now, maxAgeMs) {
   return now - n >= 0 && now - n <= maxAgeMs;
 }
 
+function isSessionFileFresh(updatedAt, filePath, now, maxAgeMs) {
+  if (updatedAt != null && updatedAt !== '') {
+    return isFreshTimestamp(updatedAt, now, maxAgeMs);
+  }
+  try {
+    return isFreshTimestamp(statSync(filePath).mtimeMs, now, maxAgeMs);
+  } catch {
+    return false;
+  }
+}
+
+function emptyAmpSessionHint(filePath, fileFresh, updatedAt) {
+  return {
+    threadId: '',
+    source: '',
+    lastThreadId: '',
+    filePath: filePath || '',
+    fileFresh: Boolean(fileFresh),
+    updatedAt: updatedAt == null ? '' : updatedAt,
+  };
+}
+
 export function readAmpSessionHint(options = {}) {
   const env = options.env || {};
   const homedir = options.homedir || env.HOME;
   const now = options.now != null ? Number(options.now) : Date.now();
   const maxAgeMs = options.maxAgeMs != null ? Number(options.maxAgeMs) : AMP_TTY_MAX_AGE_MS;
   const filePath = join(ampDataRoot(env, homedir), 'session.json');
-  if (!existsSync(filePath)) return { threadId: '', source: '' };
+  if (!existsSync(filePath)) return emptyAmpSessionHint(filePath, false, '');
   let data;
   try {
     data = JSON.parse(readFileSync(filePath, 'utf-8'));
   } catch {
-    return { threadId: '', source: '' };
+    return emptyAmpSessionHint(filePath, isSessionFileFresh('', filePath, now, maxAgeMs), '');
+  }
+  if (!data || typeof data !== 'object') {
+    return emptyAmpSessionHint(filePath, isSessionFileFresh('', filePath, now, maxAgeMs), '');
   }
-  if (!data || typeof data !== 'object') return { threadId: '', source: '', lastThreadId: '' };
   const lastThreadId = trim(data.lastThreadId);
+  const updatedAt = data.updatedAt;
+  const fileFresh = isSessionFileFresh(updatedAt, filePath, now, maxAgeMs);
   const rawTty = options.ttyKey != null ? options.ttyKey : currentTtyKey(env, options.readlink);
   const ttyKey = isUsableTtyPath(rawTty) ? (String(rawTty).startsWith('tty:') ? rawTty : `tty:${rawTty}`) : '';
   const byTty = data.lastThreadByTerminal && ttyKey ? data.lastThreadByTerminal[ttyKey] : null;
   if (byTty && trim(byTty.lastThreadId) && isFreshTimestamp(byTty.updatedAt, now, maxAgeMs)) {
-    return { threadId: trim(byTty.lastThreadId), source: 'amp-session-tty', lastThreadId };
+    return {
+      threadId: trim(byTty.lastThreadId),
+      source: 'amp-session-tty',
+      lastThreadId,
+      filePath,
+      fileFresh,
+      updatedAt,
+    };
   }
-  return { threadId: '', source: '', lastThreadId };
+  return {
+    threadId: '',
+    source: '',
+    lastThreadId,
+    filePath,
+    fileFresh,
+    updatedAt,
+  };
 }
 
 export function detectSessionClient(options = {}) {
@@ -168,6 +208,15 @@ export function detectSessionClient(options = {}) {
   if (hint.threadId) {
     return { platform: 'amp', threadId: hint.threadId, source: hint.source };
   }
+  if (hint.lastThreadId && hint.fileFresh) {
+    return { platform: 'amp', threadId: hint.lastThreadId, source: 'amp-session-last' };
+  }
+  if (hint.fileFresh) {
+    const listed = listRecentAmpThreadIds(options);
+    if (listed[0]) {
+      return { platform: 'amp', threadId: listed[0], source: 'amp-session-list' };
+    }
+  }
 
   return { platform: null, threadId: null, source: 'none' };
 }

package/bin/spend-collect.js

@@ -1,10 +1,11 @@
 import { existsSync, readdirSync, readFileSync } from 'fs';
-import { join, basename } from 'path';
+import { join, basename, sep } from 'path';
 import { homedir as osHomedir } from 'os';
 import { execFileSync } from 'child_process';
 import { listRecentAmpThreadIds } from './session-client.js';
 import { formatUtcIso, parseFlexibleIso } from './metrics-time.js';
 import { describeCursorCostEstimate } from './cursor-cost-estimate.js';
+import { describeClaudeCostEstimate } from './claude-cost-estimate.js';
 import { ampAgentMode, matchAmpUsageModel, parseAmpUsageDetails } from './amp-usage.js';
 
 const PLATFORMS = ['cursor', 'claude', 'amp'];
@@ -216,17 +217,31 @@ function collectClaude({ cwd, windowStart, windowEnd, existing, env, homedir, no
     notes.push('claude: project folder missing');
     return sources;
   }
-  let files;
+  let entries;
   try {
-    files = readdirSync(projectDir).filter((name) => name.endsWith('.jsonl'));
+    entries = readdirSync(projectDir, { withFileTypes: true });
   } catch {
     notes.push('claude: cannot read project folder');
     return sources;
   }
+  const files = entries
+    .filter((entry) => entry.isFile() && entry.name.endsWith('.jsonl'))
+    .map((entry) => join(projectDir, entry.name));
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const subagentsDir = join(projectDir, entry.name, 'subagents');
+    if (!existsSync(subagentsDir)) continue;
+    try {
+      for (const name of readdirSync(subagentsDir)) {
+        if (name.endsWith('.jsonl')) files.push(join(subagentsDir, name));
+      }
+    } catch {}
+  }
+  const bestById = new Map();
   for (const file of files) {
     let text;
     try {
-      text = readFileSync(join(projectDir, file), 'utf-8');
+      text = readFileSync(file, 'utf-8');
     } catch {
       continue;
     }
@@ -245,9 +260,18 @@ function collectClaude({ cwd, windowStart, windowEnd, existing, env, homedir, no
       const id = message.id;
       if (id == null || id === '') continue;
       if (existing.has(String(id))) continue;
-      if (row.cwd !== cwd) continue;
+      if (row.cwd !== cwd && !String(row.cwd || '').startsWith(`${cwd}${sep}`)) continue;
       if (!inWindow(row.timestamp, windowStart, windowEnd)) continue;
-      sources.push(sourceRecord({
+      const cacheReadTokens = numOrNull(usage.cache_read_input_tokens ?? usage.cacheReadInputTokens);
+      const cacheCreationTokens = numOrNull(usage.cache_creation_input_tokens ?? usage.cacheCreationInputTokens);
+      const described = describeClaudeCostEstimate({
+        model: message.model,
+        inputTokens: usage.input_tokens ?? usage.inputTokens,
+        cacheReadTokens,
+        cacheCreationTokens,
+        outputTokens: usage.output_tokens ?? usage.outputTokens,
+      });
+      const record = sourceRecord({
         id,
         platform: 'claude',
         model: message.model,
@@ -256,9 +280,21 @@ function collectClaude({ cwd, windowStart, windowEnd, existing, env, homedir, no
         costUsd: claudeCostUsd(row, usage),
         ampCredits: null,
         at: row.timestamp,
-      }));
+        cacheReadTokens,
+        costUsdEstimated: described?.usd ?? null,
+        costSource: described?.costSource ?? null,
+      });
+      const previous = bestById.get(String(id));
+      if (!previous || (record.totalTokens ?? 0) > (previous.totalTokens ?? 0)) {
+        bestById.set(String(id), record);
+      } else if ((record.totalTokens ?? 0) === (previous.totalTokens ?? 0)) {
+        const at = parseTime(record.at);
+        const previousAt = parseTime(previous.at);
+        if (Number.isFinite(at) && (!Number.isFinite(previousAt) || at < previousAt)) previous.at = record.at;
+      }
     }
   }
+  sources.push(...bestById.values());
   return sources;
 }
 
@@ -409,10 +445,14 @@ export function sourcesFromAmpThread(thread, ctx, fileName = '', via = null) {
   return sources;
 }
 
-function collectAmp({ cwd, windowStart, windowEnd, existing, env, homedir, notes }) {
+function collectAmp({ cwd, windowStart, windowEnd, existing, env, homedir, notes, ampThreadId, collectAll }) {
   const root = ampRoot(env, homedir);
   const threadsDir = join(root, 'threads');
   const sources = [];
+  if (!ampThreadId && collectAll !== true) {
+    notes.push('amp: skipped local threads without thread id');
+    return sources;
+  }
   if (!existsSync(threadsDir)) {
     notes.push('amp: threads folder missing');
     return sources;
@@ -432,6 +472,8 @@ function collectAmp({ cwd, windowStart, windowEnd, existing, env, homedir, notes
     } catch {
       continue;
     }
+    const threadKey = thread && thread.id ? String(thread.id) : basename(file, '.json');
+    if (ampThreadId && threadKey !== String(ampThreadId)) continue;
     sources.push(...sourcesFromAmpThread(thread, ctx, file));
   }
   return sources;
@@ -504,8 +546,10 @@ function collectAmpCli(ctx) {
     if (id && !ids.includes(id)) ids.push(id);
   };
   push(ampThreadId);
-  push(ampCurrentThreadId(env));
-  if (!ids.length) {
+  if (ctx.listRecentAmpThreads === true) {
+    push(ampCurrentThreadId(env));
+  }
+  if (!ids.length && ctx.listRecentAmpThreads === true) {
     for (const id of listRecentAmpThreadIds(ctx)) push(id);
   }
   const sources = [];
@@ -527,6 +571,10 @@ function collectAmpCli(ctx) {
       ...row,
       model: matchAmpUsageModel(row.model, sourceModels),
     }));
+    const alreadyBilled = ctx.existingThreadIds.has(id) && ctx.rebillThreadId !== id;
+    if (alreadyBilled) {
+      for (const row of usageModels) row.costUsd = null;
+    }
     if (usage && usage.costUsd != null) {
       for (const src of extracted) {
         src.costSource = 'amp-usage';
@@ -535,7 +583,7 @@ function collectAmpCli(ctx) {
     threads.push({
       id,
       agentMode,
-      costUsd: usage ? numOrNull(usage.costUsd) : null,
+      costUsd: usage && !alreadyBilled ? numOrNull(usage.costUsd) : null,
       inputTokens: usage ? numOrNull(usage.inputTokens) : null,
       outputTokens: usage ? numOrNull(usage.outputTokens) : null,
       totalTokens: usage ? numOrNull(usage.totalTokens) : null,
@@ -706,7 +754,6 @@ function collectCursor({ cwd, windowStart, windowEnd, existing, existingSources,
     if (!row || typeof row !== 'object') continue;
     const id = row.id == null || row.id === '' ? null : String(row.id);
     if (!id) continue;
-    if (existing.has(id)) continue;
     if (filterId) {
       const rowConversationId = row.conversationId == null || row.conversationId === ''
         ? ''
@@ -807,6 +854,9 @@ export function collectSpend(options = {}) {
         ? [...options.existingSourceIds]
         : [],
   );
+  const existingSourceTotals = options.existingSourceTotals && typeof options.existingSourceTotals === 'object'
+    ? options.existingSourceTotals
+    : {};
   const windowStart = options.windowStart;
   const windowEnd = options.windowEnd;
   const notes = [];
@@ -821,16 +871,21 @@ export function collectSpend(options = {}) {
     windowEnd,
     existing,
     existingSources,
+    existingSourceTotals,
     env,
     homedir,
     notes,
     ampThreadId: options.ampThreadId,
+    listRecentAmpThreads: options.listRecentAmpThreads,
     cursorConversationId: options.cursorConversationId,
     exportAmpThread: options.exportAmpThread,
     listAmpThreads: options.listAmpThreads,
     usageAmpThread: options.usageAmpThread,
     ampBin: options.ampBin,
     timeoutMs: options.timeoutMs,
+    collectAll: options.collectAll === true || options.platforms == null,
+    existingThreadIds: new Set(options.existingThreadIds || []),
+    rebillThreadId: options.rebillThreadId || null,
   };
   let sources = [];
   const ampThreads = [];
@@ -864,9 +919,20 @@ export function collectSpend(options = {}) {
       notes.push('cursor: adapter failed');
     }
   }
+  sources = sources.filter((source) => {
+    if (!source || !existing.has(String(source.id))) return true;
+    if (!Object.hasOwn(existingSourceTotals, source.id)) return false;
+    return (numOrNull(source.totalTokens) ?? 0) > (numOrNull(existingSourceTotals[source.id]) ?? 0);
+  });
   const { byPlatform, byModel } = aggregate(sources);
   applyAmpThreadSpend(byPlatform, byModel, ampThreads);
-  return { sources, byPlatform, byModel, notes, ampThreads };
+  const ids = [...new Set(sources.map((source) => String(source.id)))];
+  const totals = {};
+  for (const source of sources) {
+    const id = String(source.id);
+    totals[id] = Math.max(numOrNull(totals[id]) ?? 0, numOrNull(source.totalTokens) ?? 0);
+  }
+  return { sources, ids, totals, byPlatform, byModel, notes, ampThreads };
 }
 
 function applyAmpThreadSpend(byPlatform, byModel, threads) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-orchestrator-kit",
-  "version": "0.12.0",
+  "version": "0.14.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",

package/templates/.agents/commands/opsx-propose.md

@@ -35,6 +35,12 @@ When ready to implement, run /opsx:apply
 
 Each task must be self-contained for a blind implementer — executable without reading design.md. `Files:` paths must exist unless prefixed with `new file:`. Lint: `npx agent-orchestrator-kit gate-check --tasks <name>` (mode via `pipeline.task_contract: warn|strict|off`).
 
+On re-propose after `review.md` Verdict REQUEST CHANGES, the conductor MUST pass `review.md` (path + verdict + Required Before Apply list) in the `spec-architect` spawn prompt and verify the report addresses every item; the parent MUST NOT itself edit proposal/design/specs/tasks. Exception: the structure-only propose trigger is the exact line
+
+**Source:** gate-check
+
+plus the absence of `## Checklist`; then fix only those gate-check errors.
+
 **Steps**
 
 1. **If no input provided, ask what they want to build**

package/templates/.agents/commands/opsx-review.md

@@ -38,11 +38,15 @@ npx agent-orchestrator-kit gate-check --review <name>
 
 The script runs `openspec validate --strict --type change`, the task-contract lint (Files/Do/Done-when), the `Non-goals` / `Acceptance criteria` proposal sections check, and non-empty ADDED/MODIFIED/REMOVED delta-spec sections check. Add `--json` for a `{pass, errors[]}` report.
 
-**If Tier 1 fails (exit ≠ 0):** do NOT spawn `spec-reviewer` and do NOT read the artifacts. Write `openspec/changes/<name>/review.md` with `Verdict: REQUEST CHANGES` listing the gate-check errors (source: gate-check), output the Request Changes verdict in chat, and go straight to Session Exit.
+**If Tier 1 fails (exit ≠ 0):** do NOT spawn `spec-reviewer` and do NOT read the artifacts. Write `openspec/changes/<name>/review.md` with `Verdict: REQUEST CHANGES` listing the gate-check errors. The T1 file MUST include this exact line:
+
+**Source:** gate-check
+
+The T1 `review.md` has no `## Checklist` section. This parent-written T1 `review.md` is an **accepted exception** to pipeline-subagents «parent MUST NOT write the verdict». Output the Request Changes verdict in chat. After an accepted RC one line MUST contain `Verdict: REQUEST CHANGES` and `/opsx:propose`. Go straight to Session Exit.
 
 ### 3. Tier 2 — spawn the specialist
 
-Only after Tier 1 passes: spawn `spec-reviewer` with the complete change paths, project constraints, and the shortened checklist below. Require `## Subagent report: spec-reviewer`. Do not perform the review in the parent session.
+Only after Tier 1 passes: spawn `spec-reviewer` with the complete change paths, project constraints, and the shortened checklist below. The parent MUST paste the full Tier 2 checklist from this file into the `spec-reviewer` prompt, including the Vue 3 items when `project.stack: vue3`. Before spawn, the parent MUST record whether `openspec/changes/<name>/review.md` already existed, and pass that fact plus the path in the spawn prompt. Require `## Subagent report: spec-reviewer`. Do not perform the review in the parent session.
 
 ### 4. Review checklist (Tier 2 — LLM-only)
 
@@ -68,6 +72,10 @@ Do NOT re-check what Tier 1 already covered (strict validation, contract field p
 - [ ] Tasks reference concrete component/store paths under `src/`
 - [ ] No scope creep into unrelated UI refactors
 
+MUST NOT stop at the first blocking finding. Finish the full LLM checklist and a complete scan of proposal.md, design.md, tasks.md, all delta specs, and referenced main specs/repo paths before writing the verdict. One ✗ still means REQUEST CHANGES, but list every blocking issue of that pass.
+
+Re-review MUST scan the same defect class — LLM-only only (another task whose `Do:` is not executable without design.md; another design behaviour with no delta requirement; another proposal↔tasks drift; another referenced heading/path that does not exist). Tier 1 classes NEVER enter this rescan. MUST NOT emit a one-item RC that names only the first leftover.
+
 ### 5. Write and report the verdict
 
 #### If all ✓ (or only minor notes):
@@ -110,12 +118,16 @@ Create or update `openspec/changes/<name>/review.md`:
 
 On **APPROVE**, `spec-reviewer` also writes `openspec/changes/<name>/apply-notes.md` (≤ 20 lines): critical constraints, pitfalls, what NOT to touch, verification commands. It is the distilled input for `/opsx:apply` and the **second allowed file** next to `review.md`.
 
-For **REQUEST CHANGES**, write only `review.md` with `Verdict: REQUEST CHANGES` and the issues list.
+For **REQUEST CHANGES**, write only `review.md` with `Verdict: REQUEST CHANGES` and the required sections: Checklist (each T2 item ✓/✗), Findings (Blocker / Major / Minor; empty buckets allowed), Required Before Apply (blocking only), Previous findings. Cosmetics stay out of Required Before Apply.
+
+The `Previous findings` heading is ALWAYS present after any Tier 2 pass. If no prior `review.md` existed, the body is the literal line `none — first review cycle`. If a prior file existed, each prior Required Before Apply item → `resolved` | `unresolved` plus one-line evidence.
 
 `review.md` (always) and `apply-notes.md` (on APPROVE) are the **only files** you may write during review (not `src/`, not `tasks.md` checkboxes).
 
 The conductor verifies the subagent's `Status: done`, checks that `review.md` exists with the reported verdict (and `apply-notes.md` on APPROVE), and relays the result without editing them.
 
+After Tier 2, the conductor MUST reject an RC `review.md` that lacks those headings or has an empty Checklist and MUST NOT rewrite the file; then re-spawn `spec-reviewer` once with the rejection reason and required headings; if the second file is still non-conforming, close with `## Blocked` naming the missing headings and next command `/opsx:review <name>` (a rejected file is not an accepted verdict). NEXT-AFTER-RC applies only to an accepted (schema-conforming) RC.
+
 #### If any ✗:
 
 ```
@@ -123,25 +135,37 @@ The conductor verifies the subagent's `Status: done`, checks that `review.md` ex
 
 **Change:** <name>
 
-### Issues Found
+### Checklist
+- proposal ↔ design ↔ tasks: ✓ or ✗
+- Delta specs cover design: ✓ or ✗
+- No conflicts with main specs: ✓ or ✗
+- No scope creep vs Non-goals: ✓ or ✗
+- Task self-sufficiency: ✓ or ✗
+- Vue 3 items (when `project.stack: vue3`): ✓ or ✗ each
+
+### Findings
+
+#### Blocker
+- <or empty>
 
-#### Proposal
-- ✗ <issue description> — suggestion: <how to fix>
+#### Major
+- <or empty>
 
-#### Tasks
-- ✗ Task 3 is too vague: "Update the component" — specify which component and what exact change
+#### Minor
+- <or empty>
 
 ### Required Before Apply
-<list only what must be fixed, not cosmetic>
+- <blocking only>
 
-Fix the above, then re-run `/opsx:review <name>`.
+### Previous findings
+none — first review cycle
 ```
 
 ---
 
 ## Session Exit (HARD STOP)
 
-Close via the canonical Session Exit protocol in `.agents/rules/session-handoff.mdc`. First line of the pasted prompt is the next `/opsx:*` command (`/opsx:apply <name>` only after APPROVE). Do not start the next phase in this chat.
+Close via the canonical Session Exit protocol in `.agents/rules/session-handoff.mdc`. After an accepted REQUEST CHANGES one line contains `Verdict: REQUEST CHANGES` and `/opsx:propose`; after APPROVE `/opsx:apply <name>`. NEXT-AFTER-RC applies only to an accepted (schema-conforming) RC. Do not start the next phase in this chat.
 
 ## Guardrails
 

package/templates/.agents/rules/session-handoff.mdc

@@ -20,13 +20,13 @@ Agents (local or cloud) write session artifacts only to git-tracked paths — ne
 
 ## Session Exit (order)
 1. The parent writes `openspec/changes/<name>/handoff.md` itself: Closed role, Change, Done, Decisions, Blocked, Next command, Next role, Attach, Subagents to spawn, Constraints, Runtime, Metrics.
-2. Fill `## Metrics` before running persist. Required keys: `platform`, `model`, `input_tokens`, `output_tokens`, `cost_usd`, `amp_credits`, `spend_source`. Use `unknown` for unknown numbers — never invent `0`. Do not set `spend_source: self-report` when tokens are `unknown`. `--model` / `model` is the LLM product id (example `cursor-grok-4.6-xhigh-fast`); family `cursor-grok-4.6` is only a fallback; the CLI takes the product id from hook sources when they exist; Closed role MAY have a sentence after `—`; metrics stores the canonical token. `metrics.json` records what the CLI resolved.
+2. Fill `## Metrics` before persist: `platform`, `model`, `input_tokens`, `output_tokens`, `cost_usd`, `amp_credits`, `spend_source`. `platform` and product-id `model` are required and never `unknown`; unknown numbers use `unknown`, never invented `0`. Do not set self-report when all numbers are unknown. Put decisions in `## Decisions`; only the CLI writes `decisions.md`.
 3. `npx agent-orchestrator-kit handoff <name> --model <llm-product-id>` — require exit 0 (appends non-empty Decisions into append-only `openspec/changes/<name>/decisions.md`, upserts absolute-path Memory JSON, records the session into `openspec/changes/<name>/metrics.json`, prints the expanded prompt on stdout). `--model` is the LLM product id of this chat (`claude-opus-5`, `claude-fable-5`, `gpt-5.6-sol`, `cursor-grok-4.6-xhigh-fast`, `accounts/fireworks/models/glm-5p2`) — NEVER pass a Closed role, a subagent name, or an Amp **mode** (`low`, `medium`, `high`, `ultra`) as `--model`. The parent SHOULD still pass `--model`. The parent MUST NOT guess tokens. Persist collects spend for the client locked at restore (Amp: `amp threads export` + local threads; Cursor: hook file; Claude: JSONL). `--input-tokens` / `--output-tokens` / `--total-tokens` / `--cost-usd` override session-level totals only and do not wipe platform maps; they do not rewrite `## Metrics`. Optional `--platform cursor|claude|amp` or `AOK_PLATFORM`. Optional `--collect` runs all three adapters, not only the locked client. The same `npx agent-orchestrator-kit handoff <name>` works in Cursor, Claude Code, and Amp. `decisions.md` is the git canon of change decisions; Memory `Decision:*` is a file→Memory mirror only. Cloud sessions pass `--runtime cloud` (or set `AOK_RUNTIME=cloud` / `AOK_AGENT_ID` in the cloud-agent environment).
 4. Spawn `session-handoff` in persist mode ONLY if step 3 failed (Amp: isolated `subagent-session-handoff`). Fallback, never routine.
 5. Memory MCP is an optional mirror: if tools are available, update `Change:<name>`, `Handoff:<name>`, `Decision:*` in one call; unavailability never blocks closing.
 6. Paste CLI stdout as one fenced block. First line `/opsx:…`. Body uses `project.agent_language`. Self-contained (Done/Decisions/Blocked/spawn/HARD STOP). No banner.
 7. If runtime is cloud: after persist, `git add openspec/changes/<name>/` → `git commit` → `git push` → `npx agent-orchestrator-kit handoff <name> --cloud-check` (exit 0 required). Closing without this is an incomplete handoff. Persist prints these steps on stderr; the CLI never runs `git commit` / `git push`.
-8. Stop. Next role = new chat.
+8. Stop. Next role and any out-of-OpenSpec hotfix = new chat. Never run full persist twice; regenerate the prompt only with `handoff <name> --no-metrics`.
 
 ## Archive exception
 `npx agent-orchestrator-kit archive <name>` writes the final `handoff.md` (`next_command: none`) in the archive folder and upserts memory itself. After a successful archive no fenced next-prompt is required — the pipeline is complete.

package/templates/.agents/skills/agent-orchestration/SKILL.md

@@ -109,7 +109,7 @@ Before apply, check `.agents/orchestrator.yaml`:
 - `require_spec_review: true` → apply MUST find `review.md` with `Verdict: APPROVE` or Approve in session
 - `require_spec_review: false` → apply allowed directly (mvp / quick mode)
 
-If Request Changes — fix artifacts, re-run `/opsx:review`.
+If Request Changes — run `/opsx:propose <name>` to fix the punch list, then a new `/opsx:review`.
 
 This is no longer only a chat convention: `npx agent-orchestrator-kit gate-check` runs in CI (both `agent-verify.yml` fragments) and fails the pipeline if `src/` changed without an approved `review.md` — a forgotten or skipped review is caught at merge time, not just at apply time. When `require_design_brief: true`, the same command also requires `design-brief.md` (or `Design: none` in `proposal.md`).
 
@@ -146,11 +146,11 @@ Archive is one deterministic CLI call — `npx agent-orchestrator-kit archive <n
 
 **End of each session (HARD STOP — you are NOT done):**
 1. Write `openspec/changes/<name>/handoff.md` in the parent using the template below, including `## Metrics`.
-2. Fill `## Metrics` (`platform`, `model`, `input_tokens`, `output_tokens`, `cost_usd`, `amp_credits`, `spend_source`) before persist. Use `unknown` for unknown numbers — never invent `0`. Do not set `spend_source: self-report` when tokens are `unknown`. `--model` / `model` is the LLM product id (example `cursor-grok-4.6-xhigh-fast`); family `cursor-grok-4.6` is only a fallback; the CLI takes the product id from hook sources when they exist; Closed role MAY have a sentence after `—`; metrics stores the canonical token.
+2. Fill `## Metrics` before persist. `platform` and product-id `model` are required and never `unknown`; unknown numbers use `unknown`, never invented `0`. Put decisions in `## Decisions`; only the CLI writes `decisions.md`.
 3. Run `npx agent-orchestrator-kit handoff <name> --model <llm-product-id>` and require exit 0. `--model` is the LLM product id of this chat (`claude-opus-5`, `claude-fable-5`, `gpt-5.6-sol`, `cursor-grok-4.6-xhigh-fast`) — NEVER pass a Closed role (`Architect`, `Implementer`, `Explorer`) or a subagent name (`spec-architect`, `session-handoff`) as `--model`. The parent SHOULD still pass `--model`. The parent MUST NOT guess tokens. `--input-tokens` / `--output-tokens` / `--total-tokens` / `--cost-usd` override session-level totals only and do not wipe platform maps or rewrite `## Metrics`. Optional `--platform cursor|claude|amp` or `AOK_PLATFORM`. Optional `--collect` also runs local spend adapters. The same command works in Cursor, Claude Code, and Amp and MUST NOT require Cursor SDK, a Claude `/cost` parser, or an Amp billing API as a required step. The CLI appends non-empty Decisions into append-only `openspec/changes/<name>/decisions.md` (the git canon), upserts Memory JSON with an absolute path (`Decision:*` is a file→Memory mirror only), and prints the expanded self-contained prompt on stdout. Spawn `session-handoff` in persist mode ONLY if this CLI step failed.
 4. If Memory MCP tools are available, mirror `Change:<name>`, `Handoff:<name>`, and new `Decision:<topic>` entities in one call — optional; its absence never blocks closing.
 5. Paste the CLI stdout as one fenced next-session prompt. First line is `/opsx:<next> <name>`; body uses `project.agent_language`; keep Done/Decisions/Blocked/spawn/HARD STOP complete. No banner. Do not emit a thin “read Memory” stub.
-6. Do not start the next phase in this chat. If apply, include build/lint status in the persisted Done section.
+6. Do not start the next phase in this chat. Never run full persist twice; regenerate the prompt only with `handoff <name> --no-metrics`. Any out-of-OpenSpec hotfix after persist requires a new chat. If apply, include build/lint status in Done.
 
 `handoff.md` template:
 
@@ -257,12 +257,13 @@ Before declaring a session closed, the parent MUST, in order: (1) write `openspe
 | No archive after merge | Next propose has stale domain specs |
 | Strong model on lint fixes | 5–10x cost with no quality gain |
 | Skip Memory MCP / skip `handoff` CLI | Next thread has no context; Amp looks like it “ignored the rules” |
+| one-finding review loop | fragments defects across many propose/review sessions |
 
 ## Metrics (health check per change)
 
 - Sessions: 4–8 (not 1 marathon, not 20 micro-sessions)
 - Apply iterations to PR: ≤ 2
-- Spec review loops: ≤ 1
+- Spec review discovery loops: ≤ 2 (optional Tier 1 structural RC plus one semantic Tier 2 RC; a confirmation APPROVE after an exhaustive propose does not count as a discovery loop)
 - Tasks rework: ≤ 10%
 
 If apply iterations > 2 → problem is in Architect or Reviewer, not Implementer.

package/templates/.agents/skills/openspec-propose/SKILL.md

@@ -35,6 +35,12 @@ When ready to implement, run /opsx:apply
 
 Each task must be self-contained for a blind implementer — executable without reading design.md. `Files:` paths must exist unless prefixed with `new file:`. Lint: `npx agent-orchestrator-kit gate-check --tasks <name>` (mode via `pipeline.task_contract: warn|strict|off`).
 
+On re-propose after `review.md` Verdict REQUEST CHANGES, the conductor MUST pass `review.md` (path + verdict + Required Before Apply list) in the `spec-architect` spawn prompt and verify the report addresses every item; the parent MUST NOT itself edit proposal/design/specs/tasks. Exception: the structure-only propose trigger is the exact line
+
+**Source:** gate-check
+
+plus the absence of `## Checklist`; then fix only those gate-check errors.
+
 **Steps**
 
 1. **If no clear input provided, ask what they want to build**

package/templates/.agents/subagents/openspec-guide.md

@@ -15,8 +15,9 @@ On every invocation:
 4. Map what you find to the correct next command:
    - No `proposal.md` yet → `/opsx:propose <name>`
    - `require_design_brief: true`, UI-touching change, no `design-brief.md`, no `Design: none` in `proposal.md` → `/opsx:design <name>`
-   - `proposal.md` exists but no `review.md` with `Verdict: APPROVE` → `/opsx:review <name>` (must run in a separate read-only session)
-   - `review.md` says APPROVE but `tasks.md` has unchecked `- [ ]` items → `/opsx:apply <name>`
+   - `proposal.md` exists but no `review.md` → `/opsx:review <name>` (must run in a separate read-only session)
+   - `review.md` contains `Verdict: REQUEST CHANGES` → `/opsx:propose <name>`
+   - `review.md` has `Verdict: APPROVE` but `tasks.md` has unchecked `- [ ]` items → `/opsx:apply <name>`
    - All tasks `[x]` and review approved → ready to archive, suggest `/opsx:archive <name>` (or note that GitLab/GitHub CI auto-archives after merge if `archive_after_merge: true`)
 5. If a CI gate (`gate-check`, `verify-openspec-pr`) is failing, reproduce the check locally (`npx agent-orchestrator-kit gate-check <name>`, `npm run verify:openspec:pr`) and quote the exact failing reason from its output — don't guess.
 6. If `pipeline.max_active_changes` is exceeded, say so explicitly and name which changes are over the limit.

package/templates/.agents/subagents/session-handoff.md

@@ -22,7 +22,7 @@ Use when the parent's restore failed (CLI restore and handoff.md both unavailabl
 Use when the parent's persist failed (`npx agent-orchestrator-kit handoff <name>` did not exit 0). A session is not closed until persist succeeds.
 
 1. Write or update `openspec/changes/<name>/handoff.md` with every required section: Closed role, Change, Done, Decisions, Blocked, Next command, Next role, Attach, Subagents to spawn, Constraints, Runtime, Metrics.
-2. Fill `## Metrics` (`platform`, `model`, `input_tokens`, `output_tokens`, `cost_usd`, `amp_credits`, `spend_source`) before persist. Use `unknown` for unknown numbers — never invent `0`. Do not set `spend_source: self-report` when tokens are `unknown`. `--model` / `model` is the LLM product id (example `cursor-grok-4.6-xhigh-fast`); family `cursor-grok-4.6` is only a fallback; the CLI takes the product id from hook sources when they exist; Closed role MAY have a sentence after `—`; metrics stores the canonical token. The CLI does not overwrite `## Metrics` with resolved values; `metrics.json` records what landed.
+2. Fill `## Metrics` before persist. `platform` and product-id `model` are required and never `unknown`; unknown numbers use `unknown`, never invented `0`. Put decisions in `## Decisions`; only the CLI writes `decisions.md`.
 3. Run `npx agent-orchestrator-kit handoff <name> --model <llm-product-id>` and require exit 0. `--model` is the LLM product id of this chat (`claude-opus-5`, `claude-fable-5`, `gpt-5.6-sol`, `cursor-grok-4.6-xhigh-fast`) — NEVER pass a Closed role (`Architect`, `Implementer`, `Explorer`) or a subagent name (`spec-architect`, `session-handoff`) as `--model`. The parent SHOULD still pass `--model`. The parent MUST NOT guess tokens. `--input-tokens` / `--output-tokens` / `--total-tokens` / `--cost-usd` override session-level totals only and do not wipe platform maps. Optional `--platform cursor|claude|amp` or `AOK_PLATFORM`. Optional `--collect` also runs local spend adapters. The same command works in Cursor, Claude Code, and Amp and MUST NOT require Cursor SDK, a Claude `/cost` parser, or an Amp billing API as a required step. This appends non-empty Decisions into append-only `openspec/changes/<name>/decisions.md` (git canon), upserts `.cursor/memory.json` using an absolute path (`Decision:*` mirrors that file, never the reverse), and prints the expanded next-session prompt on stdout. Cloud sessions pass `--runtime cloud` (or `AOK_RUNTIME` / `AOK_AGENT_ID`).
 4. If Memory MCP tools are available, also create/update `Change:<name>`, `Handoff:<name>`, and each `Decision:<topic>` to match `decisions.md`. MCP failure is not a blocker after the CLI succeeds.
 5. Put the CLI stdout prompt (first line `/opsx:…`) into **Next prompt** unchanged. Do not shorten it. Do not add a banner.
@@ -33,6 +33,7 @@ Use when the parent's persist failed (`npx agent-orchestrator-kit handoff <name>
 - Write session artifacts only to git-tracked paths (never `/tmp`, never gitignored caches).
 - Do NOT edit `src/`, tests, main specs, `tasks.md` checkboxes, or phase artifacts (`proposal.md`, `review.md`, `design-brief.md`) except `handoff.md`.
 - Do NOT start the next OpenSpec phase.
+- Never run full persist twice. Regenerate a prompt only with `handoff <name> --no-metrics`; after persist, move any next-role or out-of-OpenSpec work to a new chat.
 - Do NOT return a thin prompt. The next thread must be able to run if Memory MCP is ignored.
 - Stop as blocked when the change name or next command cannot be resolved.
 

package/templates/.agents/subagents/spec-architect.md

@@ -11,7 +11,12 @@ Workflow:
 2. Create or update `proposal.md`, `design.md`, `specs/<capability>/spec.md`, and `tasks.md` using the repository's OpenSpec schema and conventions.
 3. Keep requirements testable: each requirement uses SHALL/MUST language and includes concrete scenarios.
 4. Make tasks ordered, independently verifiable, and traceable to the design and delta specs. Every task MUST follow the task contract: indented `Files:` (existing paths, or `new file:` prefix for new ones), `Do:` (concrete change, no vague wording like "as needed" / "if necessary" / "as appropriate"), and `Done-when:` (verifiable condition or command). Each task must be self-contained for a blind implementer without reading design.md.
-5. Report which validation command the conductor should run; do not cross into review or implementation.
+5. On re-propose after REQUEST CHANGES, the architect MUST read `review.md`, fix every Required Before Apply item, and re-scan the same defect class in proposal.md, design.md, tasks.md, and all delta specs (LLM-only classes only: another task whose `Do:` is not executable without design.md; another design behaviour with no delta requirement; another proposal↔tasks drift; another referenced heading/path that does not exist); do not stop after the listed items; Tier 1 classes NEVER enter this rescan. Exception: the structure-only propose trigger is the exact line
+
+**Source:** gate-check
+
+plus the absence of `## Checklist`; then fix only those gate-check errors.
+6. Report which validation command the conductor should run; do not cross into review or implementation.
 
 Rules:
 

package/templates/.agents/subagents/spec-archiver.md

@@ -9,7 +9,7 @@ Workflow:
 
 1. Read `.agents/orchestrator.yaml`, the complete change, review verdict, task state, and verification/merge evidence supplied by the conductor.
 2. Refuse to archive unless required review is approved, all tasks are complete, and the configured merge/CI gate is satisfied.
-3. Fill `## Metrics` in the change `handoff.md` only when reporting Archiver-specific numbers. Use `unknown` for unknown numbers — never invent `0`. Do not set `spend_source: self-report` when tokens are `unknown`. `--model` / `model` is the LLM product id (example `cursor-grok-4.6-xhigh-fast`); family `cursor-grok-4.6` is only a fallback; the CLI takes the product id from hook sources when they exist; Closed role MAY have a sentence after `—`; metrics stores the canonical token. Do not copy the previous apply session. The CLI auto-collects the locked client into the Archiver session.
+3. Fill `## Metrics` with Archiver-only numbers before archive. `platform` and product-id `model` are required and never `unknown`; unknown numbers use `unknown`, never invented `0`. Put decisions in `## Decisions`; only the CLI writes `decisions.md`. Do not copy the apply session.
 4. Run `npx agent-orchestrator-kit archive <name>` so delta requirements are merged into main specs, the change moves to the dated archive path, and stdout prints the change-wide metrics summary (by phase / by platform / by model).
 5. Run strict validation after the move and report the resulting archive path and modified main specs.
 
@@ -18,6 +18,7 @@ Rules:
 - Do NOT edit `src/`, tests, CI, or implementation files.
 - Do NOT add new features, redesign requirements, or repair incomplete implementation during archive.
 - Do NOT manually discard delta requirements to make validation pass.
+- Do not run archive/persist twice; after success, stop and move out-of-OpenSpec work to a new chat. Prompt regeneration before archive uses `handoff <name> --no-metrics`.
 - If archive prerequisites are missing, return `blocked` with the exact unmet gate.
 
 Return exactly this report contract: