kanban-system 1.0.0

package/lib/runner/budget.cjs

@@ -0,0 +1,75 @@
+/**
+ * Second-model budget enforcement + model fallback chain.
+ *
+ * Env-configurable:
+ *   DAILY_CODEX_BUDGET=200           — max second-model (Codex/GPT) invocations per UTC day
+ *   CROSS_VALIDATION_THRESHOLD=medium — severity ≥ this auto-promotes a single-model task to `both`
+ *   MODEL_FALLBACK_CHAIN=opus,sonnet,haiku — Claude tiers to step down through under load
+ *
+ * On budget exhaustion:
+ *   runner=codex            → claude        (single-model fallback)
+ *   runner=both             → claude        (cross-validation unavailable)
+ *   runner=reviewer:codex   → claude        (review skipped)
+ *
+ * Tracks invocation counts in data/runs/budget.json with a daily reset.
+ */
+const fs = require("fs");
+const path = require("path");
+const config = require("../config.cjs");
+
+const BUDGET_FILE = path.join(config.repoRoot, "data", "runs", "budget.json");
+const DAILY_CAP = parseInt(process.env.DAILY_CODEX_BUDGET || "200", 10);
+const THRESHOLD = (process.env.CROSS_VALIDATION_THRESHOLD || "medium").toLowerCase();
+const SEVERITY_RANK = { low: 0, medium: 1, high: 2, critical: 3 };
+const FALLBACK_CHAIN = (process.env.MODEL_FALLBACK_CHAIN || "claude-opus-4-7,claude-sonnet-4-6,claude-haiku-4-5").split(",").map((s) => s.trim()).filter(Boolean);
+
+function todayKey() { return new Date().toISOString().slice(0, 10); }
+function loadBudget() {
+  const fresh = { day: todayKey(), codex_calls: 0, claude_calls: 0, fallbacks: 0 };
+  if (!fs.existsSync(BUDGET_FILE)) return fresh;
+  try { const b = JSON.parse(fs.readFileSync(BUDGET_FILE, "utf-8")); return b.day !== todayKey() ? fresh : b; } catch { return fresh; }
+}
+function saveBudget(b) {
+  if (!fs.existsSync(path.dirname(BUDGET_FILE))) fs.mkdirSync(path.dirname(BUDGET_FILE), { recursive: true });
+  fs.writeFileSync(BUDGET_FILE, JSON.stringify(b, null, 2));
+}
+function codexCallsBudgeted(runner) {
+  if (runner === "codex") return 1;
+  if (runner === "both") return 1;                       // 1 codex + 1 claude
+  if (runner.startsWith("reviewer:codex")) return 1;     // claude executes, codex reviews
+  if (runner.startsWith("reviewer:claude")) return 1;    // codex executes, claude reviews
+  return 0;
+}
+
+async function resolveRunner(requested, task) {
+  const budget = loadBudget();
+  const required = codexCallsBudgeted(requested);
+  if (required === 0) { budget.claude_calls += 1; saveBudget(budget); return requested; }
+
+  // Auto-promote single-model → both when severity warrants it (and budget allows).
+  const severity = (task.metadata && task.metadata.severity) || task.priority || "medium";
+  if ((requested === "claude" || requested === "codex") && SEVERITY_RANK[severity] >= SEVERITY_RANK[THRESHOLD]) {
+    if (budget.codex_calls + 1 <= DAILY_CAP) { budget.codex_calls += 1; budget.claude_calls += 1; saveBudget(budget); return "both"; }
+  }
+  // Budget check.
+  if (budget.codex_calls + required > DAILY_CAP) { budget.fallbacks += 1; budget.claude_calls += 1; saveBudget(budget); return "claude"; }
+  budget.codex_calls += required;
+  budget.claude_calls += requested === "both" ? 1 : 0;
+  saveBudget(budget);
+  return requested;
+}
+
+function getStatus() {
+  const b = loadBudget();
+  return { day: b.day, codex_used: b.codex_calls, codex_cap: DAILY_CAP, codex_remaining: Math.max(0, DAILY_CAP - b.codex_calls), claude_calls: b.claude_calls, fallbacks: b.fallbacks, threshold: THRESHOLD, fallback_chain: FALLBACK_CHAIN };
+}
+function pickClaudeModel() {
+  const b = loadBudget();
+  if (b.claude_calls < 200) return FALLBACK_CHAIN[0] || "claude-opus-4-7";
+  if (b.claude_calls < 1000) return FALLBACK_CHAIN[1] || FALLBACK_CHAIN[0];
+  return FALLBACK_CHAIN[FALLBACK_CHAIN.length - 1] || "claude-haiku-4-5";
+}
+
+module.exports = { resolveRunner, getStatus, pickClaudeModel, DAILY_CAP, THRESHOLD, FALLBACK_CHAIN };
+
+if (require.main === module) console.log(JSON.stringify(getStatus(), null, 2));

package/lib/runner/index.cjs

@@ -0,0 +1,93 @@
+/**
+ * Runner — top-level dispatcher.
+ *
+ * Reads a task's metadata.runner and dispatches to the right adapter:
+ *   - claude / codex            → single-model adapter (own git worktree)
+ *   - both                       → parallel cross-validation (two worktrees)
+ *   - reviewer:codex / :claude   → executor + reviewer pipeline
+ *
+ * Then updates the task in the kanban (PUT /api/tasks/:id):
+ *   - status: completed | in_review (on disagreement / needs-human)
+ *   - reportSummary, reportPath
+ *   - metadata.crossValidation: { agreement, verdict, confidence, ... }
+ *
+ * The adapters shell out to the `claude` / `codex` CLIs (which manage their own
+ * auth). If a CLI isn't on PATH the adapter falls back to a deterministic stub
+ * verdict, so this is safe to wire in before the CLIs are installed.
+ *
+ * CLI: node lib/runner/index.cjs <taskId>
+ */
+const config = require("../config.cjs");
+const claude = require("./adapters/claude.cjs");
+const codex = require("./adapters/codex.cjs");
+const both = require("./adapters/both.cjs");
+const reviewer = require("./adapters/reviewer.cjs");
+const wtm = require("./worktree-manager.cjs");
+const budget = require("./budget.cjs");
+
+const KANBAN_BASE = process.env.KANBAN_BASE || `http://localhost:${config.port}`;
+
+async function runTask(task, opts = {}) {
+  const requested = (task.metadata && task.metadata.runner) || opts.runner || "claude";
+  const effective = await budget.resolveRunner(requested, task);
+
+  let result;
+  if (effective === "claude") {
+    const wt = wtm.createWorktree(task.id, "claude");
+    try { result = await claude.run(task, { ...opts, worktree: wt }); } finally { wtm.removeWorktree(wt); }
+  } else if (effective === "codex") {
+    const wt = wtm.createWorktree(task.id, "codex");
+    try { result = await codex.run(task, { ...opts, worktree: wt }); } finally { wtm.removeWorktree(wt); }
+  } else if (effective === "both") {
+    result = await both.run(task, opts);
+  } else if (effective.startsWith("reviewer:")) {
+    result = await reviewer.run(task, { ...opts, runner: effective });
+  } else {
+    throw new Error(`Unknown runner: ${effective}`);
+  }
+
+  if (effective !== requested) result.budgetFallback = { requested, effective };
+  await pushResultToKanban(task.id, result);
+  return result;
+}
+
+async function pushResultToKanban(taskId, result) {
+  const status = result.needsHuman || result.agreement === "disagreed" ? "in_review" : "completed";
+  const summary =
+    result.verdict === "pass"
+      ? `pass · ${result.runner} (conf ${result.confidence != null ? result.confidence.toFixed(2) : "—"})`
+      : `${result.verdict === "needs_human" ? "needs human review" : result.verdict}${result.runner ? " [" + result.runner + "]" : ""}`;
+  const payload = {
+    status,
+    reportSummary: summary,
+    reportPath: result.reportPath || result.diffPath,
+    metadata: {
+      crossValidation: {
+        agreement: result.agreement || "agreed",
+        verdict: result.verdict,
+        confidence: result.confidence,
+        ...(result.budgetFallback ? { budgetFallback: result.budgetFallback } : {}),
+      },
+    },
+  };
+  try {
+    await fetch(`${KANBAN_BASE}/api/tasks/${taskId}`, { method: "PUT", headers: { "Content-Type": "application/json" }, body: JSON.stringify(payload) });
+  } catch (e) {
+    console.warn("[runner] kanban update failed:", e.message);
+  }
+}
+
+module.exports = { runTask };
+
+if (require.main === module) {
+  const taskId = process.argv[2];
+  if (!taskId) { console.error("usage: node lib/runner/index.cjs <taskId>"); process.exit(1); }
+  fetch(`${KANBAN_BASE}/api/tasks`)
+    .then((r) => r.json())
+    .then(async (tasks) => {
+      const t = tasks.find((x) => String(x.id) === String(taskId));
+      if (!t) { console.error(`task #${taskId} not found`); process.exit(1); }
+      const r = await runTask(t);
+      console.log(JSON.stringify({ taskId, runner: r.runner, verdict: r.verdict, agreement: r.agreement }, null, 2));
+    });
+}

package/lib/runner/result-merger.cjs

@@ -0,0 +1,58 @@
+/**
+ * Result merger — compares two runner results, classifies agreement, and writes a
+ * diff file for the "needs human" column to link to.
+ */
+const fs = require("fs");
+const path = require("path");
+const config = require("../config.cjs");
+
+const RUNS_DIR = path.join(config.repoRoot, "data", "runs");
+
+function compare(r1, r2) {
+  // Recover the task id from either report path: data/runs/task-<id>/...
+  const taskDir = [r1.reportPath, r2.reportPath].map((p) => (p || "").split(path.sep).find((seg) => seg.startsWith("task-"))).find(Boolean) || "task-unknown";
+  const dir = path.join(RUNS_DIR, taskDir);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  const diffPath = path.join(dir, "diff.md");
+
+  let agreement, verdict, confidence;
+  if (r1.verdict === r2.verdict) {
+    agreement = "agreed"; verdict = r1.verdict; confidence = ((r1.confidence || 0) + (r2.confidence || 0)) / 2;
+  } else if (r1.verdict === "needs_human" || r2.verdict === "needs_human" || r1.verdict === "fail" || r2.verdict === "fail") {
+    agreement = "disagreed"; verdict = "needs_human"; confidence = 0;
+  } else {
+    agreement = "partial";
+    verdict = (r1.confidence || 0) < (r2.confidence || 0) ? r1.verdict : r2.verdict;  // conservative: lower-confidence verdict wins
+    confidence = Math.min(r1.confidence || 0, r2.confidence || 0);
+  }
+
+  const md = [
+    "# Cross-validation diff",
+    "",
+    "| field | claude | codex |",
+    "|---|---|---|",
+    `| verdict | ${r1.verdict} | ${r2.verdict} |`,
+    `| confidence | ${r1.confidence} | ${r2.confidence} |`,
+    `| duration_ms | ${r1.duration_ms} | ${r2.duration_ms} |`,
+    `| mode | ${r1.mode || "live"} | ${r2.mode || "live"} |`,
+    "",
+    `**Agreement**: ${agreement}`,
+    `**Final verdict**: ${verdict}`,
+    `**Final confidence**: ${confidence.toFixed(2)}`,
+    "",
+    "## Claude summary",
+    r1.summary || "—",
+    "",
+    "## Codex summary",
+    r2.summary || "—",
+    "",
+    "## Action",
+    agreement === "agreed" ? "Auto-merge — both models concur." :
+    agreement === "partial" ? "Lower-confidence verdict adopted; review optional." :
+    "**Disagreed → moved to the \"needs human\" column. A human decides which verdict to take.**",
+  ].join("\n");
+  fs.writeFileSync(diffPath, md);
+  return { agreement, verdict, confidence, diffPath };
+}
+
+module.exports = { compare };

