ecoportal-api-graphql 1.3.5 → 1.3.9

data/.ai-assistance/scripts/task-read.ts

@@ -0,0 +1,125 @@
+#!/usr/bin/env npx ts-node
+/**
+ * task-read.ts
+ * Parse a bridge task file (inbox, outbox, or archive) and output structured JSON.
+ * Saves agents from reading raw Markdown — reduces token overhead for every task fetch.
+ *
+ * Usage:
+ *   npx ts-node .ai-assistance/scripts/task-read.ts --task oscar-a3f2b1c-list-open-mrs.md
+ *   npx ts-node .ai-assistance/scripts/task-read.ts --file /absolute/path/to/file.md
+ *   npx ts-node .ai-assistance/scripts/task-read.ts --task oscar-abc.md --dir outbox
+ *
+ * Output (always to stdout):
+ *   {
+ *     "title":    "List open MRs",
+ *     "status":   "DONE",
+ *     "created":  "2026-06-07T10:00:00Z",
+ *     "from":     "cowork",
+ *     "to":       "code",
+ *     "context":  "...",
+ *     "request":  "...",
+ *     "expected": "...",
+ *     "result":   "...",
+ *     "notes":    "...",
+ *     "raw_path": "/absolute/path/to/file.md"
+ *   }
+ *
+ * Missing sections are returned as empty strings, not null.
+ * Exits 1 with {"error":"..."} if file not found or unreadable.
+ */
+
+import { readFileSync, existsSync } from "fs";
+import { join, dirname, resolve } from "path";
+
+// ---------------------------------------------------------------------------
+// Argument parsing
+// ---------------------------------------------------------------------------
+const args = process.argv.slice(2);
+const get = (flag: string): string | undefined => {
+  const i = args.indexOf(flag);
+  return i !== -1 && i + 1 < args.length ? args[i + 1] : undefined;
+};
+
+const taskFile = get("--task");
+const filePath = get("--file");
+const dir      = get("--dir") ?? "inbox"; // inbox | outbox | archive
+
+const scriptDir  = dirname(process.argv[1]);
+const bridgeDir  = join(scriptDir, "../bridge");
+
+let resolvedPath: string;
+
+if (filePath) {
+  resolvedPath = resolve(filePath);
+} else if (taskFile) {
+  // Try the specified dir first, then inbox, outbox, and archive variants
+  const seen = new Set<string>();
+  const unique = (p: string) => { seen.add(p); return p; };
+  const candidates = [
+    unique(join(bridgeDir, dir,       taskFile)),
+    unique(join(bridgeDir, "inbox",   taskFile)),
+    unique(join(bridgeDir, "outbox",  taskFile)),
+    unique(join(bridgeDir, "archive", taskFile)),
+    unique(join(bridgeDir, "archive", `inbox-${taskFile}`)),
+    unique(join(bridgeDir, "archive", `outbox-${taskFile}`)),
+  ].filter((p, i, arr) => arr.indexOf(p) === i); // deduplicate
+
+  const found = candidates.find(p => existsSync(p));
+  if (!found) {
+    console.log(JSON.stringify({ error: `Task file not found: ${taskFile}`, searched: candidates }));
+    process.exit(1);
+  }
+  resolvedPath = found;
+} else {
+  console.log(JSON.stringify({ error: "Provide --task <filename> or --file <path>" }));
+  process.exit(1);
+}
+
+if (!existsSync(resolvedPath)) {
+  console.log(JSON.stringify({ error: `File not found: ${resolvedPath}` }));
+  process.exit(1);
+}
+
+// ---------------------------------------------------------------------------
+// Parse
+// ---------------------------------------------------------------------------
+const raw = readFileSync(resolvedPath, "utf8");
+
+/** Extract a header field like "STATUS: PENDING" → "PENDING" */
+function header(key: string): string {
+  const m = raw.match(new RegExp(`^${key}:\\s*(.+)$`, "m"));
+  return m ? m[1].trim() : "";
+}
+
+/** Extract a Markdown section body (between ## Heading and the next ## or EOF) */
+function section(heading: string): string {
+  const escaped = heading.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  // Match the heading line (## Heading...\n) then capture everything until the next ## or EOF
+  const headingRe = new RegExp(`^##\\s+${escaped}[^\\n]*\\n`, "m");
+  const headingMatch = headingRe.exec(raw);
+  if (!headingMatch) return "";
+  const contentStart = headingMatch.index + headingMatch[0].length;
+  const rest = raw.slice(contentStart);
+  const nextSection = /^## /m.exec(rest);
+  return rest.slice(0, nextSection ? nextSection.index : rest.length).trim();
+}
+
+// Title: "# TASK: My title"
+const titleMatch = raw.match(/^#\s+TASK:\s+(.+)$/m);
+const title = titleMatch ? titleMatch[1].trim() : "";
+
+const result = {
+  title,
+  status:   header("STATUS"),
+  created:  header("CREATED"),
+  from:     header("FROM"),
+  to:       header("TO"),
+  context:  section("Context"),
+  request:  section("Request"),
+  expected: section("Expected output"),
+  result:   section("Result"),
+  notes:    section("Notes"),
+  raw_path: resolvedPath,
+};
+
+console.log(JSON.stringify(result, null, 2));

data/.ai-assistance/scripts/token-logger.js

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+/**
+ * token-logger.js
+ *
+ * Claude Code Stop hook — fires after every AI response turn.
+ * Reads the session transcript, extracts token usage, accumulates weekly totals,
+ * and warns when approaching the project's budget allocation.
+ *
+ * Wired in .claude/settings.json:
+ *   "Stop": [{ "type": "command", "command": "node .ai-assistance/scripts/token-logger.js" }]
+ *
+ * Reads:  stdin (Stop event JSON with session_id, transcript_path, cwd)
+ *         .ai-assistance/token-budget.json
+ *         .ai-assistance/local/kpi/session-<id>.json  (running session state)
+ *         .ai-assistance/local/kpi/weekly-<YYYY-WNN>.json  (weekly totals)
+ *
+ * Writes: .ai-assistance/local/kpi/session-<id>.json  (updated state)
+ *         .ai-assistance/local/kpi/weekly-<YYYY-WNN>.json  (updated totals)
+ *         .ai-assistance/local/kpi/sessions-<YYYY-WNN>.jsonl  (completed turns)
+ */
+
+const fs   = require("fs");
+const path = require("path");
+const os   = require("os");
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+function isoWeek(d) {
+  const jan4 = new Date(d.getFullYear(), 0, 4);
+  const startOfWeek = new Date(jan4);
+  startOfWeek.setDate(jan4.getDate() - ((jan4.getDay() + 6) % 7));
+  const weekNum = Math.ceil(((d - startOfWeek) / 86400000 + 1) / 7);
+  return `${d.getFullYear()}-W${String(weekNum).padStart(2, "0")}`;
+}
+
+function loadJson(p, fallback) {
+  try { return JSON.parse(fs.readFileSync(p, "utf8")); }
+  catch { return fallback; }
+}
+
+function saveJson(p, data) {
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, JSON.stringify(data, null, 2) + "\n", "utf8");
+}
+
+function appendJsonl(p, obj) {
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.appendFileSync(p, JSON.stringify(obj) + "\n", "utf8");
+}
+
+// ── Extract token usage from transcript JSONL ──────────────────────────────
+
+function extractUsageFromTranscript(transcriptPath) {
+  if (!transcriptPath || !fs.existsSync(transcriptPath)) return null;
+
+  let inputTokens = 0, outputTokens = 0, cacheReadTokens = 0, cacheCreateTokens = 0;
+  let toolCalls = 0, turns = 0, found = false;
+
+  try {
+    const lines = fs.readFileSync(transcriptPath, "utf8").split("\n").filter(Boolean);
+    for (const line of lines) {
+      try {
+        const entry = JSON.parse(line);
+        // Extract usage from any entry that has it
+        const usage = entry.usage || entry.message?.usage;
+        if (usage) {
+          inputTokens      += usage.input_tokens              || 0;
+          outputTokens     += usage.output_tokens             || 0;
+          cacheReadTokens  += usage.cache_read_input_tokens   || 0;
+          cacheCreateTokens+= usage.cache_creation_input_tokens|| 0;
+          found = true;
+        }
+        // Count tool uses
+        if (entry.type === "tool_use" || entry.tool_name) toolCalls++;
+        // Count assistant turns
+        if (entry.role === "assistant" || entry.type === "assistant") turns++;
+      } catch { /* skip malformed lines */ }
+    }
+  } catch { return null; }
+
+  if (!found) return null;
+  return { inputTokens, outputTokens, cacheReadTokens, cacheCreateTokens, toolCalls, turns };
+}
+
+// ── Estimate tokens when transcript doesn't have usage data ───────────────
+
+function estimateFromTranscript(transcriptPath) {
+  if (!transcriptPath || !fs.existsSync(transcriptPath)) {
+    return { inputTokens: 0, outputTokens: 0, toolCalls: 0, turns: 0, estimated: true };
+  }
+  let inputChars = 0, outputChars = 0, toolCalls = 0, turns = 0;
+  try {
+    const lines = fs.readFileSync(transcriptPath, "utf8").split("\n").filter(Boolean);
+    for (const line of lines) {
+      try {
+        const entry = JSON.parse(line);
+        const content = JSON.stringify(entry.content || entry.text || "");
+        if (entry.role === "user" || entry.type === "user")           { inputChars += content.length; }
+        if (entry.role === "assistant" || entry.type === "assistant") { outputChars += content.length; turns++; }
+        if (entry.type === "tool_use" || entry.tool_name)             { toolCalls++; inputChars += 500 * 4; }
+      } catch { /* skip */ }
+    }
+  } catch {}
+  return {
+    inputTokens:  Math.round(inputChars / 4),
+    outputTokens: Math.round(outputChars / 4),
+    cacheReadTokens: 0, cacheCreateTokens: 0,
+    toolCalls, turns, estimated: true
+  };
+}
+
+// ── Main ───────────────────────────────────────────────────────────────────
+
+async function main() {
+  let event = {};
+  try {
+    const raw = fs.readFileSync("/dev/stdin", "utf8");
+    event = JSON.parse(raw);
+  } catch { /* no stdin or parse error — use empty event */ }
+
+  const cwd            = event.cwd || process.cwd();
+  const sessionId      = event.session_id || `unknown-${Date.now()}`;
+  const transcriptPath = event.transcript_path;
+
+  const budgetFile  = path.join(cwd, ".ai-assistance", "token-budget.json");
+  const kpiDir      = path.join(cwd, ".ai-assistance", "local", "kpi");
+  const weekId      = isoWeek(new Date());
+  const sessionFile = path.join(kpiDir, `session-${sessionId}.json`);
+  const weeklyFile  = path.join(kpiDir, `weekly-${weekId}.json`);
+  const turnLogFile = path.join(kpiDir, `sessions-${weekId}.jsonl`);
+
+  const budget  = loadJson(budgetFile, {});
+  const project = (budget.project?.name || path.basename(cwd));
+  const priority= (budget.project?.priority || "medium");
+  const targetPct = (budget.weekly_quota?.target_utilization_pct || 75) / 100;
+  const warnAt    = (budget.session_logging?.warn_at_pct || 80) / 100;
+
+  // Extract usage from transcript
+  const transcriptUsage = extractUsageFromTranscript(transcriptPath)
+    || estimateFromTranscript(transcriptPath);
+
+  // Load previous session state (accumulate across turns in a session)
+  const prevSession = loadJson(sessionFile, {
+    session_id: sessionId, project, priority,
+    started_at: new Date().toISOString(),
+    week_id: weekId,
+    input_tokens: 0, output_tokens: 0,
+    cache_read_tokens: 0, cache_create_tokens: 0,
+    tool_calls: 0, turns: 0, estimated: false,
+  });
+
+  // Use transcript totals (they accumulate naturally) not deltas
+  const sessionNow = {
+    ...prevSession,
+    input_tokens:       transcriptUsage.inputTokens,
+    output_tokens:      transcriptUsage.outputTokens,
+    cache_read_tokens:  transcriptUsage.cacheReadTokens  || 0,
+    cache_create_tokens:transcriptUsage.cacheCreateTokens || 0,
+    tool_calls:         transcriptUsage.toolCalls,
+    turns:              transcriptUsage.turns,
+    estimated:          transcriptUsage.estimated || false,
+    last_updated_at:    new Date().toISOString(),
+  };
+
+  saveJson(sessionFile, sessionNow);
+
+  // Update weekly totals — replace session contribution (re-compute from sessions)
+  const weekly = loadJson(weeklyFile, { week_id: weekId, projects: {}, total_tokens: 0 });
+  const sessionTotal = sessionNow.input_tokens + sessionNow.output_tokens;
+  const prevContrib  = (weekly.projects[sessionId]?.tokens || 0);
+  weekly.projects[sessionId] = {
+    project, priority, tokens: sessionTotal,
+    tool_calls: sessionNow.tool_calls, turns: sessionNow.turns,
+    updated_at: new Date().toISOString()
+  };
+  weekly.total_tokens = Object.values(weekly.projects).reduce((s, p) => s + p.tokens, 0);
+  saveJson(weeklyFile, weekly);
+
+  // Log the turn to the weekly JSONL (for cross-session analysis)
+  appendJsonl(turnLogFile, {
+    ts: new Date().toISOString(), session_id: sessionId, project, priority, week_id: weekId,
+    turn_tokens: sessionTotal - prevContrib,
+    session_total_tokens: sessionTotal,
+    tool_calls: sessionNow.tool_calls,
+    estimated: sessionNow.estimated,
+  });
+
+  // ── Budget warnings ────────────────────────────────────────────────────
+
+  const totalTokens = budget.weekly_quota?.total_tokens;
+  if (totalTokens) {
+    const usedPct = weekly.total_tokens / totalTokens;
+    const targetTokens = totalTokens * targetPct;
+
+    // Priority-based soft allocation
+    const weights  = budget.project_allocation?.priority_weights || { high: 50, medium: 30, low: 20 };
+    const myWeight = (weights[priority] || 30) / 100;
+    const myBudget = totalTokens * targetPct * myWeight;
+    const myUsed   = Object.values(weekly.projects)
+      .filter(p => p.project === project)
+      .reduce((s, p) => s + p.tokens, 0);
+    const myPct = myBudget > 0 ? myUsed / myBudget : 0;
+
+    if (usedPct >= warnAt) {
+      process.stderr.write(
+        `\n[token-budget] ⚠  Week ${weekId}: ${Math.round(usedPct * 100)}% of quota used` +
+        ` (${weekly.total_tokens.toLocaleString()}/${totalTokens.toLocaleString()} tokens)` +
+        ` — target was ${Math.round(targetPct * 100)}%\n`
+      );
+    }
+    if (myPct >= warnAt) {
+      process.stderr.write(
+        `[token-budget] ⚠  Project "${project}" (${priority}): ${Math.round(myPct * 100)}% of allocation` +
+        ` (${myUsed.toLocaleString()}/${Math.round(myBudget).toLocaleString()} tokens)\n`
+      );
+    }
+  }
+}
+
+main().catch(() => { /* never crash the hook */ });

