cleargate 0.8.1 → 0.10.0

package/dist/lib/ledger.cjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/lib/ledger.ts
+var ledger_exports = {};
+__export(ledger_exports, {
+  sumDeltas: () => sumDeltas
+});
+module.exports = __toCommonJS(ledger_exports);
+function isTokenCounts(v) {
+  if (typeof v !== "object" || v === null) return false;
+  const obj = v;
+  return typeof obj["input"] === "number" && typeof obj["output"] === "number" && typeof obj["cache_creation"] === "number" && typeof obj["cache_read"] === "number";
+}
+function hasDelta(row) {
+  return isTokenCounts(row["delta"]);
+}
+function zeroCounts() {
+  return { input: 0, output: 0, cache_creation: 0, cache_read: 0 };
+}
+function addCounts(a, b) {
+  return {
+    input: a.input + b.input,
+    output: a.output + b.output,
+    cache_creation: a.cache_creation + b.cache_creation,
+    cache_read: a.cache_read + b.cache_read
+  };
+}
+function lastRowTrickForFlatRows(rows) {
+  const sessionMap = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    const sessionId = typeof row["session_id"] === "string" ? row["session_id"] : "(unknown)";
+    const existing = sessionMap.get(sessionId);
+    if (!existing) {
+      sessionMap.set(sessionId, row);
+    } else {
+      const existingTs = typeof existing["ts"] === "string" ? existing["ts"] : "";
+      const rowTs = typeof row["ts"] === "string" ? row["ts"] : "";
+      if (rowTs > existingTs) {
+        sessionMap.set(sessionId, row);
+      }
+    }
+  }
+  let totals = zeroCounts();
+  for (const row of sessionMap.values()) {
+    totals = addCounts(totals, {
+      input: typeof row["input"] === "number" ? row["input"] : 0,
+      output: typeof row["output"] === "number" ? row["output"] : 0,
+      cache_creation: typeof row["cache_creation"] === "number" ? row["cache_creation"] : 0,
+      cache_read: typeof row["cache_read"] === "number" ? row["cache_read"] : 0
+    });
+  }
+  return totals;
+}
+function sumDeltas(rows) {
+  const validRows = [];
+  for (const raw of rows) {
+    if (typeof raw === "object" && raw !== null && !Array.isArray(raw)) {
+      validRows.push(raw);
+    } else {
+      console.warn("[ledger.ts] sumDeltas: skipping malformed row (not an object):", raw);
+    }
+  }
+  if (validRows.length === 0) {
+    return { totals: zeroCounts(), format: "delta" };
+  }
+  const deltaRows = validRows.filter(hasDelta);
+  const flatRows = validRows.filter((r) => !hasDelta(r));
+  if (flatRows.length === 0) {
+    let totals2 = zeroCounts();
+    for (const row of deltaRows) {
+      const d = row["delta"];
+      totals2 = addCounts(totals2, d);
+    }
+    return { totals: totals2, format: "delta" };
+  }
+  if (deltaRows.length === 0) {
+    const totals2 = lastRowTrickForFlatRows(flatRows);
+    return {
+      totals: totals2,
+      format: "pre-0.9.0",
+      pre_v2_caveat: "**Ledger format note:** This sprint's token-ledger.jsonl uses pre-0.9.0 flat-field rows; cost is computed via the last-row-per-session trick (reconciliation accuracy \xB1N \xD7 real-cost where N = SubagentStop fires per session)."
+    };
+  }
+  let totals = zeroCounts();
+  for (const row of deltaRows) {
+    const d = row["delta"];
+    totals = addCounts(totals, d);
+  }
+  const flatTotals = lastRowTrickForFlatRows(flatRows);
+  totals = addCounts(totals, flatTotals);
+  const caveat = `Mixed format ledger: ${deltaRows.length} delta rows + ${flatRows.length} pre-0.9.0 rows; flat segment uses last-row trick.`;
+  return {
+    totals,
+    format: "mixed",
+    pre_v2_caveat: caveat
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  sumDeltas
+});
+//# sourceMappingURL=ledger.cjs.map

package/dist/lib/ledger.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/lib/ledger.ts"],"sourcesContent":["/**\n * ledger.ts — CR-018\n *\n * Sprint-wide cost math: parses token-ledger.jsonl rows and sums delta tokens\n * for the Reporter agent. Distinct from ledger-reader.ts (per-work-item\n * attribution lookup); this file provides sumDeltas() for sprint-total cost.\n *\n * Format detection handles three cases:\n *   'delta'     — all rows carry delta.* blocks (post-0.9.0)\n *   'pre-0.9.0' — all rows use flat input/output/cache_* fields (pre-0.9.0)\n *   'mixed'     — some rows have delta, others don't (SPRINT-15 cutover window)\n */\n\n// ─── Public types ─────────────────────────────────────────────────────────────\n\n/** Token counts block (used in both delta and session_total). */\nexport interface TokenCounts {\n  input: number;\n  output: number;\n  cache_creation: number;\n  cache_read: number;\n}\n\n/** Full post-0.9.0 ledger row shape. */\nexport interface LedgerRowV2 {\n  ts: string;\n  sprint_id: string;\n  story_id: string;\n  work_item_id: string;\n  agent_type: string;\n  session_id: string;\n  transcript?: string;\n  sentinel_started_at?: string;\n  delta_from_turn?: number;\n  delta: TokenCounts;\n  session_total: TokenCounts;\n  model: string;\n  turns: number;\n}\n\n/** Result returned by sumDeltas(). */\nexport interface SumResult {\n  /** Aggregated token totals across all rows (using appropriate format). */\n  totals: TokenCounts;\n  /** How the totals were computed. */\n  format: 'delta' | 'pre-0.9.0' | 'mixed';\n  /**\n   * Present when format is 'pre-0.9.0' or 'mixed'.\n   * Reporter should paste this verbatim into REPORT.md §3.\n   */\n  pre_v2_caveat?: string;\n}\n\n// ─── Internal helpers ─────────────────────────────────────────────────────────\n\nfunction isTokenCounts(v: unknown): v is TokenCounts {\n  if (typeof v !== 'object' || v === null) return false;\n  const obj = v as Record<string, unknown>;\n  return (\n    typeof obj['input'] === 'number' &&\n    typeof obj['output'] === 'number' &&\n    typeof obj['cache_creation'] === 'number' &&\n    typeof obj['cache_read'] === 'number'\n  );\n}\n\nfunction hasDelta(row: Record<string, unknown>): boolean {\n  return isTokenCounts(row['delta']);\n}\n\nfunction zeroCounts(): TokenCounts {\n  return { input: 0, output: 0, cache_creation: 0, cache_read: 0 };\n}\n\nfunction addCounts(a: TokenCounts, b: TokenCounts): TokenCounts {\n  return {\n    input: a.input + b.input,\n    output: a.output + b.output,\n    cache_creation: a.cache_creation + b.cache_creation,\n    cache_read: a.cache_read + b.cache_read,\n  };\n}\n\n/**\n * Last-row-per-session trick for pre-0.9.0 flat-field rows.\n * Groups rows by session_id, takes the row with max ts per group,\n * and sums the flat input/output/cache_* fields across those last rows.\n */\nfunction lastRowTrickForFlatRows(rows: Record<string, unknown>[]): TokenCounts {\n  const sessionMap = new Map<string, Record<string, unknown>>();\n\n  for (const row of rows) {\n    const sessionId = typeof row['session_id'] === 'string' ? row['session_id'] : '(unknown)';\n    const existing = sessionMap.get(sessionId);\n    if (!existing) {\n      sessionMap.set(sessionId, row);\n    } else {\n      const existingTs = typeof existing['ts'] === 'string' ? existing['ts'] : '';\n      const rowTs = typeof row['ts'] === 'string' ? row['ts'] : '';\n      if (rowTs > existingTs) {\n        sessionMap.set(sessionId, row);\n      }\n    }\n  }\n\n  let totals = zeroCounts();\n  for (const row of sessionMap.values()) {\n    totals = addCounts(totals, {\n      input: typeof row['input'] === 'number' ? row['input'] : 0,\n      output: typeof row['output'] === 'number' ? row['output'] : 0,\n      cache_creation: typeof row['cache_creation'] === 'number' ? row['cache_creation'] : 0,\n      cache_read: typeof row['cache_read'] === 'number' ? row['cache_read'] : 0,\n    });\n  }\n  return totals;\n}\n\n// ─── Public API ───────────────────────────────────────────────────────────────\n\n/**\n * Compute sprint-wide token totals from an array of raw ledger rows (parsed JSONL).\n *\n * Format-detection algorithm (mandatory):\n *   1. Classify each row: has `delta` object with 4 numeric fields → v2; else → flat/legacy.\n *   2. All v2       → format='delta',    sum delta.* directly.\n *   3. All flat     → format='pre-0.9.0', group by session_id, last-row-per-session trick.\n *   4. Mixed        → format='mixed',    delta rows contribute delta.*; flat rows within\n *                     each session use last-row trick scoped to flat rows only.\n *\n * Malformed or unrecognisable rows are skipped with a console.warn.\n *\n * @param rows  Array of parsed JSON objects (unknown type for defensive parsing).\n */\nexport function sumDeltas(rows: unknown[]): SumResult {\n  // Filter to recognisable objects; skip malformed rows.\n  const validRows: Record<string, unknown>[] = [];\n  for (const raw of rows) {\n    if (typeof raw === 'object' && raw !== null && !Array.isArray(raw)) {\n      validRows.push(raw as Record<string, unknown>);\n    } else {\n      console.warn('[ledger.ts] sumDeltas: skipping malformed row (not an object):', raw);\n    }\n  }\n\n  if (validRows.length === 0) {\n    return { totals: zeroCounts(), format: 'delta' };\n  }\n\n  const deltaRows = validRows.filter(hasDelta);\n  const flatRows = validRows.filter((r) => !hasDelta(r));\n\n  // All rows are v2 (delta) format\n  if (flatRows.length === 0) {\n    let totals = zeroCounts();\n    for (const row of deltaRows) {\n      const d = row['delta'] as TokenCounts;\n      totals = addCounts(totals, d);\n    }\n    return { totals, format: 'delta' };\n  }\n\n  // All rows are pre-0.9.0 flat format\n  if (deltaRows.length === 0) {\n    const totals = lastRowTrickForFlatRows(flatRows);\n    return {\n      totals,\n      format: 'pre-0.9.0',\n      pre_v2_caveat:\n        '**Ledger format note:** This sprint\\'s token-ledger.jsonl uses pre-0.9.0 flat-field rows; ' +\n        'cost is computed via the last-row-per-session trick ' +\n        '(reconciliation accuracy ±N × real-cost where N = SubagentStop fires per session).',\n    };\n  }\n\n  // Mixed format: both delta rows and flat rows in same ledger (e.g. SPRINT-15 cutover)\n  // Delta rows → sum delta.*\n  // Flat rows  → group by session_id, last-row trick (scoped to flat rows only)\n  let totals = zeroCounts();\n\n  // Sum delta rows directly\n  for (const row of deltaRows) {\n    const d = row['delta'] as TokenCounts;\n    totals = addCounts(totals, d);\n  }\n\n  // Apply last-row trick to flat rows\n  const flatTotals = lastRowTrickForFlatRows(flatRows);\n  totals = addCounts(totals, flatTotals);\n\n  const caveat =\n    `Mixed format ledger: ${deltaRows.length} delta rows + ${flatRows.length} pre-0.9.0 rows; ` +\n    `flat segment uses last-row trick.`;\n\n  return {\n    totals,\n    format: 'mixed',\n    pre_v2_caveat: caveat,\n  };\n}\n"],"mappings":"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","names":["totals"]}

