agent-orchestrator-kit 0.13.0 → 0.14.1

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/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,10 +546,10 @@ function collectAmpCli(ctx) {
     if (id && !ids.includes(id)) ids.push(id);
   };
   push(ampThreadId);
-  if (ctx.listRecentAmpThreads !== false) {
+  if (ctx.listRecentAmpThreads === true) {
     push(ampCurrentThreadId(env));
   }
-  if (!ids.length && ctx.listRecentAmpThreads !== false) {
+  if (!ids.length && ctx.listRecentAmpThreads === true) {
     for (const id of listRecentAmpThreadIds(ctx)) push(id);
   }
   const sources = [];
@@ -529,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';
@@ -537,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,
@@ -708,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 === ''
         ? ''
@@ -809,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 = [];
@@ -823,6 +871,7 @@ export function collectSpend(options = {}) {
     windowEnd,
     existing,
     existingSources,
+    existingSourceTotals,
     env,
     homedir,
     notes,
@@ -834,6 +883,9 @@ export function collectSpend(options = {}) {
     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 = [];
@@ -867,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.13.0",
+  "version": "0.14.1",
   "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/.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:

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

@@ -13,7 +13,8 @@ Workflow:
    - conflicts with existing `openspec/specs/` requirements;
    - scope creep vs proposal Non-goals;
    - task self-sufficiency: a blind implementer can execute each task from Files/Do/Done-when alone, without design.md.
-3. Write `review.md` with findings ordered by severity and exactly one verdict: `APPROVE` or `REQUEST CHANGES`.
+   MUST NOT stop at the first blocking finding. Finish the full LLM checklist and a complete artifact 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.
+3. MUST read the existing `review.md` before overwriting it. Write `review.md` with findings ordered by severity and exactly one verdict: `APPROVE` or `REQUEST CHANGES`. REQUEST CHANGES and re-review MUST use headings Checklist, Findings (Blocker / Major / Minor), Required Before Apply, Previous findings.
 4. On APPROVE, also write `apply-notes.md` (≤ 20 lines): critical constraints, pitfalls, what NOT to touch, verification commands. It is the second and last file you may write.
 5. Approve only when artifacts are implementable without material guessing.
 
@@ -23,6 +24,9 @@ Rules:
 - Do NOT implement fixes found during review.
 - Do NOT substitute for `code-reviewer`; that agent reviews the implementation diff after apply.
 - Do NOT approve based only on Tier 1 passing; verify semantics and repository references.
+- 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.
+- Cosmetics stay out of Required Before Apply.
+- Later review MUST carry prior Required Before Apply into Previous findings and MUST still 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 lists only the first leftover.
 
 Return exactly this report contract:
 

package/templates/AGENTS.md

@@ -25,7 +25,7 @@ Routing table, HARD STOP, and CLI forms: `.agents/rules/` (`agent-orchestration`
 
 Session Start / Exit are **parent-driven** — canonical protocol in `.agents/rules/session-handoff.mdc`. Start: `status` → `handoff --restore` → `handoff.md` fallback. Exit HARD STOP: parent writes `handoff.md` including `## Metrics` (use `unknown` when a value is missing) → `npx agent-orchestrator-kit handoff <name>` (exit 0; optional `--collect`) → paste the CLI `/opsx:*` prompt. `session-handoff` subagent = fallback only. Do not start the next phase here.
 
-Quality gates: `gate-check --tasks <name>` lints the task contract (Files/Do/Done-when, `pipeline.task_contract: warn|strict|off`); `gate-check --review <name>` is deterministic Tier 1 of review — spec-reviewer (Tier 2) is spawned only after it passes and writes `apply-notes.md` on APPROVE.
+Quality gates: `gate-check --tasks <name>` lints the task contract (Files/Do/Done-when, `pipeline.task_contract: warn|strict|off`); `gate-check --review <name>` is deterministic Tier 1 of review — spec-reviewer (Tier 2) is spawned only after it passes and writes `apply-notes.md` on APPROVE. 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). Anti-pattern: one-finding review loop — fragments defects across many propose/review sessions.
 
 ## Hard rules
 - One active change (unless mvp profile).

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: