kanban-system 1.0.0

package/docs/adapting-to-your-project.md

@@ -0,0 +1,155 @@
+# Adapting kanban-system to your project
+
+This harness ships generic. To point it at *your* front-end / back-end repo, you
+edit a handful of files. Nothing here knows about a particular framework — examples
+below cover common stacks, but the shape is the same everywhere.
+
+Prerequisites: Node ≥ 20, a git repo for your application, and (optionally) the
+`claude` and/or `codex` CLIs on PATH if you want the runner to actually execute work
+(without them the runner falls back to deterministic stub verdicts, which is fine for
+trying things out).
+
+---
+
+## Step 1 — `config.js`: point at your repo and your stack
+
+```bash
+cp config.example.js config.js     # config.js is gitignored
+cp .env.example .env               # fill in tokens; .env is gitignored
+```
+
+In `config.js`, set:
+- `projectName` — what shows in the board UI and Slack.
+- `repoPath` — **absolute** path to your application repo. The gate runs commands
+  here; the runner creates git worktrees here.
+- `kanbanPort` — default 8080 (env `PORT` overrides).
+- `deployCommands` — the build/test chain the gate runs, in order, fail-fast:
+  ```
+  Node / Vite:  [{ name:"01-typecheck", cmd:"npx", args:["tsc","--noEmit"] },
+                 { name:"02-build",     cmd:"npm", args:["run","build"] }]
+  Rust:         [{ name:"build", cmd:"cargo", args:["build","--release"] },
+                 { name:"test",  cmd:"cargo", args:["test"] }]
+  Go:           [{ name:"vet",  cmd:"go", args:["vet","./..."] },
+                 { name:"test", cmd:"go", args:["test","./..."] }]
+  Python:       [{ name:"lint",  cmd:"ruff", args:["check","."] },
+                 { name:"test",  cmd:"pytest", args:["-q"] }]
+  ```
+  Add an E2E stage too if you have one (e.g. a Playwright golden-path spec).
+- `buildOutputDir` — the built-output directory the gate inspects for bundle-size
+  regressions (`dist`, `build`, `.next`, …). Set to `null` to skip.
+
+---
+
+## Step 2 — `agents/`: make ownership match your directory layout
+
+Open `agents/frontend-agent.md` and `agents/backend-agent.md` and edit the `owns:`
+globs in the frontmatter so they match where your code actually lives. The
+orchestrator uses these to route "a task touches this file" → "this agent owns it".
+
+```
+# frontend-agent owns (examples)
+Next.js / CRA:  app/**, src/app/**, components/**, pages/**, styles/**, public/**
+Vite + React:   src/**, src/components/**, src/pages/**, src/styles/**, src/locales/**
+SvelteKit:      src/routes/**, src/lib/components/**, static/**
+
+# backend-agent owns (examples)
+Node API:       server/**, api/**, src/server/**, src/api/**
+Rails:          app/controllers/**, app/models/**, db/migrate/**
+Go services:    internal/**, cmd/**
+Supabase:       supabase/functions/**, supabase/migrations/**
+```
+
+Keep them **non-overlapping**. Need more roles than two? Copy `agents/_TEMPLATE.md`
+to `agents/<name>.md`, fill in the frontmatter (especially `name`, `mission`, `runner`,
+`owns`), and add it to `config.js → agents`. Leave `orchestrator.md`, `deploy-gate-agent.md`,
+`monitor-agent.md`, and `reviewer-codex.md` mostly as-is — they're already generic;
+just trim anything that doesn't apply.
+
+---
+
+## Step 3 — `lib/detect/`: wire up your monitoring (or skip it)
+
+`config.js → detectors` lists which detectors run on the 24h watch loop. Built-in:
+- **`sentry`** — error groups + error-rate spikes. Needs `SENTRY_AUTH_TOKEN`,
+  `SENTRY_ORG_SLUG`, `SENTRY_PROJECT_SLUG` in `.env`.
+- **`vercel`** — deploy state. Needs `VERCEL_TOKEN`, `VERCEL_PROJECT_ID` (+ `VERCEL_TEAM_ID`
+  for team accounts).
+
+Both degrade gracefully — if their env vars are blank they post a low-severity
+"config missing" task instead of crashing, so you can leave them enabled while you
+get around to it.
+
+Using something else (Datadog, CloudWatch, Prometheus, a `/healthz` endpoint, a
+custom metrics API)? Copy `lib/detect/_template.cjs` → `lib/detect/<name>.cjs`,
+implement `run(ruleSet, state)`, register it in the `detectors` map at the top of
+`lib/watch/scheduler.cjs`, add a `{ "detector": "<name>", ... }` block to
+`lib/detect/rules.json`, and enable it in `config.js → detectors`. No monitoring at
+all? Leave `detectors` empty — everything else still works.
+
+Tune thresholds in `lib/detect/rules.json` (the scheduler re-reads it every sweep —
+no restart).
+
+---
+
+## Step 4 — `agents/deploy-gate-agent.md` + `lib/gate/`: set your build/test commands
+
+The gate doesn't need code changes — it runs whatever you put in `config.js →
+deployCommands` (step 1). Just review `agents/deploy-gate-agent.md` so the prose
+matches what you configured (it's the playbook reviewers will read when the gate
+fails). The gate stages run serially, fail-fast; the failing stage's log lands in
+`data/runs/gate-<ts>/<stage>.log` and a "needs human" task is auto-created.
+
+---
+
+## Step 5 — `playbooks/`: one per incident you care about
+
+Start from `playbooks/_TEMPLATE.html`. Adapt the three example playbooks
+(`build-fail`, `e2e-regression`, `sentry-spike`) and `deploy-rollback`, and add your
+own — a payment-webhook failure, a queue backlog, a third-party outage, whatever your
+system actually has. Keep each on one page; they're read under pressure. The monitor
+agent routes anomalies into tasks; link the relevant playbook from those tasks (and
+from `agents/*.md`).
+
+---
+
+## Step 6 — `hooks/`: install the pre-push gate + schedule the watch
+
+**Pre-push gate** — install into *your application repo* (the one `config.js →
+repoPath` points at):
+```bash
+ln -sf /abs/path/to/kanban-system/hooks/pre-push.sample /abs/path/to/your-app/.git/hooks/pre-push
+chmod +x /abs/path/to/kanban-system/hooks/pre-push.sample
+export KANBAN_SYSTEM_DIR=/abs/path/to/kanban-system   # so the hook can find the harness
+```
+Now `git push` runs the gate; a human can override with `KANBAN_GATE_BYPASS=1 git push`
+(audit-logged to `data/runs/overrides.jsonl`).
+
+**24h watch** —
+- macOS: edit the three `__PLACEHOLDER__`s in `hooks/launchd.plist.template`, copy it
+  to `~/Library/LaunchAgents/`, `launchctl load` it.
+- Linux / cron: add the cron line from the comment at the top of that template
+  (`*/5 * * * * … scheduler.cjs --once`).
+
+---
+
+## Step 7 (optional) — Slack reporting
+
+Create a Slack app (bot + app token, Socket Mode), put `SLACK_BOT_TOKEN`,
+`SLACK_APP_TOKEN`, `SLACK_CHANNEL_ID` in `.env`, set `SLACK_COMMAND` (default
+`/kanban`). With that, the board posts start / progress / done updates, and the slash
+command works (`/kanban board`, `/kanban list`, `/kanban add`, `/kanban ask`,
+`/kanban exec`, `/kanban stop`). Without it, everything else runs fine — Slack is off.
+
+---
+
+## Run it
+
+```bash
+npm install
+npm start          # → http://localhost:8080
+```
+
+Then exercise it: open the board, create a task (UI or `POST /api/tasks`), watch it
+move. Run the gate (`npm run gate`). Run one watch sweep (`npm run watch:once`). See
+`docs/the-pattern.md` for *why* it's built this way, and `docs/example-apex.md` for a
+worked example from a real project.

package/docs/example-apex.md

@@ -0,0 +1,86 @@
+# Example: how APEX used this harness
+
+> This is the one place in the repo where project-specific domain content lives —
+> as a worked example, so the generic pieces have something concrete to point at.
+> Everything here is illustrative; nothing in `agents/`, `playbooks/`, or `lib/`
+> depends on it.
+
+**APEX** is an AI-skills certification exam platform — a React + TypeScript front end
+(Vite, React Router, i18n in three languages), a Supabase back end (Edge Functions in
+Deno, Postgres with row-level security, Supabase Auth + social OAuth), payments via a
+third-party SDK, Sentry for error tracking, deployed on Vercel + Supabase. The harness
+ran inside that repo under the codename "Sentinel". Here's how the generic patterns
+mapped onto a real, high-stakes system.
+
+## Config (`config.js`)
+- `repoPath` → the `apex-platform` checkout.
+- `deployCommands` → `npx tsc --noEmit` → `npm run build` (the Vite build, which is
+  exactly what Vercel runs) → `npx playwright test e2e/golden-path.spec.ts`.
+- `buildOutputDir` → `dist`.
+- The gate's golden paths (the E2E stage): sign in (email + Google + Kakao + Naver),
+  start exam → submit Part 1/2/3, result page → credential issuance, cart → payment →
+  order confirmation, admin cohort/voucher flows.
+
+## Agents
+APEX ran 14 agents split into two groups:
+
+- **OpsGuard (8)** — the generic dev/ops layer this template ships:
+  `orchestrator`, `route-agent` (React Router tree + i18n route slugs + lazy/Suspense),
+  `feature-agent` (front-end feature work — split here into `frontend-agent`),
+  `data-agent` (Supabase Edge Functions + migrations + RLS — split here into
+  `backend-agent`, always `runner: both`), `content-agent` (exam-question / rubric
+  validation — APEX-specific, not in the template), `e2e-agent` (Playwright golden
+  paths), `deploy-gate-agent`, `monitor-agent` (Sentry / Vercel / Supabase polling).
+- **ExamGuard (6)** — the *domain* layer, entirely APEX-specific and **not** part of
+  the template: `signup-agent` (sign-up funnel), `session-agent` (live exam sessions),
+  `notify-agent` (exam notifications), `proctor-agent` (cheating-signal detection —
+  see the human-approval note below), `grading-agent` (the Part-3 free-response
+  grading queue, `runner: both`), `credential-agent` (independent score recomputation
+  before a credential is issued, `runner: both`).
+
+The lesson for *your* project: keep the generic agents, add a domain group of your own
+the way APEX added ExamGuard.
+
+## A selvedge boundary that mattered: the exam engine
+APEX had an `exam-engine` selvedge — a small set of paths (the scoring/grading Edge
+Functions, the shared exam-data directory, the scoring/grading services on the front
+end) that *only* the exam-engine agent could modify; no other agent touched them. The
+shared `_shared/` helpers were a cross-check zone (exam-engine + backend jointly).
+This is the "non-overlapping ownership, with shared surfaces requiring a cross-check"
+idea from `docs/the-pattern.md` applied to the part of the system where a bug is most
+expensive — a wrong score on a certification exam.
+
+## A human-approval rule that's worth copying: the proctor agent
+APEX's `proctor-agent` detected possible cheating signals during a live exam — and
+its `runner` policy was deliberately conservative, and it had **zero auto-actions**.
+It never blocked, flagged, or failed a candidate on its own. It *recorded* the signal
+and routed a task to the "needs human" column; a person decided. The generalization:
+when an automated decision is high-consequence *and* about a person (a moderation
+action, an account suspension, a fraud flag), the agent's job is detection and
+escalation, never enforcement. Build the gate so a human is always the last signature.
+
+## Cross-validation, applied
+APEX used `runner: both` (independent re-implementation, diffed) for exactly the
+places you'd expect: Supabase migrations and RLS-policy changes (a bad one corrupts or
+leaks user data), Part-3 grading prompts (validated by a content reviewer, never edited
+solo), and credential score computation (recomputed independently before issuance).
+Everything else — front-end features, routing, the deploy gate — used `reviewer:codex`
+(Claude implements, Codex reviews). Deterministic work (Playwright runs, log polling,
+state transitions) ran single-model. A daily cap on the second model with a Claude
+fallback chain kept the cost bounded.
+
+## Governance / commit hygiene
+APEX wired the harness into a stricter governance system ("LOOM" — strict workflow
+"shuttles" for dev, content, partnerships, plus an always-on ops shuttle), enforced the
+kanban-first protocol from `agents/orchestrator.md` verbatim, required the pre-deploy
+gate to pass before any push, and used a `[APEX-XXX] type: description` commit
+convention referencing task IDs. None of that machinery is in the template — but the
+two load-bearing rules (task-first, gate-before-push) are.
+
+## Playbooks
+APEX shipped 12. The 6 ops ones generalize and ship here (build-fail, e2e-regression,
+sentry-spike, plus payment-webhook-fail, RLS-violation, content-flag — the first three
+adapted into `playbooks/`). The 6 exam ones were domain-specific (cheating-detected,
+grading-SLA-breach, credential-issuance-fail, session-stuck, signup-fail-spike,
+notification-bounce) and are not included — they're the ExamGuard equivalent of the
+playbooks you'll write for *your* domain.

package/docs/the-pattern.md

@@ -0,0 +1,92 @@
+# The pattern
+
+Why this harness is shaped the way it is. Five ideas, each one a constraint that's
+saved someone a bad day.
+
+## 1. Kanban-first: every instruction becomes a task before work starts
+
+When a person asks for something — "fix the login bug", "add a coupon field", "the
+build is failing" — the orchestrator's *first* action is to write a kanban task:
+capture the instruction verbatim in the description, derive a short subject, route
+it to an agent, set a runner, then transition it to `in_progress` and only then
+start the work.
+
+Why bother:
+- **Nothing is invisible.** Two agents (or an agent and a human) can't both quietly
+  be "working on the login thing" — there's one card, one owner, one state.
+- **Routing is explicit.** The agent and the runner (`claude` / `codex` / `both` /
+  `reviewer:*`) are written down, not implied.
+- **The trail exists.** `createdAt` / `startedAt` / `completedAt`, the report path,
+  the cross-validation verdict — all on the card.
+- **Standups write themselves** from the activity log.
+
+The one exception: **incident response.** If production is impacted (or about to be)
+and the fix is a small, obviously-reversible change, do it *now* — but register a
+post-hoc task within an hour, tagged `metadata.source = "incident-response"`, with
+what you did and any follow-up. Nothing else qualifies. Refactors, docs, features,
+ordinary bugs — task first.
+
+(Implemented by `agents/orchestrator.md`; the board is `server/kanban.cjs`.)
+
+## 2. Cross-validation: pick the verification level deliberately
+
+Every task has a `runner`. Three modes, in increasing cost and rigor:
+
+- **single-model** (`claude` or `codex`) — for deterministic / mechanical work where
+  a second opinion only adds latency: running a test suite, polling an API, applying
+  a state transition.
+- **`reviewer:codex`** (or `reviewer:claude`) — the executor model does the work in
+  an isolated git worktree and produces a verdict; the *other* model is handed that
+  report and asked to flag what was missed. Cheap, catches most mistakes. Default for
+  implementation work — front-end features, routing, the deploy gate, refactors. A
+  blocking flag downgrades the verdict to `needs_human`.
+- **`both`** — Claude *and* Codex independently do the work from the same spec, in
+  separate worktrees; the orchestrator diffs the two. Agreement → auto-merge.
+  Disagreement → the task moves to the "needs human" column. Use this for the
+  high-stakes stuff: schema migrations, access-control / RLS-style policies, anything
+  that can corrupt or leak data, money paths. **The disagreement is the safety
+  feature** — it's the system refusing to ship something two independent reads
+  couldn't converge on.
+
+The orchestrator can also *auto-promote*: a single-model task with severity ≥ a
+threshold (`CROSS_VALIDATION_THRESHOLD`) gets bumped to `both`, budget permitting.
+And there's a daily cap on the second model (`DAILY_CODEX_BUDGET`) — when it's spent,
+`codex` / `both` / `reviewer:codex` fall back to Claude alone, and Claude steps down
+through `MODEL_FALLBACK_CHAIN` under load. (Implemented by `lib/runner/`.)
+
+## 3. Selvedge boundaries: agents own non-overlapping territory
+
+Each agent declares `owns:` globs (relative to your repo). The orchestrator uses them
+to answer "which agent owns this file?" — and agents stay on their side of the line.
+`frontend-agent` doesn't touch the server; `backend-agent` doesn't touch components;
+the `deploy-gate-agent` never edits application code at all, it only runs commands.
+Shared surfaces — shared type definitions, dependency manifests, migrations — are the
+places that *require* a cross-check, which is exactly where `runner: both` earns its
+keep. Clean boundaries make routing automatic and make "who broke this?" answerable.
+
+## 4. Human-approval gates: some things never auto-merge
+
+A hard gate is one that *cannot* be bypassed by an agent — only by a human, audibly.
+Two in this harness:
+
+- **The pre-deploy gate** (`lib/gate/index.cjs`, run by `hooks/pre-push.sample` on
+  `git push`): runs your build/test commands fail-fast. Fail → push blocked, a
+  "needs human" task auto-created with the logs linked. The only override is `git push
+  --no-verify` or `KANBAN_GATE_BYPASS=1 git push`, the latter logged to
+  `data/runs/overrides.jsonl` and reviewed at standup.
+- **Cross-validation disagreement** (`runner: both`): when the two models disagree,
+  the task goes to the "needs human" column with a diff. No auto-merge. A person picks.
+
+The general principle: anything irreversible or externally visible (a deploy, a
+destructive migration, a money movement, in some projects a moderation action) gets a
+gate where a human is the last signature. Agents do the work; humans own the commit
+that ships it.
+
+## 5. Incident playbooks: scannable runbooks, not prose
+
+A playbook (`playbooks/*.html`) is a one-page runbook for one incident type: what
+fires it, how to diagnose, a decision tree, when to escalate, what to do afterwards.
+They're short and skimmable because they get read under pressure. Tasks link to them;
+the monitor agent routes anomalies into tasks that reference them. Start from
+`playbooks/_TEMPLATE.html`, write one per incident you actually care about, and keep
+each on a single page — if it grows past a screen, it's documentation, not a playbook.

package/hooks/launchd.plist.template

@@ -0,0 +1,66 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<!--
+  kanban-system — macOS launchd agent for the 24h watch daemon.
+
+  1. Replace the THREE __PLACEHOLDERS__ below:
+       __NODE_PATH__          e.g. /opt/homebrew/bin/node   (run `which node`)
+       __KANBAN_SYSTEM_DIR__  absolute path to your kanban-system checkout
+       __USER_HOME__          e.g. /Users/you                (run `echo $HOME`)
+  2. Rename the file to something stable, e.g. com.you.kanban-system.watch.plist,
+     and make the <key>Label</key> match the file name (without .plist).
+  3. Install:
+       cp com.you.kanban-system.watch.plist ~/Library/LaunchAgents/
+       launchctl load ~/Library/LaunchAgents/com.you.kanban-system.watch.plist
+     Stop:
+       launchctl unload ~/Library/LaunchAgents/com.you.kanban-system.watch.plist
+     Logs:
+       tail -f ~/Library/Logs/kanban-system/watch.{out,err}.log
+
+  CRON ALTERNATIVE (Linux, or if you'd rather use cron):
+     # run a single sweep every 5 minutes — the scheduler reads .env via lib/config.cjs
+     */5 * * * * cd __KANBAN_SYSTEM_DIR__ && __NODE_PATH__ lib/watch/scheduler.cjs --once >> __KANBAN_SYSTEM_DIR__/data/logs/watch-cron.log 2>&1
+-->
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.you.kanban-system.watch</string>
+
+  <key>ProgramArguments</key>
+  <array>
+    <string>__NODE_PATH__</string>
+    <string>__KANBAN_SYSTEM_DIR__/lib/watch/scheduler.cjs</string>
+  </array>
+
+  <key>WorkingDirectory</key>
+  <string>__KANBAN_SYSTEM_DIR__</string>
+
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>WATCH_INTERVAL_MS</key>
+    <string>300000</string>
+    <key>NODE_ENV</key>
+    <string>production</string>
+  </dict>
+
+  <key>RunAtLoad</key>
+  <true/>
+
+  <key>KeepAlive</key>
+  <dict>
+    <key>SuccessfulExit</key>
+    <false/>
+    <key>Crashed</key>
+    <true/>
+  </dict>
+
+  <key>ThrottleInterval</key>
+  <integer>30</integer>
+
+  <key>StandardOutPath</key>
+  <string>__USER_HOME__/Library/Logs/kanban-system/watch.out.log</string>
+
+  <key>StandardErrorPath</key>
+  <string>__USER_HOME__/Library/Logs/kanban-system/watch.err.log</string>
+</dict>
+</plist>