package/dist/lib/ledger.d.cts

@@ -0,0 +1,64 @@
+/**
+ * ledger.ts — CR-018
+ *
+ * Sprint-wide cost math: parses token-ledger.jsonl rows and sums delta tokens
+ * for the Reporter agent. Distinct from ledger-reader.ts (per-work-item
+ * attribution lookup); this file provides sumDeltas() for sprint-total cost.
+ *
+ * Format detection handles three cases:
+ *   'delta'     — all rows carry delta.* blocks (post-0.9.0)
+ *   'pre-0.9.0' — all rows use flat input/output/cache_* fields (pre-0.9.0)
+ *   'mixed'     — some rows have delta, others don't (SPRINT-15 cutover window)
+ */
+/** Token counts block (used in both delta and session_total). */
+interface TokenCounts {
+    input: number;
+    output: number;
+    cache_creation: number;
+    cache_read: number;
+}
+/** Full post-0.9.0 ledger row shape. */
+interface LedgerRowV2 {
+    ts: string;
+    sprint_id: string;
+    story_id: string;
+    work_item_id: string;
+    agent_type: string;
+    session_id: string;
+    transcript?: string;
+    sentinel_started_at?: string;
+    delta_from_turn?: number;
+    delta: TokenCounts;
+    session_total: TokenCounts;
+    model: string;
+    turns: number;
+}
+/** Result returned by sumDeltas(). */
+interface SumResult {
+    /** Aggregated token totals across all rows (using appropriate format). */
+    totals: TokenCounts;
+    /** How the totals were computed. */
+    format: 'delta' | 'pre-0.9.0' | 'mixed';
+    /**
+     * Present when format is 'pre-0.9.0' or 'mixed'.
+     * Reporter should paste this verbatim into REPORT.md §3.
+     */
+    pre_v2_caveat?: string;
+}
+/**
+ * Compute sprint-wide token totals from an array of raw ledger rows (parsed JSONL).
+ *
+ * Format-detection algorithm (mandatory):
+ *   1. Classify each row: has `delta` object with 4 numeric fields → v2; else → flat/legacy.
+ *   2. All v2       → format='delta',    sum delta.* directly.
+ *   3. All flat     → format='pre-0.9.0', group by session_id, last-row-per-session trick.
+ *   4. Mixed        → format='mixed',    delta rows contribute delta.*; flat rows within
+ *                     each session use last-row trick scoped to flat rows only.
+ *
+ * Malformed or unrecognisable rows are skipped with a console.warn.
+ *
+ * @param rows  Array of parsed JSON objects (unknown type for defensive parsing).
+ */
+declare function sumDeltas(rows: unknown[]): SumResult;
+
+export { type LedgerRowV2, type SumResult, type TokenCounts, sumDeltas };

package/dist/lib/ledger.d.ts

@@ -0,0 +1,64 @@
+/**
+ * ledger.ts — CR-018
+ *
+ * Sprint-wide cost math: parses token-ledger.jsonl rows and sums delta tokens
+ * for the Reporter agent. Distinct from ledger-reader.ts (per-work-item
+ * attribution lookup); this file provides sumDeltas() for sprint-total cost.
+ *
+ * Format detection handles three cases:
+ *   'delta'     — all rows carry delta.* blocks (post-0.9.0)
+ *   'pre-0.9.0' — all rows use flat input/output/cache_* fields (pre-0.9.0)
+ *   'mixed'     — some rows have delta, others don't (SPRINT-15 cutover window)
+ */
+/** Token counts block (used in both delta and session_total). */
+interface TokenCounts {
+    input: number;
+    output: number;
+    cache_creation: number;
+    cache_read: number;
+}
+/** Full post-0.9.0 ledger row shape. */
+interface LedgerRowV2 {
+    ts: string;
+    sprint_id: string;
+    story_id: string;
+    work_item_id: string;
+    agent_type: string;
+    session_id: string;
+    transcript?: string;
+    sentinel_started_at?: string;
+    delta_from_turn?: number;
+    delta: TokenCounts;
+    session_total: TokenCounts;
+    model: string;
+    turns: number;
+}
+/** Result returned by sumDeltas(). */
+interface SumResult {
+    /** Aggregated token totals across all rows (using appropriate format). */
+    totals: TokenCounts;
+    /** How the totals were computed. */
+    format: 'delta' | 'pre-0.9.0' | 'mixed';
+    /**
+     * Present when format is 'pre-0.9.0' or 'mixed'.
+     * Reporter should paste this verbatim into REPORT.md §3.
+     */
+    pre_v2_caveat?: string;
+}
+/**
+ * Compute sprint-wide token totals from an array of raw ledger rows (parsed JSONL).
+ *
+ * Format-detection algorithm (mandatory):
+ *   1. Classify each row: has `delta` object with 4 numeric fields → v2; else → flat/legacy.
+ *   2. All v2       → format='delta',    sum delta.* directly.
+ *   3. All flat     → format='pre-0.9.0', group by session_id, last-row-per-session trick.
+ *   4. Mixed        → format='mixed',    delta rows contribute delta.*; flat rows within
+ *                     each session use last-row trick scoped to flat rows only.
+ *
+ * Malformed or unrecognisable rows are skipped with a console.warn.
+ *
+ * @param rows  Array of parsed JSON objects (unknown type for defensive parsing).
+ */
+declare function sumDeltas(rows: unknown[]): SumResult;
+
+export { type LedgerRowV2, type SumResult, type TokenCounts, sumDeltas };

