@phuthuycoding/kanban-flow 0.3.0

package/dist/cli/commands/run.js

@@ -0,0 +1,156 @@
+import { relative, join } from "node:path";
+import { findFeature, listFeatures } from "../../workflow/features.js";
+import { STAGES } from "../../workflow/schema.js";
+import { readProjectConfig } from "../../project/config.js";
+import { resolveChain } from "../../harness/prompt.js";
+import { provisionSession } from "../../harness/session.js";
+import { executeChain, planFor } from "../../harness/chain.js";
+import { isPidAlive, runningRun, DEFAULT_TIMEOUT_MS } from "../../harness/run.js";
+import { startDetached, superviseRun } from "../../harness/supervise.js";
+import { findRoot } from "./helpers.js";
+function parseTimeout(raw) {
+    if (raw === undefined)
+        return DEFAULT_TIMEOUT_MS;
+    const minutes = Number(raw);
+    if (!Number.isFinite(minutes) || minutes < 0)
+        throw new Error(`Invalid --timeout '${String(raw)}': expected minutes (0 = no limit).`);
+    return Math.round(minutes * 60_000);
+}
+function renderOutcome(root, feature, outcome) {
+    const r = outcome.record;
+    const lines = [
+        `${outcome.ok ? "✓" : "✗"} ${r.chain ? `[${r.chain.index}/${r.chain.total}] ` : ""}${r.role} (${r.runner}) run ${r.id} @ ${r.stage} (${r.mode}) — ${r.status}${r.exitCode === undefined ? "" : `, exit ${r.exitCode}`}`,
+        `  Log: ${relative(root, join(feature.dir, r.log))}`,
+        `  STATUS: ${r.statusLine ?? "(missing)"}`,
+    ];
+    if (r.summary)
+        lines.push(`  Summary: ${r.summary}`);
+    if (r.usage)
+        lines.push(`  Usage: ${r.usage.input} in / ${r.usage.output} out${r.usage.costUsd === undefined ? "" : ` / $${r.usage.costUsd.toFixed(4)}`}`);
+    if (r.warning)
+        lines.push(`  ⚠ ${r.warning}`);
+    if (r.error)
+        lines.push(`  ✗ ${r.error}`);
+    if (outcome.note)
+        lines.push(`  ${outcome.note}`);
+    if (!outcome.ok && r.statusLine === null && r.exitCode === 0)
+        lines.push("  Worker exited 0 without a STATUS line — not treated as done.");
+    return lines.join("\n");
+}
+function renderChain(root, feature, summary) {
+    const lines = summary.outcomes.map((o) => renderOutcome(root, feature, o));
+    if (summary.stoppedAt) {
+        lines.push(`✗ Chain stopped at role "${summary.stoppedAt}"${summary.skipped.length > 0 ? `; not run: ${summary.skipped.join(", ")}` : ""}`);
+    }
+    return lines.join("\n\n");
+}
+export async function cmdRun(args, cwd) {
+    const name = args.positionals[0];
+    if (!name)
+        return { code: 1, stdout: "Usage: kf run <feature> [--stage <s>] [--role <r>] [--fresh] [--detach] [--timeout <min>] [--dry-run]", stderr: "missing feature" };
+    if (args.options.agent !== undefined) {
+        return { code: 1, stdout: "--agent was replaced by --role: stages are assigned to roles (harness.roles), and a role points at a runner. See: kf harness", stderr: "agent flag removed" };
+    }
+    const root = await findRoot(cwd);
+    if (!root.ok)
+        return { code: 1, stdout: root.err, stderr: "no works" };
+    const feature = findFeature(root.root, name);
+    if (!feature)
+        return { code: 1, stdout: `Unknown feature '${name}'. Run: kf list`, stderr: "unknown feature" };
+    if (typeof args.options.supervise === "string") {
+        const summary = await superviseRun(root.root, name, args.options.supervise);
+        return { code: summary.ok ? 0 : 1, stdout: renderChain(root.root, findFeature(root.root, name) ?? feature, summary) };
+    }
+    const stageRaw = args.options.stage;
+    if (stageRaw !== undefined && !STAGES.includes(String(stageRaw))) {
+        return { code: 1, stdout: `Unknown stage '${String(stageRaw)}'. Stages: ${STAGES.join(", ")}`, stderr: "unknown stage" };
+    }
+    const cfg = readProjectConfig(root.root);
+    const resolved = resolveChain(cfg.harness, feature, root.root, {
+        stage: stageRaw === undefined ? undefined : String(stageRaw),
+        role: typeof args.options.role === "string" ? args.options.role : undefined,
+    });
+    if (!resolved.ok)
+        return { code: 1, stdout: resolved.reason, stderr: "not assigned" };
+    const chain = resolved.chain;
+    const timeoutMs = parseTimeout(args.options.timeout);
+    const fresh = Boolean(args.options.fresh);
+    if (args.options["dry-run"]) {
+        const blocks = chain.map((assignment, index) => {
+            const plan = planFor(root.root, feature, assignment, { fresh, timeoutMs }, index === 0 ? null : { role: chain[index - 1].role, output: chain[index - 1].output, log: "<log of the previous run, known at run time>" }, { id: "<chain>", index: index + 1, total: chain.length });
+            const provisioned = provisionSession(plan.runner, feature.meta?.sessions?.[plan.role], plan.prompt, fresh);
+            return `[${index + 1}/${chain.length}] ${assignment.role} (${assignment.runnerName}) — ${provisioned.mode}\n\nargv:\n${provisioned.argv.map((a) => `  ${JSON.stringify(a)}`).join("\n")}\n\nprompt:\n${plan.prompt}`;
+        });
+        return { code: 0, stdout: `Dry run — stage ${chain[0].stage}, chain: ${chain.map((a) => a.role).join(" → ")}\n\n${blocks.join("\n\n---\n\n")}` };
+    }
+    const active = runningRun(feature);
+    if (active)
+        return { code: 1, stdout: `Run ${active.id} (${active.role} @ ${active.stage}) is still running for '${name}'. Wait for it or check: kf runs ${name}`, stderr: "run in progress" };
+    if (args.options.detach) {
+        const record = await startDetached(root.root, name, chain, { fresh, timeoutMs });
+        const rest = chain.slice(1).map((a) => a.role);
+        return {
+            code: 0,
+            stdout: `▶ Chain ${record.id} started detached: ${chain.map((a) => `${a.role} (${a.runnerName})`).join(" → ")}\n  Log: ${relative(root.root, join(feature.dir, record.log))}${rest.length > 0 ? `\n  Remaining roles run after the first one finishes: ${rest.join(", ")}` : ""}\n  Poll with: kf runs ${name}`,
+        };
+    }
+    const summary = await executeChain(root.root, name, chain, { fresh, timeoutMs });
+    return {
+        code: summary.ok ? 0 : 1,
+        stdout: renderChain(root.root, findFeature(root.root, name) ?? feature, summary),
+        stderr: summary.ok ? undefined : "chain not done",
+    };
+}
+/**
+ * A chain that stopped early looks exactly like a finished one unless we say so:
+ * flag the last run of a chain whose position is short of `total` and that has
+ * no live run after it, so a detached supervisor dying mid-chain is visible.
+ */
+export function runViews(features) {
+    const views = [];
+    for (const f of features) {
+        const runs = f.meta?.runs ?? [];
+        const lastOfChain = new Map();
+        for (const r of runs)
+            if (r.chain)
+                lastOfChain.set(r.chain.id, r);
+        const anyLive = runs.some((r) => r.status === "running" && (isPidAlive(r.pid) || isPidAlive(r.supervisorPid)));
+        for (const r of runs) {
+            const lost = r.status === "running" && !isPidAlive(r.pid) && !isPidAlive(r.supervisorPid);
+            const broken = Boolean(r.chain && r.chain.index < r.chain.total && lastOfChain.get(r.chain.id)?.id === r.id && !anyLive);
+            views.push({
+                ...r, feature: f.name, chainBroken: broken,
+                displayStatus: lost ? "failed (supervisor lost)" : broken ? `${r.status} (chain stopped ${r.chain.index}/${r.chain.total})` : r.status,
+            });
+        }
+    }
+    return views.sort((a, b) => b.at.localeCompare(a.at));
+}
+export async function cmdRuns(args, cwd) {
+    const root = await findRoot(cwd);
+    if (!root.ok)
+        return { code: 1, stdout: root.err, stderr: "no works" };
+    const name = args.positionals[0];
+    let features;
+    if (name) {
+        const f = findFeature(root.root, name);
+        if (!f)
+            return { code: 1, stdout: `Unknown feature '${name}'. Run: kf list`, stderr: "unknown feature" };
+        features = [f];
+    }
+    else {
+        // Runs of finished or dropped work are history: only show them when asked by name.
+        features = listFeatures(root.root).filter((f) => f.stage !== "dones" && f.stage !== "cancelled");
+    }
+    const views = runViews(features);
+    if (args.options.json)
+        return { code: 0, stdout: JSON.stringify(views, null, 2) };
+    if (views.length === 0)
+        return { code: 0, stdout: name ? `No runs for '${name}'.` : "No runs." };
+    const lines = views.map((v) => `${v.id}  ${v.feature.padEnd(20)} ${(v.chain ? `${v.chain.index}/${v.chain.total} ` : "").padEnd(4)}${v.role.padEnd(12)} ${v.runner.padEnd(10)} ${v.stage.padEnd(14)} ${v.mode.padEnd(6)} ${v.displayStatus.padEnd(30)} ${v.at}${v.statusLine ? `  STATUS: ${v.statusLine}` : ""}`);
+    const broken = views.filter((v) => v.chainBroken);
+    if (broken.length > 0) {
+        lines.push("", ...broken.map((v) => `⚠ ${v.feature}: role chain stopped at ${v.role} (${v.chain.index}/${v.chain.total}); the remaining roles never ran — re-run the stage with kf run.`));
+    }
+    return { code: 0, stdout: lines.join("\n") };
+}