package/hooks/pre-push.sample

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+# kanban-system pre-push hook — runs the deploy gate before allowing a push.
+#
+# Install into YOUR APPLICATION REPO (the one config.js → repoPath points at):
+#   ln -sf /absolute/path/to/kanban-system/hooks/pre-push.sample .git/hooks/pre-push
+#   chmod +x /absolute/path/to/kanban-system/hooks/pre-push.sample
+# (Or copy it, if you prefer not to symlink.)
+#
+# Tell it where the harness lives — either edit KANBAN_SYSTEM_DIR below, or export it:
+#   export KANBAN_SYSTEM_DIR=/absolute/path/to/kanban-system
+#
+# Bypass (audited — logs to kanban-system/data/runs/overrides.jsonl):
+#   KANBAN_GATE_BYPASS=1 git push
+# Bypass entirely (not logged):
+#   git push --no-verify
+
+set -e
+
+# --- where is the harness? -----------------------------------------------------
+KANBAN_SYSTEM_DIR="${KANBAN_SYSTEM_DIR:-}"
+if [ -z "$KANBAN_SYSTEM_DIR" ]; then
+  # Best effort: if this hook is a symlink, follow it to find the harness root.
+  HOOK_PATH="$(readlink -f "$0" 2>/dev/null || echo "$0")"
+  KANBAN_SYSTEM_DIR="$(cd "$(dirname "$HOOK_PATH")/.." 2>/dev/null && pwd || true)"
+fi
+GATE_RUNNER="$KANBAN_SYSTEM_DIR/lib/gate/index.cjs"
+
+if [ -z "$KANBAN_SYSTEM_DIR" ] || [ ! -f "$GATE_RUNNER" ]; then
+  echo "[kanban-system] gate runner not found (set KANBAN_SYSTEM_DIR) — skipping gate"
+  exit 0
+fi
+
+# --- audited bypass ------------------------------------------------------------
+if [ "$KANBAN_GATE_BYPASS" = "1" ]; then
+  echo "[kanban-system] BYPASS — gate skipped (audit logged)"
+  OVERRIDE_LOG="$KANBAN_SYSTEM_DIR/data/runs/overrides.jsonl"
+  mkdir -p "$(dirname "$OVERRIDE_LOG")"
+  printf '{"timestamp":"%s","branch":"%s","user":"%s","reason":"KANBAN_GATE_BYPASS=1"}\n' \
+    "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+    "$(git rev-parse --abbrev-ref HEAD)" \
+    "$(git config user.email || whoami)" \
+    >> "$OVERRIDE_LOG"
+  exit 0
+fi
+
+# --- run the gate --------------------------------------------------------------
+BRANCH="$(git rev-parse --abbrev-ref HEAD)"
+echo "[kanban-system] running pre-deploy gate for branch '$BRANCH'..."
+node "$GATE_RUNNER"
+GATE_EXIT=$?
+
+if [ $GATE_EXIT -ne 0 ]; then
+  echo ""
+  echo "[kanban-system] ✗ gate FAILED (exit $GATE_EXIT). Push BLOCKED."
+  echo "[kanban-system] reports: $KANBAN_SYSTEM_DIR/data/runs/gate-*/"
+  echo "[kanban-system] to bypass (logged): KANBAN_GATE_BYPASS=1 git push"
+  exit $GATE_EXIT
+fi
+
+echo "[kanban-system] ✓ gate passed. Push allowed."
+exit 0