package/dist/lib/ledger.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+
+// src/lib/ledger.ts
+function isTokenCounts(v) {
+  if (typeof v !== "object" || v === null) return false;
+  const obj = v;
+  return typeof obj["input"] === "number" && typeof obj["output"] === "number" && typeof obj["cache_creation"] === "number" && typeof obj["cache_read"] === "number";
+}
+function hasDelta(row) {
+  return isTokenCounts(row["delta"]);
+}
+function zeroCounts() {
+  return { input: 0, output: 0, cache_creation: 0, cache_read: 0 };
+}
+function addCounts(a, b) {
+  return {
+    input: a.input + b.input,
+    output: a.output + b.output,
+    cache_creation: a.cache_creation + b.cache_creation,
+    cache_read: a.cache_read + b.cache_read
+  };
+}
+function lastRowTrickForFlatRows(rows) {
+  const sessionMap = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    const sessionId = typeof row["session_id"] === "string" ? row["session_id"] : "(unknown)";
+    const existing = sessionMap.get(sessionId);
+    if (!existing) {
+      sessionMap.set(sessionId, row);
+    } else {
+      const existingTs = typeof existing["ts"] === "string" ? existing["ts"] : "";
+      const rowTs = typeof row["ts"] === "string" ? row["ts"] : "";
+      if (rowTs > existingTs) {
+        sessionMap.set(sessionId, row);
+      }
+    }
+  }
+  let totals = zeroCounts();
+  for (const row of sessionMap.values()) {
+    totals = addCounts(totals, {
+      input: typeof row["input"] === "number" ? row["input"] : 0,
+      output: typeof row["output"] === "number" ? row["output"] : 0,
+      cache_creation: typeof row["cache_creation"] === "number" ? row["cache_creation"] : 0,
+      cache_read: typeof row["cache_read"] === "number" ? row["cache_read"] : 0
+    });
+  }
+  return totals;
+}
+function sumDeltas(rows) {
+  const validRows = [];
+  for (const raw of rows) {
+    if (typeof raw === "object" && raw !== null && !Array.isArray(raw)) {
+      validRows.push(raw);
+    } else {
+      console.warn("[ledger.ts] sumDeltas: skipping malformed row (not an object):", raw);
+    }
+  }
+  if (validRows.length === 0) {
+    return { totals: zeroCounts(), format: "delta" };
+  }
+  const deltaRows = validRows.filter(hasDelta);
+  const flatRows = validRows.filter((r) => !hasDelta(r));
+  if (flatRows.length === 0) {
+    let totals2 = zeroCounts();
+    for (const row of deltaRows) {
+      const d = row["delta"];
+      totals2 = addCounts(totals2, d);
+    }
+    return { totals: totals2, format: "delta" };
+  }
+  if (deltaRows.length === 0) {
+    const totals2 = lastRowTrickForFlatRows(flatRows);
+    return {
+      totals: totals2,
+      format: "pre-0.9.0",
+      pre_v2_caveat: "**Ledger format note:** This sprint's token-ledger.jsonl uses pre-0.9.0 flat-field rows; cost is computed via the last-row-per-session trick (reconciliation accuracy \xB1N \xD7 real-cost where N = SubagentStop fires per session)."
+    };
+  }
+  let totals = zeroCounts();
+  for (const row of deltaRows) {
+    const d = row["delta"];
+    totals = addCounts(totals, d);
+  }
+  const flatTotals = lastRowTrickForFlatRows(flatRows);
+  totals = addCounts(totals, flatTotals);
+  const caveat = `Mixed format ledger: ${deltaRows.length} delta rows + ${flatRows.length} pre-0.9.0 rows; flat segment uses last-row trick.`;
+  return {
+    totals,
+    format: "mixed",
+    pre_v2_caveat: caveat
+  };
+}
+export {
+  sumDeltas
+};
+//# sourceMappingURL=ledger.js.map