package/lib/runner/worktree-manager.cjs

@@ -0,0 +1,64 @@
+/**
+ * Git worktree manager — gives each parallel agent run its own working copy.
+ *
+ * Worktrees live at <repo-root>/data/worktrees/task-<id>-<runner>-<ts>/
+ * Branches are named  kanban/task-<id>-<runner>-<ts>
+ * Cleanup happens after the task completes (success or failure).
+ *
+ * The git repo the worktrees branch off is config.repoPath — the application
+ * repo this harness drives — not the harness checkout itself.
+ */
+const fs = require("fs");
+const path = require("path");
+const { execSync } = require("child_process");
+const config = require("../config.cjs");
+
+const REPO = config.repoPath;                                   // the app repo
+const WT_DIR = path.join(config.repoRoot, "data", "worktrees"); // worktrees stored here
+
+function ts() { return Date.now().toString(36); }
+function ensureDir(p) { if (!fs.existsSync(p)) fs.mkdirSync(p, { recursive: true }); }
+function q(s) { return "'" + String(s).replace(/'/g, "'\\''") + "'"; }
+function git(cmd, opts = {}) { return execSync(cmd, { cwd: REPO, encoding: "utf-8", ...opts }); }
+
+function createWorktree(taskId, runner) {
+  ensureDir(WT_DIR);
+  const tag = `${taskId}-${runner}-${ts()}`;
+  const wtPath = path.join(WT_DIR, `task-${tag}`);
+  const branch = `kanban/task-${tag}`;
+  if (fs.existsSync(wtPath)) {
+    try { git(`git worktree remove --force ${q(wtPath)}`); } catch {}
+    try { fs.rmSync(wtPath, { recursive: true, force: true }); } catch {}
+  }
+  git(`git worktree add -b ${q(branch)} ${q(wtPath)} HEAD`);
+  return { branch, path: wtPath, taskId, runner, createdAt: new Date().toISOString() };
+}
+function removeWorktree(wt) {
+  if (!wt || !wt.path) return;
+  try { git(`git worktree remove --force ${q(wt.path)}`); } catch {}
+  // Branch cleanup is optional — leave it for git gc.
+}
+function listWorktrees() {
+  let out = "";
+  try { out = git("git worktree list --porcelain"); } catch { return []; }
+  return out.split("\n\n").filter(Boolean).map((b) => {
+    const wt = {};
+    for (const l of b.split("\n")) {
+      const [k, ...rest] = l.split(" ");
+      if (k === "worktree") wt.path = rest.join(" ");
+      else if (k === "branch") wt.branch = rest.join(" ").replace("refs/heads/", "");
+      else if (k === "HEAD") wt.head = rest.join(" ");
+    }
+    return wt;
+  }).filter((wt) => wt.path && wt.path.startsWith(WT_DIR));
+}
+function cleanupOrphans(maxAgeHours = 24) {
+  const cutoff = Date.now() - maxAgeHours * 3600 * 1000;
+  let removed = 0;
+  for (const wt of listWorktrees()) {
+    try { if (fs.statSync(wt.path).mtimeMs < cutoff) { removeWorktree(wt); removed++; } } catch {}
+  }
+  return removed;
+}
+
+module.exports = { createWorktree, removeWorktree, listWorktrees, cleanupOrphans, WT_DIR };

package/lib/watch/scheduler.cjs

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+/**
+ * kanban-system — 24h watch scheduler.
+ *
+ * Reads detection rules from lib/detect/rules.json, runs the detectors enabled
+ * in config.js → detectors (or WATCH_ENABLED), and converts findings into kanban
+ * tasks via the local API.
+ *
+ * No npm dependencies — only fetch / fs / setInterval — so it also runs under a
+ * Deno scheduled function or a cron line. Loads <repo-root>/.env via lib/config.cjs
+ * (launchd / cron don't source your shell).
+ *
+ * Env:
+ *   WATCH_INTERVAL_MS  — base poll interval (default 300000 = 5 min)
+ *   KANBAN_BASE        — http://localhost:8080 (default; or config.js port)
+ *   WATCH_DRY_RUN      — "1" → log alerts, don't create tasks
+ *   WATCH_ENABLED      — comma-separated detector names; overrides config.js
+ *
+ * Usage:
+ *   node lib/watch/scheduler.cjs           # daemon
+ *   node lib/watch/scheduler.cjs --once    # single sweep, then exit
+ */
+const fs = require("fs");
+const path = require("path");
+const config = require("../config.cjs");
+
+const REPO_ROOT = config.repoRoot;
+const RULES_FILE = path.join(REPO_ROOT, "lib", "detect", "rules.json");
+const STATE_FILE = path.join(REPO_ROOT, "data", "runs", "watch-state.json");
+const FINDINGS_DIR = path.join(REPO_ROOT, "data", "runs", "watch-findings");
+const KANBAN_BASE = process.env.KANBAN_BASE || `http://localhost:${config.port}`;
+const INTERVAL = parseInt(process.env.WATCH_INTERVAL_MS || "300000", 10);
+const DRY_RUN = process.env.WATCH_DRY_RUN === "1";
+
+// Built-in detectors. Add yours here (and a row in rules.json + config.js → detectors).
+const detectors = {
+  sentry: require("../detect/sentry.cjs"),
+  vercel: require("../detect/vercel.cjs"),
+  // _template: require("../detect/_template.cjs"),  // copy & rename to wire up a new one
+};
+
+// Which detectors are on? WATCH_ENABLED wins; else config.js → detectors; else rules.json.
+function enabledDetectorNames() {
+  const fromEnv = (process.env.WATCH_ENABLED || "").split(",").map((s) => s.trim()).filter(Boolean);
+  if (fromEnv.length) return new Set(fromEnv);
+  const fromConfig = (config.detectors || []).filter((d) => d.enabled !== false).map((d) => d.detector);
+  if (fromConfig.length) return new Set(fromConfig);
+  return null; // null ⇒ "use rules.json `enabled` flags as-is"
+}
+
+function loadRules() {
+  if (!fs.existsSync(RULES_FILE)) return { rules: [] };
+  return JSON.parse(fs.readFileSync(RULES_FILE, "utf-8"));
+}
+function loadState() {
+  if (!fs.existsSync(STATE_FILE)) return { lastSweep: null, alerts: {} };
+  try { return JSON.parse(fs.readFileSync(STATE_FILE, "utf-8")); } catch { return { lastSweep: null, alerts: {} }; }
+}
+function saveState(s) {
+  if (!fs.existsSync(path.dirname(STATE_FILE))) fs.mkdirSync(path.dirname(STATE_FILE), { recursive: true });
+  fs.writeFileSync(STATE_FILE, JSON.stringify(s, null, 2));
+}
+function deduplicate(state, alert) {
+  // Same source+signal+severity within 1h → skip (avoid task spam)
+  const key = `${alert.source}:${alert.signal}:${alert.severity}`;
+  const last = state.alerts[key];
+  const now = Date.now();
+  if (last && now - last < 60 * 60 * 1000) return true;
+  state.alerts[key] = now;
+  return false;
+}
+
+// Heartbeats, transient API errors, and missing-config notices are operational
+// telemetry — they belong in sweep logs, never in the kanban backlog. Likewise any
+// severity:low signal. Only medium/high actionable findings become tasks.
+const INFORMATIONAL_SIGNALS = new Set(["heartbeat", "api-error", "config-missing"]);
+function isInformationalOnly(alert) {
+  if (alert.severity === "low") return true;
+  if (INFORMATIONAL_SIGNALS.has(alert.signal)) return true;
+  return false;
+}
+
+async function postTaskFromAlert(alert) {
+  const body = {
+    subject: `[${String(alert.severity || "medium").toUpperCase()}] ${alert.source}: ${alert.signal}`,
+    description:
+      `${alert.message || ""}\n\n` +
+      `**Source**: ${alert.source}\n**Signal**: ${alert.signal}\n**Severity**: ${alert.severity}\n` +
+      `**Threshold**: ${alert.threshold || "n/a"}\n**Value**: ${alert.value || "n/a"}\n` +
+      `**Routes to**: ${alert.routesTo || "orchestrator"}\n\n` +
+      (alert.evidence ? "## Evidence\n```\n" + JSON.stringify(alert.evidence, null, 2) + "\n```" : ""),
+    priority: alert.severity === "high" ? "high" : alert.severity === "low" ? "low" : "medium",
+    agent: alert.routesTo || "orchestrator",
+    metadata: {
+      source: "watch", detector: alert.source, signal: alert.signal, severity: alert.severity,
+      runner: alert.severity === "high" ? "both" : "claude", tag: "alert",
+    },
+  };
+  if (DRY_RUN) { console.log("[watch][dry-run]", JSON.stringify(body, null, 2)); return { id: "dry-run" }; }
+  const r = await fetch(`${KANBAN_BASE}/api/tasks`, {
+    method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body),
+  });
+  if (!r.ok) throw new Error(`POST /api/tasks failed: ${r.status}`);
+  return await r.json();
+}
+
+async function sweepOnce() {
+  const sweepId = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
+  const start = Date.now();
+  const rules = loadRules();
+  const state = loadState();
+  const enabled = enabledDetectorNames();
+  if (!fs.existsSync(FINDINGS_DIR)) fs.mkdirSync(FINDINGS_DIR, { recursive: true });
+
+  const findings = [];
+  const errors = [];
+
+  for (const ruleSet of rules.rules || []) {
+    if (enabled && !enabled.has(ruleSet.detector)) continue;
+    if (!enabled && ruleSet.enabled === false) continue;
+    const detector = detectors[ruleSet.detector];
+    if (!detector) { errors.push({ detector: ruleSet.detector, error: "no detector module registered in scheduler.cjs" }); continue; }
+    try {
+      const alerts = await detector.run(ruleSet, state);
+      for (const alert of alerts || []) {
+        if (isInformationalOnly(alert)) { findings.push({ ...alert, suppressed: "informational — logged, not ticketed" }); continue; }
+        if (deduplicate(state, alert)) { findings.push({ ...alert, deduped: true }); continue; }
+        try { const task = await postTaskFromAlert(alert); findings.push({ ...alert, taskId: task.id }); }
+        catch (e) { errors.push({ detector: ruleSet.detector, alert, error: e.message }); }
+      }
+    } catch (e) {
+      errors.push({ detector: ruleSet.detector, error: e.message });
+    }
+  }
+
+  state.lastSweep = new Date().toISOString();
+  saveState(state);
+
+  const summary = {
+    sweepId, duration_ms: Date.now() - start,
+    findings_count: findings.length,
+    suppressed: findings.filter((f) => f.suppressed).length,
+    deduped: findings.filter((f) => f.deduped).length,
+    posted: findings.filter((f) => f.taskId).length,
+    errors: errors.length,
+  };
+  fs.writeFileSync(
+    path.join(FINDINGS_DIR, `sweep-${sweepId}.md`),
+    `# Watch sweep ${sweepId}\n\n${JSON.stringify(summary, null, 2)}\n\n## Findings\n${JSON.stringify(findings, null, 2)}\n\n## Errors\n${JSON.stringify(errors, null, 2)}`,
+  );
+  console.log(`[watch] sweep ${sweepId} — ${summary.posted} posted / ${summary.suppressed} suppressed / ${summary.deduped} deduped / ${summary.errors} errors / ${summary.duration_ms}ms`);
+  return summary;
+}
+
+async function main() {
+  const isOnce = process.argv.includes("--once");
+  console.log(`[watch] kanban-system watch — interval=${INTERVAL}ms dryRun=${DRY_RUN} kanban=${KANBAN_BASE}`);
+  if (isOnce) { const r = await sweepOnce(); process.exit(r.errors > 0 ? 1 : 0); }
+  await sweepOnce().catch((e) => console.error("[watch] sweep error:", e));
+  setInterval(() => { sweepOnce().catch((e) => console.error("[watch] sweep error:", e)); }, INTERVAL);
+}
+
+if (require.main === module) main();
+module.exports = { sweepOnce };

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "kanban-system",
+  "version": "1.0.0",
+  "description": "A kanban board + multi-agent (Claude + Codex) ops/dev harness: routing, pre-deploy gates, incident playbooks, 24h monitoring, Telegram Ops Thread mirror.",
+  "keywords": [
+    "kanban",
+    "multi-agent",
+    "claude",
+    "codex",
+    "ops",
+    "harness",
+    "telegram",
+    "incident-response"
+  ],
+  "homepage": "https://github.com/Zakedu/kanban-system",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Zakedu/kanban-system.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Zakedu/kanban-system/issues"
+  },
+  "license": "MIT",
+  "main": "server/kanban.cjs",
+  "bin": {
+    "kanban-system": "./bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "server/",
+    "ui/",
+    "lib/",
+    "agents/",
+    "playbooks/",
+    "hooks/",
+    "skills/",
+    "docs/",
+    "config.example.js",
+    ".env.example",
+    "CLAUDE.md",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node server/kanban.cjs",
+    "dev": "node server/kanban.cjs",
+    "gate": "node lib/gate/index.cjs",
+    "watch": "node lib/watch/scheduler.cjs",
+    "watch:once": "node lib/watch/scheduler.cjs --once"
+  },
+  "dependencies": {
+    "@slack/bolt": "^4.1.0"
+  },
+  "optionalDependencies": {
+    "dotenv": "^16.4.5"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/playbooks/_TEMPLATE.html

@@ -0,0 +1,54 @@
+<!DOCTYPE html><html lang="en"><head><meta charset="UTF-8"><title>Playbook: TEMPLATE</title><link rel="stylesheet" href="./playbook.css"></head><body>
+<!-- Copy this file to playbooks/<incident-name>.html and fill in every section.
+     A playbook is a short, scannable runbook: when it fires, how to diagnose,
+     the decision tree, when to escalate, and what to do afterwards. Keep it on
+     one page. The orchestrator / agents link to it from tasks; humans read it
+     under pressure. -->
+<h1>Playbook · &lt;incident-name&gt;</h1>
+<div class="meta">
+  <span class="tag high">severity: &lt;low|medium|high&gt;</span>
+  <span class="tag group">&lt;owning area&gt;</span>
+  <span class="tag agent">&lt;owning agent&gt;</span>
+  <span class="tag low">SLA: &lt;target time to mitigate&gt;</span>
+</div>
+<div class="card danger">
+  <strong>Summary</strong> — One or two sentences: what state the system is in when this
+  fires, and the single most important thing to check first.
+</div>
+
+<h2>Trigger</h2>
+<ul>
+  <li>What detector / hook / observation creates a task that points here.</li>
+  <li>Any threshold that escalates an existing task to this playbook.</li>
+</ul>
+
+<h2>Diagnosis</h2>
+<ol>
+  <li>First thing to look at (a log path, a dashboard, a command).</li>
+  <li>How to localize the cause (correlate with deploys, with other signals).</li>
+  <li>How to confirm the hypothesis cheaply (reproduce locally, narrow the blast radius).</li>
+</ol>
+
+<h2>Decision tree</h2>
+<div class="tree">cause
+├─ &lt;case A&gt;  → &lt;action&gt; → re-run the gate / verify
+├─ &lt;case B&gt;  → &lt;route to which agent / which fix&gt;
+└─ &lt;case C&gt;  → &lt;rollback / escalate&gt;
+</div>
+
+<h2>Escalation</h2>
+<table>
+<tr><th>condition</th><th>action</th></tr>
+<tr><td>not mitigated within the SLA</td><td>page the on-call / post in the incident channel</td></tr>
+<tr><td>hotfix needed but the gate blocks it</td><td><code>KANBAN_GATE_BYPASS=1 git push</code> (audit-logged)</td></tr>
+</table>
+
+<h2>Aftermath</h2>
+<ul>
+  <li>Link the fix PR to the gate/run report.</li>
+  <li>If this pattern recurs (3×): file a task to add a check that catches it earlier.</li>
+  <li>Write a short postmortem if it had user impact.</li>
+</ul>
+
+<div class="footer">trigger: &lt;…&gt; · owner: &lt;agent&gt; · last reviewed: YYYY-MM-DD</div>
+</body></html>

package/playbooks/build-fail.html

@@ -0,0 +1,57 @@
+<!DOCTYPE html><html lang="en"><head><meta charset="UTF-8"><title>Playbook: build-fail</title><link rel="stylesheet" href="./playbook.css"></head><body>
+<h1>Playbook · build-fail</h1>
+<div class="meta">
+  <span class="tag high">severity: high</span>
+  <span class="tag group">deploy</span>
+  <span class="tag agent">deploy-gate-agent</span>
+  <span class="tag low">SLA: unblock the push within 30 min</span>
+</div>
+<div class="card danger">
+  <strong>Summary</strong> — A <code>deployCommands</code> stage (type-check / build / test)
+  failed, so the pre-push gate blocked the push. If a deploy was imminent, fix it now.
+</div>
+
+<h2>Trigger</h2>
+<ul>
+  <li>The pre-push hook failed on a <code>deployCommands</code> stage.</li>
+  <li>A local <code>npm run gate</code> failed.</li>
+  <li>monitor-agent saw the hosting provider report a deploy in an ERROR state.</li>
+</ul>
+
+<h2>Diagnosis</h2>
+<ol>
+  <li>Open the latest gate log: <code>data/runs/gate-&lt;ts&gt;/&lt;stage&gt;.log</code>.</li>
+  <li>The first error line usually has <code>file:line</code> — open it, check recent history (<code>git log -p &lt;file&gt;</code>).</li>
+  <li>Dependency issue? <code>npm ls</code> / check whether <code>package.json</code> changed; confirm runtime deps aren't in <code>devDependencies</code>.</li>
+  <li>Import path casing — CI is usually case-sensitive even if your dev machine isn't.</li>
+  <li>New <code>process.env.X</code> read that isn't in <code>.env.example</code>?</li>
+</ol>
+
+<h2>Decision tree</h2>
+<div class="tree">type-check error
+├─ single type error          → fix directly → re-run the gate
+├─ many files affected        → delegate a task to frontend-agent / backend-agent
+└─ shared types changed       → cross-check across the agents that depend on them
+
+build error
+├─ import not found           → check path / casing / extension
+├─ chunk too large            → file a code-splitting task to frontend-agent
+└─ env var missing            → sync .env.example + add it in the hosting console
+</div>
+
+<h2>Escalation</h2>
+<table>
+<tr><th>condition</th><th>action</th></tr>
+<tr><td>not unblocked within 30 min</td><td>post in the infra channel, pull in a lead</td></tr>
+<tr><td>hotfix needed but the gate blocks it</td><td><code>KANBAN_GATE_BYPASS=1 git push</code> (auto-logged to <code>data/runs/overrides.jsonl</code>)</td></tr>
+<tr><td>shared-type cascade failure</td><td>orchestrator dispatches the dependent agents in parallel</td></tr>
+</table>
+
+<h2>Aftermath</h2>
+<ul>
+  <li>Attach the gate report link to the fix PR.</li>
+  <li>If the same failure pattern recurs (3×) → file a task to add a lint/CI rule that catches it.</li>
+</ul>
+
+<div class="footer">trigger: pre-push hook · owner: deploy-gate-agent</div>
+</body></html>