package/lib/config.cjs

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+/**
+ * kanban-system config loader.
+ *
+ * Resolution order:
+ *   1. <repo-root>/config.js          (your edited copy — gitignored)
+ *   2. <repo-root>/config.example.js  (template fallback, so the server boots)
+ *   3. env-var overrides on top of whatever loaded
+ *
+ * Also loads <repo-root>/.env (without a dependency) so launchd / cron — which
+ * don't source your shell — still see SLACK_*, SENTRY_*, etc.
+ *
+ * `require("../lib/config.cjs")` from anywhere in the repo returns the merged
+ * config object. The repo root is the parent of lib/.
+ */
+const fs = require("fs");
+const path = require("path");
+
+const REPO_ROOT = path.resolve(__dirname, "..");
+
+// ── Load <repo-root>/.env without external deps ──────────────────────────────
+(function loadDotEnv() {
+  const envPath = path.join(REPO_ROOT, ".env");
+  if (!fs.existsSync(envPath)) return;
+  for (let line of fs.readFileSync(envPath, "utf-8").split(/\r?\n/)) {
+    line = line.trim();
+    if (!line || line.startsWith("#")) continue;
+    const eq = line.indexOf("=");
+    if (eq < 0) continue;
+    const key = line.slice(0, eq).trim();
+    let val = line.slice(eq + 1);
+    if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+      val = val.slice(1, -1);
+    }
+    if (process.env[key] === undefined || process.env[key] === "") process.env[key] = val;
+  }
+})();
+
+// ── Load config.js (or fall back to config.example.js) ───────────────────────
+function loadProjectConfig() {
+  const realPath = path.join(REPO_ROOT, "config.js");
+  const examplePath = path.join(REPO_ROOT, "config.example.js");
+  let cfg = {};
+  let source = null;
+  if (fs.existsSync(realPath)) {
+    cfg = require(realPath);
+    source = realPath;
+  } else if (fs.existsSync(examplePath)) {
+    cfg = require(examplePath);
+    source = examplePath;
+    if (!process.env.KANBAN_QUIET_CONFIG) {
+      console.warn("[config] config.js not found — using config.example.js. Copy it: cp config.example.js config.js");
+    }
+  }
+  return { cfg: cfg || {}, source };
+}
+
+const { cfg, source } = loadProjectConfig();
+
+// ── Env-var overrides ────────────────────────────────────────────────────────
+const port =
+  (process.env.PORT && parseInt(process.env.PORT, 10)) ||
+  cfg.kanbanPort ||
+  8080;
+
+const slack = Object.assign(
+  {
+    botToken: "",
+    appToken: "",
+    channelId: "",
+    webhookUrl: "",
+    adminUsers: [],
+    command: "/kanban",
+  },
+  cfg.slack || {},
+);
+if (process.env.SLACK_BOT_TOKEN) slack.botToken = process.env.SLACK_BOT_TOKEN;
+if (process.env.SLACK_APP_TOKEN) slack.appToken = process.env.SLACK_APP_TOKEN;
+if (process.env.SLACK_CHANNEL_ID) slack.channelId = process.env.SLACK_CHANNEL_ID;
+if (process.env.SLACK_AGENT_WEBHOOK) slack.webhookUrl = process.env.SLACK_AGENT_WEBHOOK;
+if (process.env.SLACK_ADMIN_USERS) slack.adminUsers = process.env.SLACK_ADMIN_USERS.split(",").filter(Boolean);
+if (process.env.SLACK_COMMAND) slack.command = process.env.SLACK_COMMAND;
+
+// ── Telegram (optional — Ops Thread mirror panel) ────────────────────────────
+// Drop in TELEGRAM_BOT_TOKEN + TELEGRAM_CHAT_ID and the kanban server starts
+// mirroring the Ops Thread panel to that Telegram chat (and pulls operator
+// replies back via getUpdates polling). Both blank ⇒ panel still works locally
+// as a kanban-only chat; it just doesn't sync with Telegram.
+const telegram = Object.assign(
+  {
+    botToken: "",          // BotFather → token
+    chatId: "",            // DM chat id (run /api/telegram/whoami → "send any DM to your bot, then GET /api/telegram/whoami")
+    allowedChatIds: [],    // optional allowlist; empty ⇒ chatId only
+    pollEnabled: true,     // start the long-poll worker on boot when token+chatId present
+    pollIntervalMs: 1500,  // gap between long-poll cycles (long-poll itself blocks 25s)
+  },
+  cfg.telegram || {},
+);
+if (process.env.TELEGRAM_BOT_TOKEN) telegram.botToken = process.env.TELEGRAM_BOT_TOKEN;
+if (process.env.TELEGRAM_CHAT_ID) telegram.chatId = process.env.TELEGRAM_CHAT_ID;
+if (process.env.TELEGRAM_ALLOWED_CHAT_IDS) telegram.allowedChatIds = process.env.TELEGRAM_ALLOWED_CHAT_IDS.split(",").map((s) => s.trim()).filter(Boolean);
+if (process.env.TELEGRAM_POLL_ENABLED) telegram.pollEnabled = process.env.TELEGRAM_POLL_ENABLED !== "0";
+if (process.env.TELEGRAM_POLL_INTERVAL_MS) telegram.pollIntervalMs = parseInt(process.env.TELEGRAM_POLL_INTERVAL_MS, 10);
+
+const config = {
+  repoRoot: REPO_ROOT,
+  configSource: source,
+  projectName: cfg.projectName || path.basename(cfg.repoPath || REPO_ROOT),
+  // Absolute path to the application repo this harness drives. Defaults to the
+  // harness repo itself if unset (so demos work), but you should set it.
+  repoPath: cfg.repoPath ? path.resolve(cfg.repoPath) : REPO_ROOT,
+  port,
+  deployCommands: cfg.deployCommands || [],
+  buildOutputDir: cfg.buildOutputDir || null,
+  agents: cfg.agents || [],
+  detectors: cfg.detectors || [],
+  gateTimeoutMs: parseInt(process.env.GATE_TIMEOUT_MS || "600000", 10),
+  slack,
+  telegram,
+};
+
+module.exports = config;
+
+// Allow `node lib/config.cjs` to print the resolved config.
+if (require.main === module) {
+  const redacted = JSON.parse(JSON.stringify(config));
+  redacted.slack = {
+    ...redacted.slack,
+    botToken: redacted.slack.botToken ? "(set)" : "",
+    appToken: redacted.slack.appToken ? "(set)" : "",
+    webhookUrl: redacted.slack.webhookUrl ? "(set)" : "",
+  };
+  redacted.telegram = {
+    ...redacted.telegram,
+    botToken: redacted.telegram.botToken ? "(set)" : "",
+  };
+  console.log(JSON.stringify(redacted, null, 2));
+}