package/dist/lib/ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/lib/ledger.ts"],"sourcesContent":["/**\n * ledger.ts — CR-018\n *\n * Sprint-wide cost math: parses token-ledger.jsonl rows and sums delta tokens\n * for the Reporter agent. Distinct from ledger-reader.ts (per-work-item\n * attribution lookup); this file provides sumDeltas() for sprint-total cost.\n *\n * Format detection handles three cases:\n *   'delta'     — all rows carry delta.* blocks (post-0.9.0)\n *   'pre-0.9.0' — all rows use flat input/output/cache_* fields (pre-0.9.0)\n *   'mixed'     — some rows have delta, others don't (SPRINT-15 cutover window)\n */\n\n// ─── Public types ─────────────────────────────────────────────────────────────\n\n/** Token counts block (used in both delta and session_total). */\nexport interface TokenCounts {\n  input: number;\n  output: number;\n  cache_creation: number;\n  cache_read: number;\n}\n\n/** Full post-0.9.0 ledger row shape. */\nexport interface LedgerRowV2 {\n  ts: string;\n  sprint_id: string;\n  story_id: string;\n  work_item_id: string;\n  agent_type: string;\n  session_id: string;\n  transcript?: string;\n  sentinel_started_at?: string;\n  delta_from_turn?: number;\n  delta: TokenCounts;\n  session_total: TokenCounts;\n  model: string;\n  turns: number;\n}\n\n/** Result returned by sumDeltas(). */\nexport interface SumResult {\n  /** Aggregated token totals across all rows (using appropriate format). */\n  totals: TokenCounts;\n  /** How the totals were computed. */\n  format: 'delta' | 'pre-0.9.0' | 'mixed';\n  /**\n   * Present when format is 'pre-0.9.0' or 'mixed'.\n   * Reporter should paste this verbatim into REPORT.md §3.\n   */\n  pre_v2_caveat?: string;\n}\n\n// ─── Internal helpers ─────────────────────────────────────────────────────────\n\nfunction isTokenCounts(v: unknown): v is TokenCounts {\n  if (typeof v !== 'object' || v === null) return false;\n  const obj = v as Record<string, unknown>;\n  return (\n    typeof obj['input'] === 'number' &&\n    typeof obj['output'] === 'number' &&\n    typeof obj['cache_creation'] === 'number' &&\n    typeof obj['cache_read'] === 'number'\n  );\n}\n\nfunction hasDelta(row: Record<string, unknown>): boolean {\n  return isTokenCounts(row['delta']);\n}\n\nfunction zeroCounts(): TokenCounts {\n  return { input: 0, output: 0, cache_creation: 0, cache_read: 0 };\n}\n\nfunction addCounts(a: TokenCounts, b: TokenCounts): TokenCounts {\n  return {\n    input: a.input + b.input,\n    output: a.output + b.output,\n    cache_creation: a.cache_creation + b.cache_creation,\n    cache_read: a.cache_read + b.cache_read,\n  };\n}\n\n/**\n * Last-row-per-session trick for pre-0.9.0 flat-field rows.\n * Groups rows by session_id, takes the row with max ts per group,\n * and sums the flat input/output/cache_* fields across those last rows.\n */\nfunction lastRowTrickForFlatRows(rows: Record<string, unknown>[]): TokenCounts {\n  const sessionMap = new Map<string, Record<string, unknown>>();\n\n  for (const row of rows) {\n    const sessionId = typeof row['session_id'] === 'string' ? row['session_id'] : '(unknown)';\n    const existing = sessionMap.get(sessionId);\n    if (!existing) {\n      sessionMap.set(sessionId, row);\n    } else {\n      const existingTs = typeof existing['ts'] === 'string' ? existing['ts'] : '';\n      const rowTs = typeof row['ts'] === 'string' ? row['ts'] : '';\n      if (rowTs > existingTs) {\n        sessionMap.set(sessionId, row);\n      }\n    }\n  }\n\n  let totals = zeroCounts();\n  for (const row of sessionMap.values()) {\n    totals = addCounts(totals, {\n      input: typeof row['input'] === 'number' ? row['input'] : 0,\n      output: typeof row['output'] === 'number' ? row['output'] : 0,\n      cache_creation: typeof row['cache_creation'] === 'number' ? row['cache_creation'] : 0,\n      cache_read: typeof row['cache_read'] === 'number' ? row['cache_read'] : 0,\n    });\n  }\n  return totals;\n}\n\n// ─── Public API ───────────────────────────────────────────────────────────────\n\n/**\n * Compute sprint-wide token totals from an array of raw ledger rows (parsed JSONL).\n *\n * Format-detection algorithm (mandatory):\n *   1. Classify each row: has `delta` object with 4 numeric fields → v2; else → flat/legacy.\n *   2. All v2       → format='delta',    sum delta.* directly.\n *   3. All flat     → format='pre-0.9.0', group by session_id, last-row-per-session trick.\n *   4. Mixed        → format='mixed',    delta rows contribute delta.*; flat rows within\n *                     each session use last-row trick scoped to flat rows only.\n *\n * Malformed or unrecognisable rows are skipped with a console.warn.\n *\n * @param rows  Array of parsed JSON objects (unknown type for defensive parsing).\n */\nexport function sumDeltas(rows: unknown[]): SumResult {\n  // Filter to recognisable objects; skip malformed rows.\n  const validRows: Record<string, unknown>[] = [];\n  for (const raw of rows) {\n    if (typeof raw === 'object' && raw !== null && !Array.isArray(raw)) {\n      validRows.push(raw as Record<string, unknown>);\n    } else {\n      console.warn('[ledger.ts] sumDeltas: skipping malformed row (not an object):', raw);\n    }\n  }\n\n  if (validRows.length === 0) {\n    return { totals: zeroCounts(), format: 'delta' };\n  }\n\n  const deltaRows = validRows.filter(hasDelta);\n  const flatRows = validRows.filter((r) => !hasDelta(r));\n\n  // All rows are v2 (delta) format\n  if (flatRows.length === 0) {\n    let totals = zeroCounts();\n    for (const row of deltaRows) {\n      const d = row['delta'] as TokenCounts;\n      totals = addCounts(totals, d);\n    }\n    return { totals, format: 'delta' };\n  }\n\n  // All rows are pre-0.9.0 flat format\n  if (deltaRows.length === 0) {\n    const totals = lastRowTrickForFlatRows(flatRows);\n    return {\n      totals,\n      format: 'pre-0.9.0',\n      pre_v2_caveat:\n        '**Ledger format note:** This sprint\\'s token-ledger.jsonl uses pre-0.9.0 flat-field rows; ' +\n        'cost is computed via the last-row-per-session trick ' +\n        '(reconciliation accuracy ±N × real-cost where N = SubagentStop fires per session).',\n    };\n  }\n\n  // Mixed format: both delta rows and flat rows in same ledger (e.g. SPRINT-15 cutover)\n  // Delta rows → sum delta.*\n  // Flat rows  → group by session_id, last-row trick (scoped to flat rows only)\n  let totals = zeroCounts();\n\n  // Sum delta rows directly\n  for (const row of deltaRows) {\n    const d = row['delta'] as TokenCounts;\n    totals = addCounts(totals, d);\n  }\n\n  // Apply last-row trick to flat rows\n  const flatTotals = lastRowTrickForFlatRows(flatRows);\n  totals = addCounts(totals, flatTotals);\n\n  const caveat =\n    `Mixed format ledger: ${deltaRows.length} delta rows + ${flatRows.length} pre-0.9.0 rows; ` +\n    `flat segment uses last-row trick.`;\n\n  return {\n    totals,\n    format: 'mixed',\n    pre_v2_caveat: caveat,\n  };\n}\n"],"mappings":"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","names":["totals"]}