data/.ai-assistance/scripts/token-report.ts

@@ -0,0 +1,158 @@
+/**
+ * token-report.ts
+ *
+ * Cross-project token usage report. Reads weekly session logs from all aligned
+ * projects (via local/paths.md) and produces a management-ready summary.
+ *
+ * Usage:
+ *   npx ts-node .ai-assistance/scripts/token-report.ts
+ *   npx ts-node .ai-assistance/scripts/token-report.ts --week 2026-W24
+ *   npx ts-node .ai-assistance/scripts/token-report.ts --format json
+ *
+ * Output: Markdown table (default) or JSON (--format json)
+ * The report is printed to stdout — redirect to a file or pipe to your reporting tool.
+ */
+
+import * as fs   from "fs";
+import * as path from "path";
+
+const SCRIPTS_DIR = path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Z]:)/, "$1"));
+const AI_DIR      = path.join(SCRIPTS_DIR, "..");
+const CWD         = path.join(AI_DIR, "..", "..");
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+function isoWeek(d: Date): string {
+  const jan4 = new Date(d.getFullYear(), 0, 4);
+  const s = new Date(jan4); s.setDate(jan4.getDate() - ((jan4.getDay() + 6) % 7));
+  return `${d.getFullYear()}-W${String(Math.ceil(((d.getTime() - s.getTime()) / 86400000 + 1) / 7)).padStart(2, "0")}`;
+}
+
+function loadJson<T>(p: string, fb: T): T {
+  try { return JSON.parse(fs.readFileSync(p, "utf8")); } catch { return fb; }
+}
+
+interface ProjectPath { alias: string; localPath: string; }
+
+function loadProjectPaths(): ProjectPath[] {
+  const pathsFile = path.join(AI_DIR, "local", "paths.md");
+  if (!fs.existsSync(pathsFile)) return [{ alias: path.basename(CWD), localPath: CWD }];
+  const projects: ProjectPath[] = [];
+  const seen = new Set<string>();
+  for (const line of fs.readFileSync(pathsFile, "utf8").split("\n")) {
+    const m = line.match(/\|\s*`([^`]+)`\s*\|\s*`([^`]+)`/);
+    if (!m) continue;
+    const [, alias, rawPath] = m;
+    const localPath = rawPath.replace(/\//g, path.sep);
+    const real = fs.existsSync(localPath) ? fs.realpathSync(localPath) : localPath;
+    if (!seen.has(real) && fs.existsSync(localPath)) { projects.push({ alias, localPath }); seen.add(real); }
+  }
+  return projects.length ? projects : [{ alias: path.basename(CWD), localPath: CWD }];
+}
+
+interface WeeklyData {
+  week_id: string;
+  total_tokens: number;
+  projects: Record<string, { project: string; priority: string; tokens: number; tool_calls: number; turns: number; }>;
+}
+
+interface SessionTurn {
+  ts: string; session_id: string; project: string; priority: string;
+  week_id: string; turn_tokens: number; session_total_tokens: number;
+  tool_calls: number; estimated: boolean;
+}
+
+// ── Main ───────────────────────────────────────────────────────────────────
+
+const args    = process.argv.slice(2);
+const weekArg = args.includes("--week") ? args[args.indexOf("--week") + 1] : null;
+const format  = args.includes("--format") ? args[args.indexOf("--format") + 1] : "text";
+const weekId  = weekArg || isoWeek(new Date());
+
+const projects = loadProjectPaths();
+
+// Aggregate across all projects
+const byProject: Record<string, {
+  tokens: number; tool_calls: number; turns: number;
+  priority: string; sessions: number; estimated: number;
+}> = {};
+
+let grandTotal = 0;
+
+for (const { localPath } of projects) {
+  const kpiDir     = path.join(localPath, ".ai-assistance", "local", "kpi");
+  const weeklyFile = path.join(kpiDir, `weekly-${weekId}.json`);
+  const budget     = loadJson<any>(path.join(localPath, ".ai-assistance", "token-budget.json"), {});
+  const projectName= budget.project?.name || path.basename(localPath);
+  const priority   = budget.project?.priority || "medium";
+
+  if (!fs.existsSync(weeklyFile)) continue;
+
+  const weekly = loadJson<WeeklyData>(weeklyFile, { week_id: weekId, total_tokens: 0, projects: {} });
+
+  // Sum sessions for this project
+  let tokens = 0, toolCalls = 0, turns = 0, sessions = 0, estimated = 0;
+  for (const s of Object.values(weekly.projects)) {
+    if (s.project === projectName) {
+      tokens    += s.tokens;
+      toolCalls += s.tool_calls || 0;
+      turns     += s.turns || 0;
+      sessions++;
+    }
+  }
+
+  // Count estimated sessions from JSONL
+  const jsonl = path.join(kpiDir, `sessions-${weekId}.jsonl`);
+  if (fs.existsSync(jsonl)) {
+    const lines = fs.readFileSync(jsonl, "utf8").split("\n").filter(Boolean);
+    estimated = lines.filter(l => { try { return JSON.parse(l).estimated; } catch { return false; } }).length;
+  }
+
+  if (tokens > 0) {
+    byProject[projectName] = { tokens, tool_calls: toolCalls, turns, priority, sessions, estimated };
+    grandTotal += tokens;
+  }
+}
+
+if (format === "json") {
+  console.log(JSON.stringify({ week_id: weekId, grand_total_tokens: grandTotal, projects: byProject }, null, 2));
+  process.exit(0);
+}
+
+// ── Text report ────────────────────────────────────────────────────────────
+
+const sortedProjects = Object.entries(byProject)
+  .sort(([, a], [, b]) => b.tokens - a.tokens);
+
+console.log(`\n${"=".repeat(70)}`);
+console.log(`  Token Usage Report — ${weekId}`);
+console.log(`  Generated: ${new Date().toISOString().slice(0, 16)}`);
+console.log(`${"=".repeat(70)}\n`);
+console.log(`  Grand total: ${grandTotal.toLocaleString()} tokens across ${sortedProjects.length} project(s)\n`);
+
+console.log(`  ${"Project".padEnd(30)} ${"Priority".padEnd(10)} ${"Tokens".padStart(10)} ${"Share".padStart(7)} ${"Tool calls".padStart(12)} ${"Turns".padStart(6)}`);
+console.log(`  ${"-".repeat(78)}`);
+
+for (const [name, data] of sortedProjects) {
+  const share = grandTotal > 0 ? Math.round((data.tokens / grandTotal) * 100) : 0;
+  const est   = data.estimated > 0 ? " ~" : "  ";
+  console.log(`  ${name.padEnd(30)} ${data.priority.padEnd(10)} ${est}${data.tokens.toLocaleString().padStart(8)} ${`${share}%`.padStart(7)} ${data.tool_calls.toString().padStart(12)} ${data.turns.toString().padStart(6)}`);
+}
+
+console.log(`\n  ~ = some sessions used token estimation (transcript had no usage data)`);
+
+// Priority allocation analysis
+const targetPct = 75;
+const weights   = { high: 50, medium: 30, low: 20 };
+console.log(`\n  Priority allocation vs actuals (target utilization: ${targetPct}%):`);
+for (const priority of ["high", "medium", "low"]) {
+  const w = (weights as any)[priority];
+  const actual = Object.values(byProject)
+    .filter(p => p.priority === priority)
+    .reduce((s, p) => s + p.tokens, 0);
+  const actualPct = grandTotal > 0 ? Math.round((actual / grandTotal) * 100) : 0;
+  const projects  = Object.entries(byProject).filter(([, p]) => p.priority === priority).map(([n]) => n).join(", ") || "(none)";
+  console.log(`    ${priority.padEnd(8)} target ~${w}%  actual ${`${actualPct}%`.padStart(4)}  — ${projects}`);
+}
+
+console.log(`\n${"=".repeat(70)}\n`);

data/.ai-assistance/scripts/token-session-start.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+/**
+ * token-session-start.js
+ *
+ * Claude Code SessionStart hook.
+ * Checks current week's token usage, warns if over allocation,
+ * and shows the budget status for this project.
+ *
+ * Wired in .claude/settings.json:
+ *   "SessionStart": [{ "type": "command", "command": "node .ai-assistance/scripts/token-session-start.js" }]
+ */
+
+const fs   = require("fs");
+const path = require("path");
+
+function isoWeek(d) {
+  const jan4 = new Date(d.getFullYear(), 0, 4);
+  const s = new Date(jan4); s.setDate(jan4.getDate() - ((jan4.getDay() + 6) % 7));
+  return `${d.getFullYear()}-W${String(Math.ceil(((d - s) / 86400000 + 1) / 7)).padStart(2, "0")}`;
+}
+function loadJson(p, fb) { try { return JSON.parse(fs.readFileSync(p, "utf8")); } catch { return fb; } }
+
+async function main() {
+  let event = {};
+  try { event = JSON.parse(fs.readFileSync("/dev/stdin", "utf8")); } catch {}
+
+  const cwd     = event.cwd || process.cwd();
+  const weekId  = isoWeek(new Date());
+  const budget  = loadJson(path.join(cwd, ".ai-assistance", "token-budget.json"), {});
+  const weekly  = loadJson(path.join(cwd, ".ai-assistance", "local", "kpi", `weekly-${weekId}.json`), { total_tokens: 0, projects: {} });
+
+  const project  = budget.project?.name || path.basename(cwd);
+  const priority = budget.project?.priority || "medium";
+  const total    = budget.weekly_quota?.total_tokens;
+  const targetPct= (budget.weekly_quota?.target_utilization_pct || 75);
+
+  // My project's tokens this week across all sessions
+  const myTokens = Object.values(weekly.projects)
+    .filter(p => p.project === project)
+    .reduce((s, p) => s + p.tokens, 0);
+
+  const lines = [`\n[token-budget] Week ${weekId} | Project: ${project} (${priority})`];
+  lines.push(`  All projects this week: ${weekly.total_tokens.toLocaleString()} tokens`);
+  lines.push(`  This project this week: ${myTokens.toLocaleString()} tokens`);
+
+  if (total) {
+    const usedPct = Math.round((weekly.total_tokens / total) * 100);
+    const weights = budget.project_allocation?.priority_weights || { high: 50, medium: 30, low: 20 };
+    const myAlloc = Math.round(total * (targetPct / 100) * ((weights[priority] || 30) / 100));
+    const myPct   = myAlloc > 0 ? Math.round((myTokens / myAlloc) * 100) : 0;
+    lines.push(`  Week quota: ${usedPct}% used (target ${targetPct}%) | This project: ${myPct}% of ${myAlloc.toLocaleString()} alloc`);
+    if (usedPct >= targetPct) lines.push(`  !! Over weekly target — consider deferring low-priority work`);
+    if (myPct >= 90)          lines.push(`  !! This project near allocation limit`);
+  }
+
+  process.stderr.write(lines.join("\n") + "\n");
+
+  // Also run bridge-init if it exists
+  const bridgeInit = path.join(cwd, ".ai-assistance", "scripts", "bridge-init.sh");
+  if (fs.existsSync(bridgeInit)) {
+    const { execSync } = require("child_process");
+    try { execSync(`bash "${bridgeInit}"`, { stdio: "inherit" }); } catch {}
+  }
+}
+
+main().catch(() => {});

data/.ai-assistance/skills/ai-instructions/SKILL.md

@@ -0,0 +1,48 @@
+# SKILL: AI Instructions Generator, Reviewer & Updater
+
+**Purpose:** Keep CLAUDE.md, skill files, and conventions accurate, tidy, and placed correctly as the project evolves.
+
+---
+
+## When to Use
+
+- A developer makes an observation that reveals a gap, mistake, or new convention.
+- A new pattern emerges in the code that future AI agents should know about.
+- A skill needs to be created, updated, or split.
+- CLAUDE.md needs to reflect a structural change to the repo.
+
+---
+
+## Decision: Practice/Convention vs. CLAUDE.md Instruction vs. Skill
+
+When an observation is made, scope it:
+
+| Type | Where it goes |
+|------|--------------|
+| One-off note or context | Inline comment in the relevant `.ai-assistance/code/*.md` doc |
+| Convention (how we do things here) | `CLAUDE.md` → Conventions section |
+| Always-do behaviour for AI agents | `CLAUDE.md` → Before Starting Any Task, or a new section |
+| Reusable, invocable capability | New or updated `SKILL.md` in `.ai-assistance/skills/<skill-name>/` |
+
+---
+
+## File Placement Rules
+
+- **CLAUDE.md** lives at repo root — one file, always.
+- **Skills** live at `.ai-assistance/skills/<skill-name>/SKILL.md`.
+  - Additional assets (scripts, prompts) live alongside the SKILL.md in the same folder.
+- **Code specs** live at `.ai-assistance/code/` (see `code-specs` skill).
+- **Project files** live at `.ai-assistance/projects/<project-name>/` (see `project-cycle` skill).
+- **Refactoring logs** live at `.ai-assistance/code/refactoring/` (see `refactor` skill).
+
+**Never scatter instruction files in code directories.** All AI tooling lives under `.ai-assistance/`.
+
+---
+
+## Workflow
+
+1. Identify the type of observation (see table above).
+2. Locate the correct file. Create it if it doesn't exist.
+3. Make the minimal change — don't rewrite documents unnecessarily.
+4. Update the skill index table in CLAUDE.md if a new skill was added.
+5. Confirm with the developer if the change affects an existing convention that other developers rely on.