package/lib/detect/_template.cjs

@@ -0,0 +1,63 @@
+/**
+ * Detector template — copy this to lib/detect/<name>.cjs, register it in
+ * lib/watch/scheduler.cjs (the `detectors` map), add a `{ "detector": "<name>" ... }`
+ * block to lib/detect/rules.json, and enable it in config.js → detectors.
+ *
+ * A detector exports `run(ruleSet, state)` and returns an array of alert objects.
+ * It must:
+ *   - degrade gracefully when its credentials/config are missing (return a single
+ *     low-severity "config-missing" alert, deduped, instead of throwing);
+ *   - never throw out of `run` for a transient API error — catch it and return a
+ *     low-severity "api-error" alert;
+ *   - keep state it needs (baselines, "already seen" markers) on the `state` object —
+ *     the scheduler persists it to data/runs/watch-state.json between sweeps.
+ *
+ * Alert shape (only `source`, `signal`, `severity` are required):
+ *   {
+ *     source:    "<detector name>",
+ *     signal:    "<machine-readable signal id, matches rules.json>",
+ *     severity:  "low" | "medium" | "high" | "critical",
+ *     message:   "human-readable one-liner",
+ *     threshold: "what the limit was",          // optional, for the task body
+ *     value:     "what we observed",            // optional
+ *     routesTo:  "frontend-agent",              // optional; which agent the task goes to
+ *     evidence:  { ...arbitrary JSON... }       // optional; gets dumped into the task
+ *   }
+ *
+ * Example skeleton for "datadog" — replace with your monitoring of choice
+ * (CloudWatch, Prometheus, a /healthz endpoint, a custom metrics API, …):
+ */
+const API_KEY = process.env.DATADOG_API_KEY || "";
+const APP_KEY = process.env.DATADOG_APP_KEY || "";
+
+async function run(ruleSet, state) {
+  // 1. Config check — surface the gap once a day, don't crash.
+  if (!API_KEY || !APP_KEY) {
+    const k = "datadog:config-missing";
+    if (state.alerts[k] && Date.now() - state.alerts[k] < 24 * 3600 * 1000) return [];
+    return [{
+      source: "datadog", signal: "config-missing", severity: "low",
+      message: "DATADOG_API_KEY / DATADOG_APP_KEY not set — this detector is disabled.",
+      threshold: "env present", value: "missing", routesTo: "orchestrator",
+      evidence: { needs: ["DATADOG_API_KEY", "DATADOG_APP_KEY"] },
+    }];
+  }
+
+  const alerts = [];
+  try {
+    // 2. Fetch a metric / query a log search / hit a health endpoint.
+    //    const data = await fetch("https://api.datadoghq.com/api/v1/query?...", { headers: { "DD-API-KEY": API_KEY, "DD-APPLICATION-KEY": APP_KEY } }).then(r => r.json());
+
+    // 3. Compare against a threshold (and/or a rolling baseline you keep on `state`).
+    //    const baseline = state["datadog:baseline:errors"] || null;
+    //    if (baseline && observed > baseline * 3) alerts.push({ source: "datadog", signal: "...", severity: "high", ... });
+    //    state["datadog:baseline:errors"] = baseline ? baseline * 0.8 + observed * 0.2 : observed;
+
+    // 4. Optional heartbeat (deduped, so the operator knows polling is alive).
+  } catch (e) {
+    return [{ source: "datadog", signal: "api-error", severity: "low", message: `Datadog API error: ${e.message}`, routesTo: "orchestrator", evidence: { error: e.message } }];
+  }
+  return alerts;
+}
+
+module.exports = { run };