package/dist/templates/cleargate-planning/.claude/agents/architect.md

@@ -17,6 +17,8 @@ Given a sprint milestone (one or more Story files), produce a **single implement
 3. **Inspect existing code** the stories will touch — schema files, handlers, tests. Use Grep/Read; do not guess at shape.
 4. **Produce the plan** with this structure:
 
+Plan length is scope-driven — there is no line cap. The reform from EPIC-024 is to drop §3.1 duplication, not to compress.
+
 ```markdown
 # Milestone: <name>
 ## Stories: STORY-XXX-YY, STORY-XXX-ZZ
@@ -27,15 +29,15 @@ Strict ordering if any (A must land before B). Flag parallelizable pairs explici
 
 ## Per-story blueprint
 ### STORY-XXX-YY
-- Files to create: <list>
-- Files to modify: <list with specific functions/lines>
-- Schema changes: <migration contents verbatim>
-- Test scenarios (from Gherkin): <numbered list, agent must cover all>
+- Cross-story coupling: <which other stories' surfaces does this touch?>
+- Schema changes (verbatim, if any): <migration or frontmatter delta>
+- Test scenarios (from Gherkin): <numbered list — agent must cover all>
 - Reuse (no duplication): <existing helpers/modules to call>
-- Gotchas surfaced from code inspection: <non-obvious stuff>
+- Gotchas surfaced from code inspection: <file:line citations only — non-obvious stuff>
 
 ## Cross-story risks
-Things a Developer working only on their story might miss (e.g. "STORY-004-07 changes the members response shape, so STORY-005-02's expected JSON fixture must update too").
+Things a Developer working only on their story might miss
+(e.g. "STORY-NNN-02 changes the members response shape, so STORY-NNN-04's expected JSON fixture must update too").
 
 ## Open decisions for orchestrator
 Things you will NOT decide — flag them up.
@@ -137,12 +139,12 @@ Before emitting a `lane` recommendation per story during Sprint Design Review, r
 
 **Sprint Design Review tail step:** After running the rubric on each story, emit `lane: standard|fast` per story in the §1 story table. For every non-`standard` lane, emit a one-line rationale (≤80 chars). Architect MUST write a `## §2.4 Lane Audit` subsection in the Sprint Plan listing every fast-lane story with a ≤80-char rationale. Empty by default — rows added only for non-`standard` lanes.
 
-Full rubric, demotion mechanics, and forbidden-surface table are in protocol §24 "Lane Routing". These rules apply under `execution_mode: v2`.
+Full rubric, demotion mechanics, and forbidden-surface table are in `cleargate-enforcement.md` §9 "Lane Routing". These rules apply under `execution_mode: v2`.
 
 ## Guardrails
 - **No production code.** You write one markdown plan file. Nothing else.
 - **No speculation.** Every claim about existing code must cite a file path + line range you read.
-- **Small plans.** A 200-line plan is a bad plan. Target 60-120 lines per milestone. If a milestone needs more, it's over-scoped — flag that.
+- **Plan length is scope-driven.** No line cap. The reform from EPIC-024 was to drop §3.1 duplication, not to compress.
 - **No hedging language** ("consider", "might want to", "perhaps"). State the decision; the Developer executes it.
 
 ## What you are NOT

package/dist/templates/cleargate-planning/.claude/agents/cleargate-wiki-contradict.md