package/dist/cli/commands/stage.js

@@ -0,0 +1,186 @@
+import { rename } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { STAGES, TRANSITIONS } from "../../workflow/schema.js";
+import { findFeature, stageDir, writeFeatureMeta } from "../../workflow/features.js";
+import { cmdArchive } from "./archive.js";
+import { validateFeature, checkDirectionGate, renderValidateText } from "../../workflow/validate.js";
+import { runHook, resolveHook } from "../../integrations/hooks.js";
+import { findRoot, recordBypasses, bypassNote } from "./helpers.js";
+export async function cmdStage(args, cwd) {
+    const [name, toRaw] = args.positionals;
+    if (!name || !toRaw) {
+        return {
+            code: 1,
+            stdout: "Usage: kf stage <feature> <next-stage>\nStages: brainstorm → planning → backlog → implementation → testing → review → dones",
+            stderr: "missing args",
+        };
+    }
+    const to = toRaw;
+    if (!STAGES.includes(to)) {
+        return { code: 1, stdout: `Unknown stage '${to}'. Stages: ${STAGES.join(" → ")}`, stderr: "unknown stage" };
+    }
+    const root = await findRoot(cwd);
+    if (!root.ok)
+        return { code: 1, stdout: root.err, stderr: "no works" };
+    const f = findFeature(root.root, name);
+    if (!f)
+        return { code: 1, stdout: `Unknown feature '${name}'. Run: kf list`, stderr: "unknown feature" };
+    if (f.stage === "dones") {
+        return { code: 1, stdout: `Feature '${name}' is already archived (dones).`, stderr: "already dones" };
+    }
+    // A cancelled item has exactly one way back: the stage it was cancelled from.
+    let isReopen = false;
+    if (f.stage === "cancelled") {
+        const from = f.meta?.cancellation?.fromStage;
+        if (!from) {
+            return { code: 1, stdout: `'${name}' is cancelled but its metadata has no fromStage, so kf cannot tell where it belongs. Re-run with --force to place it anywhere.`, stderr: "cancellation missing" };
+        }
+        if (to !== from && !args.options.force) {
+            return { code: 1, stdout: `Cancelled '${name}' can only be reopened at ${from} (where it was cancelled). Run: kf stage ${name} ${from}`, stderr: "wrong reopen stage" };
+        }
+        isReopen = to === from;
+    }
+    const allowed = TRANSITIONS[f.stage];
+    if (f.stage !== "cancelled" && !allowed.includes(to)) {
+        const desc = allowed.join(", ");
+        return {
+            code: 1,
+            stdout: `Cannot move '${name}' ${f.stage} → ${to}. Allowed: ${desc}.`,
+            stderr: "not allowed transition",
+        };
+    }
+    // Reopening into `dones` is putting an item back where it was, not archiving it again. Routing
+    // it through archive made `kf cancel`'s own advertised reopen command refuse itself, with no
+    // escape: archive rejects a cancelled item before it ever looks at --force. The move happens
+    // below, and the archive state it had is restored right after — see the isReopen tail.
+    if (to === "dones" && !isReopen)
+        return cmdArchive({ ...args, command: "archive", positionals: [name] }, cwd);
+    // Gate: feature must be valid for its CURRENT stage before leaving it.
+    const force = Boolean(args.options.force);
+    const forcedCodes = [];
+    // Returning to planning is checked against the brainstorm gate: the requirement must still be
+    // confirmed. A cancelled item is exempt — pretending it sits in brainstorm walked straight past
+    // the `cancelled` shortcut inside validateFeature, so `kf validate` called the item valid while
+    // `kf stage` refused the very reopen `kf cancel` prints, and blamed a stage it was not in. The
+    // only way through was --force, which stamps a permanent bypass for a gate that should not hold.
+    const check = to === "planning" && f.stage !== "brainstorm" && f.stage !== "cancelled"
+        ? validateFeature({ ...f, stage: "brainstorm" }, false, false)
+        : validateFeature(f);
+    if (!check.valid) {
+        if (!force) {
+            return {
+                code: 1,
+                stdout: `Gate failed for '${name}' (${f.stage}). Fix validation before moving:\n\n${renderValidateText(check)}\n\nOr re-run with --force.`,
+                stderr: "gate failed",
+            };
+        }
+        forcedCodes.push(...check.issues.filter((i) => i.severity === "ERROR").map((i) => i.code));
+    }
+    // Directional gate: PASS/FAIL/REQUIREMENT_BUG semantics of the reports.
+    const direction = checkDirectionGate(f, to);
+    if (direction.length > 0) {
+        if (!force) {
+            const lines = direction.map((i) => `  [${i.severity}] ${i.file}: ${i.message} (${i.code})`).join("\n");
+            return {
+                code: 1,
+                stdout: `Cannot move '${name}' ${f.stage} → ${to} — report status blocks this direction:\n\n${lines}\n\nOr re-run with --force.`,
+                stderr: "direction gate failed",
+            };
+        }
+        forcedCodes.push(...direction.map((i) => i.code));
+    }
+    // Phase hook: run the hook of the stage we are entering (before the move).
+    // If it exits non-zero the transition is refused, unless --skip-hooks.
+    const skipHooks = Boolean(args.options["skip-hooks"]);
+    let hookResult = null;
+    const skippedHook = skipHooks ? resolveHook(root.root, to) : null;
+    if (!skipHooks) {
+        hookResult = runHook(root.root, {
+            feature: f.name,
+            context: f.context,
+            dir: f.dir,
+            root: root.root,
+            from: f.stage,
+            to,
+            approval: to === "planning" ? "pending" : f.meta?.approval?.status ?? "pending",
+        });
+        if (hookResult.ran && !hookResult.ok) {
+            return {
+                code: 1,
+                stdout: `Hook '${to}' failed (exit ${hookResult.code})${hookResult.hook ? ` [${hookResult.hook.path}]` : ""}.\nTransition refused.\n\n${hookResult.output}\n\nRe-run with --skip-hooks to bypass.`,
+                stderr: "hook failed",
+            };
+        }
+    }
+    const dest = stageDir(root.root, to);
+    const target = join(dest, f.folder);
+    if (existsSync(target)) {
+        return { code: 1, stdout: `Target already exists: ${target}`, stderr: "target exists" };
+    }
+    if (!f.meta)
+        return { code: 1, stdout: "Feature metadata is missing.", stderr: "metadata missing" };
+    const recorded = recordBypasses(f.stage, to, forcedCodes, skippedHook);
+    let metadataUpdated = false;
+    try {
+        let meta = recorded.length > 0 ? { ...f.meta, bypasses: [...(f.meta.bypasses ?? []), ...recorded] } : f.meta;
+        // Putting an item back in `dones` means putting back the state it had there. `status` does
+        // not depend on validation, so restore it here rather than leaving it to the doc re-sync,
+        // which can legitimately refuse on an item that was never fully valid.
+        if (f.stage === "cancelled")
+            meta = { ...meta, cancellation: undefined, status: isReopen && to === "dones" ? "archived" : undefined };
+        if (to === "planning") {
+            await writeFeatureMeta(f.dir, { ...meta, approval: { status: "pending" }, executionId: undefined });
+            metadataUpdated = true;
+        }
+        else if (to === "testing" || to === "implementation") {
+            await writeFeatureMeta(f.dir, { ...meta, executionId: to === "testing" ? randomUUID() : undefined });
+            metadataUpdated = true;
+        }
+        else if (recorded.length > 0 || f.stage === "cancelled") {
+            await writeFeatureMeta(f.dir, meta);
+            metadataUpdated = true;
+        }
+        await rename(f.dir, target);
+    }
+    catch (err) {
+        if (metadataUpdated) {
+            try {
+                await writeFeatureMeta(f.dir, f.meta);
+            }
+            catch (rollbackError) {
+                throw new AggregateError([err, rollbackError], `Transition failed and metadata rollback was incomplete for '${name}'.`);
+            }
+        }
+        throw err;
+    }
+    const hookNote = hookResult?.ran ? `\n  Hook '${to}' ran [${hookResult.hook?.source ?? ""}]` : "";
+    const moved = `✓ Moved '${name}' ${f.stage} → ${to}\n  ${target}${hookNote}${bypassNote(recorded)}`;
+    // An item reopened into `dones` must end up as archived as it was: `status: "archived"` back,
+    // and canonical docs re-synced, since `kf cancel --purge-docs` may have deleted them. Archive
+    // is idempotent once the item is in `dones`, so hand off rather than duplicate its logic.
+    if (isReopen && to === "dones") {
+        // The caller's flags are deliberately NOT forwarded. `--force` on `kf stage` means "skip a
+        // gate"; inside archive it also means "overwrite canonical docs that changed since the
+        // snapshot", which would destroy hand edits on a command that never offered to. A re-sync
+        // that refuses is the correct outcome here, and archive says why.
+        //
+        // Archive can throw as well as return non-zero — a missing source artifact, an unwritable
+        // docs tree. The move and the metadata write have already committed by now, so a throw must
+        // not turn a successful reopen into exit 1.
+        let resync;
+        try {
+            resync = await cmdArchive({ command: "archive", positionals: [name], options: {} }, cwd);
+        }
+        catch (err) {
+            const why = err instanceof Error ? err.message : String(err);
+            return { code: 0, stdout: `${moved}\n  Canonical docs were not re-synced: ${why}\n  Fix that, then run: kf archive ${name}` };
+        }
+        if (resync.code !== 0) {
+            return { code: 0, stdout: `${moved}\n  Canonical docs were not re-synced. Run: kf archive ${name}\n${resync.stdout}` };
+        }
+        return { code: 0, stdout: `${moved}\n${resync.stdout}` };
+    }
+    return { code: 0, stdout: moved };
+}