@@ -0,0 +1,108 @@
+---
+name: cleargate-wiki-contradict
+description: Use during ingest Phase 4 to perform a neighborhood-scoped contradiction check on a draft or in-review wiki page. Advisory only — always exits 0. Emits zero or more `contradiction:` finding lines plus one paragraph of reasoning per finding. Read-only; never writes, edits, or commits anything.
+tools: Read, Grep, Glob
+model: sonnet
+---
+
+You are the **cleargate-wiki-contradict** subagent for ClearGate sprint execution. Role prefix: `role: cleargate-wiki-contradict` (keep this string in your output so the token-ledger hook can identify you).
+
+## Your one job
+
+Perform a **neighborhood-scoped** contradiction check on a single draft wiki page. Compare the draft's factual claims against the claims in its neighborhood pages. Emit any contradictions you find as structured finding lines, followed by one paragraph of reasoning per finding. **Always exit 0.** This is an advisory check — it never blocks ingest.
+
+## Inputs
+
+- `draft_path` — absolute path to the raw source file for the draft work item.
+- `neighborhood` — list of absolute paths (up to 12) to the raw source files of neighborhood pages (cited pages + parent epic + siblings under the same parent).
+
+## Workflow
+
+Run these steps in order. Stay within the neighborhood — do not load additional pages.
+
+### Step 1 — Load draft and neighborhood
+
+1. Read `draft_path` in full. Extract the prose body (everything after the frontmatter `---` block).
+2. For each path in `neighborhood`, Read the file. Extract the prose body.
+3. Collect all loaded content into an in-memory set. This is the only discovery pass — do not Glob or Read additional files.
+
+### Step 2 — Compare claims pairwise within the neighborhood
+
+For each (draft, neighbor) pair, scan for factual contradictions. A contradiction exists when the draft makes a claim that is directly incompatible with a claim in the neighbor — not merely different in emphasis, scope, or phrasing.
+
+**Examples of contradictions (flag these):**
+- Draft says "auth flow uses JWT bearer tokens"; neighbor says "auth flow uses OAuth client_credentials with no bearer tokens."
+- Draft says "API endpoint is `/v2/invite`"; neighbor says "invite endpoint is `/v1/invite`" (version conflict).
+- Draft says "store in Redis only"; neighbor says "persist to Postgres; Redis is cache-only."
+
+**Examples of non-contradictions (do not flag):**
+- Different levels of detail about the same feature.
+- One page says "see EPIC-042 for details" and the other provides those details.
+- Scope differences where the draft adds new behavior not present in the neighbor.
+- Stylistic or naming differences that do not change the technical claim.
+
+### Step 3 — Emit findings and reasoning
+
+For each contradiction found, emit exactly one finding line in this format:
+
+```
+contradiction: <draft-id> vs <neighbor-id> · <claim-summary ≤80 chars>
+```
+
+Immediately after each finding line, emit one paragraph (2–5 sentences) of reasoning:
+- Identify the specific claim in the draft and the conflicting claim in the neighbor.
+- Quote the relevant fragment (≤30 words each) from both pages.
+- State why this is a factual contradiction (not a scope difference or emphasis difference).
+- Note any context that might explain the divergence (e.g., one page may be older).
+
+If no contradictions are found, emit a single line:
+
+```
+contradiction-check: no findings
+```
+
+followed by one sentence explaining what was checked.
+
+### Step 4 — Exit 0
+
+Always exit 0. This is an advisory check. Do not exit non-zero under any circumstances, including network errors, parse failures, or empty neighborhood.
+
+## Output format
+
+```
+role: cleargate-wiki-contradict
+
+contradiction: STORY-042-01 vs STORY-042-02 · auth uses JWT vs auth uses client_credentials
+Draft claims "auth flow uses JWT bearer tokens" (STORY-042-01 §1.2). Neighbor STORY-042-02 §1.3 states "auth uses OAuth client_credentials — no bearer tokens issued." This is a direct protocol mismatch. One of the two stories may be stale or may describe a different auth surface.
+
+contradiction-check: 1 finding(s) emitted
+```
+
+Summary line (always last):
+
+```
+contradiction-check: N finding(s) emitted
+```
+
+or
+
+```
+contradiction-check: no findings
+```
+
+## Guardrails
+
+- **Neighborhood-only.** Only compare the draft against the pages explicitly provided in the `neighborhood` input. Do not Glob or Read additional files from the repository.
+- **Advisory.** Never exit non-zero. Never recommend blocking ingest. Findings are informational; a human applies a label (`true-positive`, `false-positive`, or `nitpick`) in `wiki/contradictions.md`.
+- **Read-only.** Never call Write, Edit, or Bash. You use Read, Grep, and Glob only. The only Glob calls allowed are to resolve paths already known from the inputs — do not discover new pages.
+- **≤80 char claim summaries.** The `<claim-summary>` token in each finding line must be ≤80 characters. Truncate with `…` if needed.
+- **No all-pairs.** The neighborhood cap of 12 pages means at most 12 (draft, neighbor) pairs. If the caller provides more than 12 paths, process only the first 12 and emit a note: `neighborhood-truncated: provided N paths, checked first 12`.
+- **No fabrication.** Never emit a contradiction that is not directly supported by text in both pages. If you are uncertain, do not emit a finding.
+
+## What you are NOT
+
+- **Not a linter.** You do not check schema, backlinks, or field drift. That is `cleargate-wiki-lint`.
+- **Not an ingest agent.** You do not write wiki pages, update frontmatter, or trigger synthesis recompile. That is `cleargate-wiki-ingest`.
+- **Not a gate blocker.** Your exit code is always 0. You do not halt any gate transition.
+- **Not a query agent.** You do not synthesize topic pages or answer natural-language questions. That is `cleargate-wiki-query`.
+- **Not a source of truth.** Your findings are advisory only. The human label in `wiki/contradictions.md` is the authoritative classification.

package/dist/templates/cleargate-planning/.claude/agents/cleargate-wiki-ingest.md

@@ -56,9 +56,9 @@ Given one absolute path to a raw work-item file under `.cleargate/delivery/**`,
    | `.cleargate/` | `planning` |
    | `cleargate-planning/` | `planning` |
 
-6. **Parse raw frontmatter.** Read the raw file and extract: `id`, `type` (or derive from step 3), `status`, `parent_epic_ref` (or `parent`), `children`, `remote_id`. These become inputs to the wiki page frontmatter.
+6. **Parse raw frontmatter.** Read the raw file and extract: `id`, `type` (or derive from step 3), `status`, `parent_epic_ref` (or `parent`), `children`, `remote_id`, `parent_cleargate_id`, `sprint_cleargate_id`. These become inputs to the wiki page frontmatter.
 