package/dist/cli/result.js

@@ -0,0 +1 @@
+export {};

package/dist/dashboard/dashboard-view.js

@@ -0,0 +1,238 @@
+export function renderDashboardHtml() {
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>kanban-flow dashboard</title>
+<style>
+  :root { color-scheme: dark; --bg: #0b1120; --panel: #111c30; --border: #2b3a52;
+    --text: #e8eef8; --muted: #a9b8ce; --feature: #22d3ee; --bug: #fbbf24; }
+  * { box-sizing: border-box; }
+  body { margin: 0; background: var(--bg); color: var(--text);
+    font: 14px/1.5 ui-sans-serif, system-ui, -apple-system, sans-serif; }
+  main { max-width: 1280px; margin: auto; padding: 32px 24px; }
+  header { display: flex; align-items: flex-start; justify-content: space-between; gap: 20px; }
+  h1 { font-size: 26px; letter-spacing: -.04em; margin: 4px 0 6px; }
+  h2 { font-size: 16px; margin: 0; }
+  p { margin: 0; }
+  .eyebrow { font-size: 11px; letter-spacing: .14em; text-transform: uppercase; color: var(--feature); }
+  .muted, .caption { color: var(--muted); }
+  .caption { font-size: 12px; margin-top: 6px; }
+  .toolbar { display: flex; flex-wrap: wrap; align-items: end; gap: 12px; margin: 24px 0; }
+  label { display: grid; gap: 6px; font-size: 12px; color: var(--muted); }
+  select, button { font: inherit; min-height: 44px; border: 1px solid var(--border); border-radius: 8px;
+    background: var(--panel); color: var(--text); padding: 8px 12px; }
+  select { min-width: 180px; max-width: 100%; cursor: pointer; }
+  button { cursor: pointer; }
+  button:hover { border-color: var(--feature); }
+  button:disabled { cursor: wait; opacity: .65; }
+  select:focus-visible, button:focus-visible { outline: 2px solid var(--feature); outline-offset: 3px; }
+  .updated { margin-left: auto; color: var(--muted); font-size: 12px; align-self: center; }
+  #root { font-size: 12px; overflow-wrap: anywhere; margin-top: 12px; }
+  #error { background: #452028; color: #fecdd3; border: 1px solid #a94a5a; border-radius: 8px; padding: 12px; margin-bottom: 20px; }
+  [hidden] { display: none !important; }
+  .kpis { display: grid; grid-template-columns: repeat(auto-fit, minmax(150px, 1fr)); gap: 12px; margin-bottom: 20px; }
+  .kpi, .panel { background: var(--panel); border: 1px solid var(--border); border-radius: 12px; }
+  .kpi { padding: 18px; }
+  .kpi-label { color: var(--muted); font-size: 12px; }
+  .kpi-value { font-size: 32px; font-weight: 650; letter-spacing: -.04em; margin: 6px 0; font-variant-numeric: tabular-nums; }
+  .kpi-note { font-size: 11px; color: var(--muted); }
+  .charts { display: grid; grid-template-columns: minmax(0, 1.5fr) minmax(0, 1fr); gap: 20px; }
+  .panel { padding: 22px; min-width: 0; }
+  .panel-heading { margin-bottom: 20px; }
+  .legend { display: flex; flex-wrap: wrap; gap: 16px; color: var(--muted); font-size: 12px; margin-bottom: 18px; }
+  .legend span { display: inline-flex; align-items: center; gap: 6px; }
+  .swatch { width: 9px; height: 9px; border-radius: 2px; display: inline-block; }
+  .feature { background: var(--feature); }
+  .bug { background: var(--bug); }
+  .bars { display: grid; gap: 15px; }
+  .chart-row { display: grid; grid-template-columns: minmax(90px, 120px) minmax(0, 1fr) 36px; align-items: center; gap: 12px; }
+  .chart-label { overflow-wrap: anywhere; font-size: 12px; }
+  .track { display: flex; height: 12px; background: #26354c; border-radius: 4px; overflow: hidden; }
+  .segment { display: block; height: 100%; }
+  .chart-value { font-size: 12px; text-align: right; font-variant-numeric: tabular-nums; }
+  .scroll-chart { max-height: 340px; overflow: auto; padding-right: 4px; }
+  .donut-layout { display: flex; align-items: center; gap: 24px; flex-wrap: wrap; }
+  .donut { width: 180px; height: 180px; flex-shrink: 0; }
+  .donut text { fill: var(--text); text-anchor: middle; }
+  .donut-total { font-size: 28px; font-weight: 650; }
+  .donut-label { font-size: 10px; fill: var(--muted) !important; }
+  .kind-legend { display: grid; gap: 12px; flex: 1; min-width: 120px; }
+  .kind-row { display: grid; grid-template-columns: 12px 1fr auto; align-items: center; gap: 8px; }
+  .kind-row small { color: var(--muted); }
+  .task-summary { margin-top: 28px; padding-top: 22px; border-top: 1px solid var(--border); }
+  .task-line { display: flex; justify-content: space-between; gap: 12px; margin-bottom: 10px; }
+  .empty { padding: 24px 0; color: var(--muted); text-align: center; }
+  footer { margin-top: 24px; font-size: 12px; color: var(--muted); }
+  @media (max-width: 1000px) { .kpis { grid-template-columns: repeat(3, minmax(0, 1fr)); } }
+  @media (max-width: 720px) {
+    main { padding: 24px 16px; }
+    header { display: block; }
+    .kpis { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+    .charts { grid-template-columns: minmax(0, 1fr); }
+    .toolbar label { flex: 1; min-width: 140px; }
+    select { min-width: 0; width: 100%; }
+    .updated { width: 100%; margin-left: 0; }
+    .panel { padding: 18px; }
+    .chart-row { grid-template-columns: 90px minmax(0, 1fr) 30px; gap: 8px; }
+  }
+</style>
+</head>
+<body>
+<main>
+  <header>
+    <div><div class="eyebrow">kanban-flow / Analytics</div><h1>Workflow overview</h1>
+      <p class="muted">Feature and bug counts, and how far execution has got.</p><p class="muted" id="root"></p></div>
+    <button id="refresh" type="button">Refresh</button>
+  </header>
+  <div class="toolbar">
+    <label>Context<select id="context"><option value="">All contexts</option></select></label>
+    <label>Work item kind<select id="kind"><option value="">Features and bugs</option><option value="feature">Feature</option><option value="bug">Bug</option></select></label>
+    <p class="updated">Updated <span id="ts">—</span> · refreshes every 5 seconds</p>
+  </div>
+  <div id="error" role="alert" hidden></div>
+  <section class="kpis" id="kpis" aria-label="Summary metrics"><p class="muted">Loading metrics…</p></section>
+  <div class="charts">
+    <section class="panel" aria-labelledby="stages-title">
+      <div class="panel-heading"><h2 id="stages-title">By stage</h2><p class="caption">How many work items sit in each stage right now.</p></div>
+      <div class="legend"><span><i class="swatch feature"></i>Feature</span><span><i class="swatch bug"></i>Bug</span></div>
+      <div class="bars" id="stage-chart"></div>
+    </section>
+    <section class="panel" aria-labelledby="kind-title">
+      <div class="panel-heading"><h2 id="kind-title">Features and bugs</h2><p class="caption">The split under the current filter.</p></div>
+      <div class="donut-layout" id="kind-chart"></div>
+      <div class="task-summary" id="task-chart"></div>
+    </section>
+    <section class="panel" aria-labelledby="context-title">
+      <div class="panel-heading"><h2 id="context-title">By context</h2><p class="caption">Feature and bug volume compared across contexts.</p></div>
+      <div class="bars scroll-chart" id="context-chart"></div>
+    </section>
+    <section class="panel" aria-labelledby="approval-title">
+      <div class="panel-heading"><h2 id="approval-title">Approval state</h2><p class="caption">Work items from planning through review, backlog included.</p></div>
+      <div class="bars" id="approval-chart"></div>
+    </section>
+  </div>
+  <footer>These numbers are a snapshot of .works/. Task progress counts only items in implementation, testing and review that have a tasks.md. It is not a test pass rate or coverage.</footer>
+</main>
+<script>
+const $ = (selector) => document.querySelector(selector);
+const escapeHtml = (value) => String(value ?? '').replace(/[&<>"']/g, (char) =>
+  ({'&':'&amp;', '<':'&lt;', '>':'&gt;', '"':'&quot;', "'":'&#39;'}[char]));
+const percent = (value) => value === null ? '—' : value + '%';
+const colors = { feature: '#22d3ee', bug: '#fbbf24', pending: '#a9b8ce', approved: '#4ade80', changed: '#fb7185' };
+function bars(rows, stacked) {
+  const maximum = Math.max(1, ...rows.map((row) => row.count));
+  return rows.map((row) => {
+    const label = stacked
+      ? row.label + ': ' + row.features + ' feature, ' + row.bugs + ' bug'
+      : row.label + ': ' + row.count;
+    const segments = stacked
+      ? '<i class="segment feature" style="width:' + (100 * row.features / maximum) + '%"></i>'
+        + '<i class="segment bug" style="width:' + (100 * row.bugs / maximum) + '%"></i>'
+      : '<i class="segment" style="background:' + colors[row.id] + ';width:' + (100 * row.count / maximum) + '%"></i>';
+    return '<div class="chart-row"><span class="chart-label">' + escapeHtml(row.label) + '</span>'
+      + '<div class="track" role="img" aria-label="' + escapeHtml(label) + '" title="' + escapeHtml(label) + '">' + segments + '</div>'
+      + '<span class="chart-value">' + row.count + '</span></div>';
+  }).join('');
+}
+function render(data) {
+  const m = data.metrics;
+  const kpis = [
+    ['Work items', m.total, m.features + ' feature · ' + m.bugs + ' bug'],
+    ['In execution', m.executing, 'Implementation · testing · review'],
+    ['Backlog', m.backlog, 'Awaiting a decision to start'],
+    ['Completed', m.completed, percent(m.completionRate) + ' of work items'],
+    ['Cancelled', m.cancelled, 'Left out of the completion rate'],
+    ['Gate bypasses', m.bypassed, 'Work items using --force / --skip-hooks'],
+    ['Task progress', percent(m.tasks.completionRate), m.tasks.done + '/' + m.tasks.total + ' tasks done'],
+  ];
+  $('#kpis').innerHTML = kpis.map(([label, value, note]) => '<div class="kpi"><p class="kpi-label">'
+    + escapeHtml(label) + '</p><p class="kpi-value">' + escapeHtml(value)
+    + '</p><p class="kpi-note">' + escapeHtml(note) + '</p></div>').join('');
+  $('#stage-chart').innerHTML = bars(data.charts.byStage, true);
+  $('#context-chart').innerHTML = data.charts.byContext.length
+    ? bars(data.charts.byContext, true) : '<p class="empty">No work item matches this filter.</p>';
+  $('#approval-chart').innerHTML = data.charts.approvals.some((row) => row.count)
+    ? bars(data.charts.approvals, false) : '<p class="empty">No work item needs approval yet.</p>';
+  const circumference = 2 * Math.PI * 62;
+  let offset = 0;
+  const arcs = data.charts.byKind.map((row) => {
+    const length = m.total ? circumference * row.count / m.total : 0;
+    const arc = '<circle cx="90" cy="90" r="62" fill="none" stroke="' + colors[row.id]
+      + '" stroke-width="18" stroke-dasharray="' + length + ' ' + (circumference - length)
+      + '" stroke-dashoffset="' + (-offset) + '" transform="rotate(-90 90 90)"></circle>';
+    offset += length;
+    return arc;
+  }).join('');
+  const legend = data.charts.byKind.map((row) => '<div class="kind-row"><i class="swatch ' + row.id
+    + '"></i><span>' + escapeHtml(row.label) + '</span><span>' + row.count + ' <small>('
+    + (m.total ? Math.round(100 * row.count / m.total) : 0) + '%)</small></span></div>').join('');
+  $('#kind-chart').innerHTML = '<svg class="donut" viewBox="0 0 180 180" role="img" aria-label="'
+    + m.features + ' feature, ' + m.bugs + ' bug"><circle cx="90" cy="90" r="62" fill="none" stroke="#26354c" stroke-width="18"></circle>'
+    + arcs + '<text x="90" y="91" class="donut-total">' + m.total
+    + '</text><text x="90" y="111" class="donut-label">WORK ITEMS</text></svg><div class="kind-legend">' + legend + '</div>';
+  $('#task-chart').innerHTML = '<div class="task-line"><span>Tasks in execution</span><strong>'
+    + m.tasks.done + '/' + m.tasks.total + '</strong></div><div class="track" role="img" aria-label="'
+    + m.tasks.done + ' of ' + m.tasks.total + ' tasks done"><i class="segment feature" style="width:'
+    + (m.tasks.completionRate ?? 0) + '%"></i></div><p class="caption">'
+    + m.tasks.itemsTracked + ' items with tasks · ' + m.tasks.itemsUntracked + ' items without</p>';
+  $('#root').textContent = data.root;
+  $('#ts').textContent = new Date(data.updatedAt).toLocaleTimeString();
+}
+function query() {
+  const params = new URLSearchParams();
+  if ($('#context').value) params.set('context', $('#context').value);
+  if ($('#kind').value) params.set('kind', $('#kind').value);
+  return params.toString();
+}
+let contextOptionsKey = '';
+function updateContexts(data) {
+  const selected = $('#context').value;
+  const options = data.availableContexts.map((context) => ({
+    value: context.id === null ? '__none__' : context.id, label: context.label
+  }));
+  if (selected && !options.some((option) => option.value === selected)) {
+    options.push({ value: selected, label: selected === '__none__' ? 'Unassigned' : selected });
+  }
+  const key = JSON.stringify(options);
+  if (key === contextOptionsKey) return;
+  contextOptionsKey = key;
+  $('#context').innerHTML = '<option value="">All contexts</option>' + options.map((option) =>
+    '<option value="' + escapeHtml(option.value) + '">' + escapeHtml(option.label) + '</option>').join('');
+  $('#context').value = selected;
+}
+let loading = false;
+let queued = false;
+async function refresh() {
+  if (loading) { queued = true; return; }
+  loading = true;
+  $('#refresh').disabled = true;
+  const requested = query();
+  try {
+    const response = await fetch('/api/data?' + requested, { cache: 'no-store' });
+    if (!response.ok) throw new Error('HTTP ' + response.status);
+    const data = await response.json();
+    if (requested !== query()) { queued = true; return; }
+    updateContexts(data);
+    render(data);
+    $('#error').hidden = true;
+  } catch (error) {
+    $('#error').textContent = 'Could not load the metrics (' + (error instanceof Error ? error.message : String(error))
+      + '). What is on screen may be stale. Check the server output, then refresh.';
+    $('#error').hidden = false;
+  } finally {
+    loading = false;
+    $('#refresh').disabled = false;
+    if (queued) { queued = false; refresh(); }
+  }
+}
+$('#refresh').addEventListener('click', refresh);
+$('#context').addEventListener('change', refresh);
+$('#kind').addEventListener('change', refresh);
+refresh();
+setInterval(refresh, 5000);
+</script>
+</body>
+</html>`;
+}