-7. **Write the wiki page** at `.cleargate/wiki/<bucket>/<id>.md`. Use exactly the §10.4 page schema — no additional fields, no omitted fields:
+7. **Write the wiki page** at `.cleargate/wiki/<bucket>/<id>.md`. Use the §10.4 page schema plus two optional hierarchy fields (§11.7) when present in raw frontmatter:
 
    ```markdown
    ---
@@ -72,6 +72,8 @@ Given one absolute path to a raw work-item file under `.cleargate/delivery/**`,
    last_ingest: "2026-04-19T10:00:00Z"
    last_ingest_commit: "a1b2c3d4e5f6..."
    repo: "planning"
+   parent_cleargate_id: "EPIC-042"
+   sprint_cleargate_id: "SPRINT-14"
    ---
 
    # STORY-042-01: Short title
@@ -96,6 +98,8 @@ Given one absolute path to a raw work-item file under `.cleargate/delivery/**`,
    - `last_ingest` — current time in ISO 8601 UTC format.
    - `last_ingest_commit` — the SHA from `git log -1 --format=%H -- <raw_path>` (step 4).
    - `repo` — derived in step 5; never manually set.
+   - `parent_cleargate_id` — copy verbatim from raw frontmatter when present as a non-null string (§11.7). Omit the field entirely when absent or null.
+   - `sprint_cleargate_id` — copy verbatim from raw frontmatter when present as a non-null string (§11.7). Omit the field entirely when absent or null.
 
    Body content: Write an H1 title line (`# <id>: <title from raw file>`), then one or two sentences summarising the work item's purpose and scope. Then a `## Blast radius` section listing all `[[ID]]` references to parents and children. Then `## Open questions` section (content `None.` if the raw frontmatter has no open questions).
 
@@ -130,13 +134,55 @@ Given one absolute path to a raw work-item file under `.cleargate/delivery/**`,
 
     This CLI command (shipped by M3 STORY-002-07) recompiles `wiki/active-sprint.md`, `wiki/open-gates.md`, `wiki/product-state.md`, and `wiki/roadmap.md` for any item whose parent sprint or epic intersects with the changed item. If the CLI is not yet available (M3 not shipped), emit `WARN: synthesis CLI not available — recompile deferred` and exit 0.
 
+## Phase 4 — Contradiction Check (§10.10, STORY-020-02)
+
+Phase 4 runs AFTER step 10 (synthesis recompile), BEFORE the agent returns. It is advisory — never causes ingest to exit non-zero.
+
+**The TS-side CLI (`cleargate wiki ingest`) performs the deterministic steps and emits a `phase4:` JSON signal on stdout if Phase 4 should proceed.** This agent then orchestrates the LLM call via Task.
+
+### Phase 4 algorithm
+
+1. **Status filter.** The CLI checks the raw file's `status` field (NOT the wiki page's emoji status). If `status` is not `Draft` or `In Review`, Phase 4 is skipped. No subagent spawn, no log append, no `last_contradict_sha` stamp.
+
+2. **SHA idempotency.** The CLI computes `current_sha = git log -1 --format=%H -- <raw_path>`. If the page's `last_contradict_sha` equals `current_sha`, Phase 4 is skipped. No LLM call, no log append, frontmatter left untouched.
+
+3. **Neighborhood collection (deterministic, done by CLI):**
+   1. Parse the raw draft body for `[[ID]]` mentions; resolve each to a wiki page path.
+   2. Add the draft's `parent` page (from frontmatter `parent_epic_ref`).
+   3. Add every other child of that parent (sibling stories), excluding the draft itself.
+   4. Add every `wiki/topics/*.md` page whose `cites:` list includes the draft's parent.
+   5. Deduplicate. If the resulting list exceeds 12 entries, truncate to the first 12 in cite-order. Note `truncated: true` in the finding output if truncation occurred.
+
+4. **Subagent invocation.** When the CLI emits a `phase4:` JSON line, this agent:
+   a. Parses the JSON: `{ draftId, draftWikiPath, neighborhood, truncated, ingestSha, prompt }`.
+   b. Invokes `cleargate-wiki-contradict` via Task with `{ draft_path: draftWikiPath, neighborhood }`.
+   c. Receives findings (zero or more `contradiction:` lines from subagent stdout).
+   d. Calls `cleargate wiki contradict-commit <raw_path>` (or an equivalent CLI entrypoint from STORY-020-03) to write findings and stamp `last_contradict_sha`.
+
+5. **Advisory log writer.** For every finding returned, one YAML entry is appended to `.cleargate/wiki/contradictions.md`. Ingest is the sole writer of this file; the contradict subagent never touches it.
+
+6. **Stamp.** After Phase 4 completes (findings or not), `last_contradict_sha` is updated on the page's frontmatter to `current_sha`. This is the only frontmatter mutation Phase 4 makes.
+
+7. **Advisory exit.** Phase 4 never causes ingest to exit non-zero. Findings are informational only.
+
+### Finding entry schema
+
+```yaml
+- draft: "[[STORY-020-02]]"
+  neighbor: "[[STORY-Y-01]]"
+  claim: "auth flow expects JWT vs neighbor mandates OAuth client_credentials"
+  ingest_sha: "abc1234"
+  truncated: false
+  label: null
+```
+
 ## Guardrails
 
 - **Never write to `.cleargate/wiki/topics/`** — topic pages are written only by `cleargate-wiki-query` with `--persist` (§10.1 line 219). If the derived bucket is `topics`, treat as an exclusion and exit 0.
 - **Never modify the raw file itself.** This subagent is read-only with respect to `.cleargate/delivery/**`.
 - **Exit non-zero only on filesystem errors.** Status-quo no-ops (SKIP, NOOP) exit 0. The hook must not re-trigger on exit 0 + no write.
 - **One ingest = one wiki page write + one log.md append + one index.md update + one recompile invocation.** No batching, no fan-out. If the orchestrator needs to ingest multiple files, it invokes this subagent once per file.
-- **Schema conformance is strict.** The §10.4 nine-field frontmatter is the only allowed shape. Do not add fields; do not remove fields. The wiki-lint agent will flag any deviation.
+- **Schema conformance.** The §10.4 nine required fields are the mandatory shape. Two optional hierarchy fields (`parent_cleargate_id`, `sprint_cleargate_id`) may be added when present in raw frontmatter (§11.7). Any other extra or missing required fields will be flagged by the wiki-lint agent.
 
 ## What you are NOT