@luuthuong/devboard 0.0.0-stage → 1.0.1

package/server-dist/server/harness/intents.js

@@ -0,0 +1,268 @@
+// AI-DLC on the board. An Intent is one piece of work that goes through
+// Inception (requirements → units) and Construction (one card per unit:
+// design → code → review). Every stage ends at a human gate: the agent asks
+// for review (`devboard gate request`), the card waits in "requires
+// attention", and only a person's approve or reject moves it on.
+import fs from "node:fs";
+import path from "node:path";
+import { newLinkBase } from "../coordination.js";
+import { Mutex, devboardDataDir, ksuid, writeFileAtomic } from "../util.js";
+import { slugify } from "./config.js";
+const nowIso = () => new Date().toISOString();
+export class IntentStore {
+    filePath;
+    lock = new Mutex();
+    constructor(base) {
+        this.filePath = path.join(base ?? devboardDataDir(), "intents.json");
+    }
+    async list() {
+        try {
+            const parsed = JSON.parse(await fs.promises.readFile(this.filePath, "utf8"));
+            return Array.isArray(parsed?.intents) ? parsed.intents : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    async get(id) {
+        return (await this.list()).find((i) => i.id === id);
+    }
+    upsert(intent) {
+        return this.lock.run(async () => {
+            const all = await this.list();
+            const idx = all.findIndex((i) => i.id === intent.id);
+            intent.updatedAt = nowIso();
+            if (idx >= 0)
+                all[idx] = intent;
+            else
+                all.push(intent);
+            await writeFileAtomic(this.filePath, JSON.stringify({ intents: all }, null, 2));
+            return intent;
+        });
+    }
+}
+// ── Prompts ──────────────────────────────────────────────────────────────────
+const GATE_HINT = 'When this stage is done, run `devboard gate request --note "<one line>"` and stop: a person reviews before the next stage.';
+export function inceptionPrompt(intent) {
+    return [
+        `AI-DLC Inception for: ${intent.title}`,
+        "",
+        intent.body,
+        "",
+        `Use the aidlc-requirements skill. Write ${intent.artifactsDir}/requirements.md (user stories, acceptance criteria, open questions).`,
+        "Commit it on this card's branch. Do not write code yet.",
+        GATE_HINT,
+    ].join("\n");
+}
+export function unitsPrompt(intent) {
+    return [
+        "Requirements approved.",
+        `Use the aidlc-units skill. Write ${intent.artifactsDir}/units.md: one "## <unit title>" section per unit of work, each with its scope (files or folders), dependencies and acceptance criteria.`,
+        "Units must be small enough for one pull request each.",
+        GATE_HINT,
+    ].join("\n");
+}
+export function unitPrompt(intent, unit) {
+    return [
+        `AI-DLC unit of "${intent.title}": ${unit.title}`,
+        "",
+        unit.body,
+        "",
+        `Context: ${intent.artifactsDir}/requirements.md and ${intent.artifactsDir}/units.md.`,
+        `Use the aidlc-design skill. Write ${intent.artifactsDir}/${unit.slug}/design.md. Do not write code yet.`,
+        GATE_HINT,
+    ].join("\n");
+}
+export const codePrompt = (intent) => [
+    "Design approved.",
+    `Use the aidlc-implement skill to implement the design, with tests, then the aidlc-pr skill to open a pull request that links ${intent.artifactsDir}.`,
+    "The pull request is the next gate: a person merges it.",
+].join("\n");
+export const rejectPrompt = (stage, note) => `The ${stage} stage was sent back by the reviewer:\n\n${note}\n\nRevise it, then run \`devboard gate request\` again.`;
+/** Each `## heading` in units.md is one unit; text up to the next `##` is its body. */
+export function parseUnits(markdown) {
+    const units = [];
+    let cur = null;
+    const flush = () => {
+        if (!cur)
+            return;
+        const slug = slugify(cur.title);
+        units.push({ title: cur.title, slug: uniqueSlug(slug, units), body: cur.lines.join("\n").trim() });
+    };
+    for (const line of markdown.split(/\r?\n/)) {
+        const m = /^##\s+(.+?)\s*#*\s*$/.exec(line);
+        if (m) {
+            flush();
+            cur = { title: m[1], lines: [] };
+        }
+        else if (cur) {
+            cur.lines.push(line);
+        }
+    }
+    flush();
+    return units;
+}
+function uniqueSlug(slug, taken) {
+    let s = slug;
+    for (let n = 2; taken.some((u) => u.slug === s); n++)
+        s = `${slug}-${n}`;
+    return s;
+}
+/** The checkout the card works in: its worktree, else the project. */
+export function cardCheckout(link) {
+    return link.worktreeLink?.path ?? link.projectPath;
+}
+export async function createIntent(deps, args) {
+    const id = ksuid("intent");
+    const slug = `${new Date().toISOString().slice(0, 10)}-${slugify(args.title).slice(0, 40)}`;
+    const intent = {
+        id,
+        projectPath: args.projectPath,
+        title: args.title.trim(),
+        body: args.body.trim(),
+        phase: "inception",
+        artifactsDir: `docs/aidlc/${slug}`,
+        unitCardIds: [],
+        issueUrl: args.issueUrl,
+        createdAt: nowIso(),
+        updatedAt: nowIso(),
+    };
+    const card = newLinkBase();
+    card.name = `Inception: ${intent.title}`;
+    card.projectPath = intent.projectPath;
+    card.promptBody = inceptionPrompt(intent);
+    card.intentId = id;
+    card.stage = "requirements";
+    await deps.store.upsertLink(card);
+    intent.inceptionCardId = card.id;
+    await deps.intents.upsert(intent);
+    return { intent, card };
+}
+/** The agent finished a stage: park the card until a person decides. */
+export async function requestGate(deps, cardId, note) {
+    let out;
+    await deps.store.update((links) => {
+        const link = links.find((l) => l.id === cardId);
+        if (!link)
+            throw new Error(`card ${cardId} not found`);
+        if (!link.stage)
+            throw new Error("this card is not part of an AI-DLC intent");
+        link.gate = { stage: link.stage, status: "pending", note: note?.trim() || undefined, at: nowIso() };
+        link.column = "in_progress";
+        link.manualOverrides.column = true;
+        link.updatedAt = nowIso();
+        out = link;
+        return links;
+    });
+    return out;
+}
+function queuePrompt(link, body) {
+    (link.queuedPrompts ??= []).push({ id: ksuid("qp"), body, sendAutomatically: true });
+}
+export async function approveGate(deps, cardId) {
+    const links = await deps.store.readLinks();
+    const link = links.find((l) => l.id === cardId);
+    if (!link?.intentId || !link.stage)
+        throw new Error("this card has no AI-DLC stage to approve");
+    if (link.gate?.status !== "pending")
+        throw new Error("no review was requested for this stage");
+    const intent = await deps.intents.get(link.intentId);
+    if (!intent)
+        throw new Error(`intent ${link.intentId} not found`);
+    const created = [];
+    let units = [];
+    if (link.stage === "units") {
+        const checkout = cardCheckout(link);
+        const file = checkout ? path.join(checkout, intent.artifactsDir, "units.md") : "";
+        let text = "";
+        try {
+            text = await fs.promises.readFile(file, "utf8");
+        }
+        catch {
+            throw new Error(`${intent.artifactsDir}/units.md was not found in the card's checkout`);
+        }
+        units = parseUnits(text);
+        if (units.length === 0)
+            throw new Error("units.md has no '## <unit>' sections");
+    }
+    await deps.store.update((all) => {
+        const l = all.find((x) => x.id === cardId);
+        l.gate = { ...l.gate, status: "approved", at: nowIso() };
+        l.manualOverrides.column = true;
+        l.updatedAt = nowIso();
+        switch (l.stage) {
+            case "requirements":
+                l.stage = "units";
+                l.column = "in_progress";
+                queuePrompt(l, unitsPrompt(intent));
+                break;
+            case "units":
+                // Inception is finished; each unit becomes its own card.
+                l.column = "done";
+                for (const u of units) {
+                    const card = newLinkBase();
+                    card.name = u.title;
+                    card.projectPath = intent.projectPath;
+                    card.promptBody = unitPrompt(intent, u);
+                    card.intentId = intent.id;
+                    card.stage = "design";
+                    all.push(card);
+                    created.push(card);
+                }
+                break;
+            case "design":
+                l.stage = "code";
+                l.column = "in_progress";
+                queuePrompt(l, codePrompt(intent));
+                break;
+            default:
+                // code / review end at the pull request merge, not at a gate.
+                l.column = "in_progress";
+        }
+        return all;
+    });
+    if (created.length) {
+        intent.unitCardIds.push(...created.map((c) => c.id));
+        intent.phase = "construction";
+        await deps.intents.upsert(intent);
+    }
+    const card = (await deps.store.readLinks()).find((l) => l.id === cardId);
+    return { card, created, intent };
+}
+export async function rejectGate(deps, cardId, note) {
+    const reason = note.trim();
+    if (!reason)
+        throw new Error("say why the stage is sent back");
+    let out;
+    await deps.store.update((links) => {
+        const l = links.find((x) => x.id === cardId);
+        if (!l?.stage || l.gate?.status !== "pending")
+            throw new Error("no review is pending on this card");
+        l.gate = { stage: l.stage, status: "rejected", note: reason, at: nowIso() };
+        l.column = "in_progress";
+        l.manualOverrides.column = true;
+        queuePrompt(l, rejectPrompt(l.stage, reason));
+        l.updatedAt = nowIso();
+        out = l;
+        return links;
+    });
+    return out;
+}
+/** Mark intents done once every unit card is done. Returns the intents that changed. */
+export async function settleIntents(deps) {
+    const links = new Map((await deps.store.readLinks()).map((l) => [l.id, l]));
+    const changed = [];
+    for (const intent of await deps.intents.list()) {
+        if (intent.phase !== "construction" || intent.unitCardIds.length === 0)
+            continue;
+        const allDone = intent.unitCardIds.every((id) => {
+            const l = links.get(id);
+            return !l || l.column === "done";
+        });
+        if (allDone) {
+            intent.phase = "done";
+            changed.push(await deps.intents.upsert(intent));
+        }
+    }
+    return changed;
+}

package/server-dist/server/harness/kbIndex.js

@@ -0,0 +1,291 @@
+// Index over every knowledge base: an in-memory scope index (path → entries)
+// and text search in each KB's store (SQLite FTS5, or memory on old Node),
+// fused with reciprocal rank fusion. Files are re-read only when their mtime
+// or size changes, and with SQLite that holds across restarts too. The
+// markdown files stay the source of truth; the index can be thrown away.
+import fs from "node:fs";
+import path from "node:path";
+import { tokenize } from "../transcripts.js";
+import { normalizeScope, parseEntry } from "./entry.js";
+import { openStore } from "./kbStore.js";
+/** Bigger = more useful when injected. Kept close to 1 so they break ties, not rankings. */
+const TYPE_WEIGHT = {
+    gotcha: 1.1,
+    convention: 1.08,
+    decision: 1.05,
+    runbook: 1.0,
+    component: 1.0,
+    glossary: 0.9,
+};
+/** Small k: candidate lists are short, so rank 1 vs 2 should matter. */
+const RRF_K = 10;
+/** Text candidates fetched per KB before routing and supersede filters. */
+const TEXT_CANDIDATES = 200;
+export class KbIndex {
+    storeDir;
+    sources = new Map();
+    stores = new Map();
+    docs = new Map(); // kbId → file → doc
+    byId = new Map();
+    superseded = new Set();
+    stale = new Set();
+    usefulness = new Map();
+    /** `storeDir`: where per-KB SQLite files live; omit for a memory-only index. */
+    constructor(storeDir) {
+        this.storeDir = storeDir;
+    }
+    setSources(sources) {
+        this.sources = new Map(sources.map((s) => [s.id, s]));
+        for (const id of [...this.docs.keys()]) {
+            if (this.sources.has(id))
+                continue;
+            this.docs.delete(id);
+            this.stores.get(id)?.close();
+            this.stores.delete(id);
+        }
+        this.rebuildMaps();
+    }
+    listSources() {
+        return [...this.sources.values()];
+    }
+    /** "sqlite" when every store is on disk, else "memory". */
+    storeKind() {
+        return [...this.stores.values()].every((s) => s.kind === "sqlite") && this.stores.size ? "sqlite" : "memory";
+    }
+    /** Re-read changed files in every source. Returns how many entries changed. */
+    async reindex() {
+        let changed = 0;
+        for (const src of this.sources.values())
+            changed += await this.reindexSource(src);
+        if (changed)
+            this.rebuildMaps();
+        return changed;
+    }
+    store(kbId) {
+        let s = this.stores.get(kbId);
+        if (!s)
+            this.stores.set(kbId, (s = openStore(this.storeDir, kbId)));
+        return s;
+    }
+    async reindexSource(src) {
+        const store = this.store(src.id);
+        // First pass after start: what the store already holds (nothing for memory).
+        const prev = this.docs.get(src.id) ?? new Map(store.load().map((f) => [f.rel, f]));
+        const next = new Map();
+        const upserts = [];
+        for (const rel of await listMarkdown(src.root)) {
+            const abs = path.join(src.root, rel);
+            let st;
+            try {
+                st = await fs.promises.stat(abs);
+            }
+            catch {
+                continue;
+            }
+            const old = prev.get(rel);
+            if (old && old.mtimeMs === st.mtimeMs && old.size === st.size) {
+                next.set(rel, old);
+                continue;
+            }
+            const entry = parseEntry(await fs.promises.readFile(abs, "utf8"), src.id, rel);
+            if (!entry)
+                continue;
+            const file = { rel, mtimeMs: st.mtimeMs, size: st.size, entry };
+            next.set(rel, file);
+            upserts.push(file);
+        }
+        const removed = [...prev.keys()].filter((k) => !next.has(k));
+        store.apply(upserts, removed);
+        const firstLoad = !this.docs.has(src.id);
+        this.docs.set(src.id, next);
+        // Loading from the store is a change for this process even when the files are not.
+        return upserts.length + removed.length + (firstLoad ? next.size - upserts.length : 0);
+    }
+    rebuildMaps() {
+        this.byId = new Map();
+        this.superseded = new Set();
+        for (const m of this.docs.values()) {
+            for (const f of m.values()) {
+                this.byId.set(f.entry.id, f.entry);
+                for (const id of f.entry.supersedes)
+                    this.superseded.add(id);
+            }
+        }
+    }
+    /** Close every store (tests, shutdown). */
+    close() {
+        for (const s of this.stores.values())
+            s.close();
+        this.stores.clear();
+        this.docs.clear();
+        this.rebuildMaps();
+    }
+    all(kbId) {
+        const kbs = kbId ? [this.docs.get(kbId)].filter(Boolean) : [...this.docs.values()];
+        return kbs.flatMap((m) => [...m.values()].map((d) => d.entry));
+    }
+    get(id) {
+        return this.byId.get(id);
+    }
+    /** Superseded by another indexed entry: it never surfaces. */
+    isSuperseded(id) {
+        return this.superseded.has(id);
+    }
+    count(kbId) {
+        return this.docs.get(kbId)?.size ?? 0;
+    }
+    setStale(ids) {
+        this.stale = new Set(ids);
+    }
+    isStale(id) {
+        return this.stale.has(id);
+    }
+    /** Multipliers from usage stats (1 = neutral). */
+    setUsefulness(scores) {
+        this.usefulness = scores;
+    }
+    search(q) {
+        const limit = q.limit ?? 10;
+        const files = (q.files ?? []).map(normalizeScope).filter(Boolean);
+        const text = q.text?.trim() ?? "";
+        const kbIds = new Set(q.kbIds ?? []);
+        // Routing: a KB is searched when it is named, has no `covers`, or its covers match.
+        const only = q.onlyKbs?.length ? new Set(q.onlyKbs) : null;
+        const searched = [...this.sources.values()].filter((s) => only ? only.has(s.id) : kbIds.has(s.id) || s.covers.length === 0 || coversMatch(s.covers, files, text));
+        // Superseded entries never surface.
+        const live = searched.flatMap((s) => [...(this.docs.get(s.id)?.values() ?? [])].map((f) => f.entry).filter((e) => !this.superseded.has(e.id)));
+        if (live.length === 0)
+            return [];
+        const liveIds = new Set(live.map((e) => e.id));
+        const byScope = rankByScope(live, files);
+        // Each KB ranks its own text matches; the lists are interleaved by rank.
+        const byText = text
+            ? interleave(searched.map((s) => this.store(s.id)
+                .searchText(text, TEXT_CANDIDATES)
+                .filter((id) => liveIds.has(id))
+                .map((id) => this.byId.get(id))))
+            : [];
+        // No signal at all (a fresh session): fall back to the named KBs' project-wide primer.
+        const byPrior = byScope.length || byText.length ? [] : rankByPrior(live.filter((e) => kbIds.has(e.kbId)));
+        const fused = new Map();
+        const add = (ranked, via) => ranked.forEach((entry, rank) => {
+            const cur = fused.get(entry.id) ?? { entry, score: 0, via: new Set() };
+            cur.score += 1 / (RRF_K + rank + 1);
+            cur.via.add(via);
+            fused.set(entry.id, cur);
+        });
+        add(byScope, "scope");
+        add(byText, "text");
+        add(byPrior, "primer");
+        return [...fused.values()]
+            .map(({ entry: e, score, via }) => {
+            const weight = (this.sources.get(e.kbId)?.weight ?? 1) *
+                TYPE_WEIGHT[e.type] *
+                (this.usefulness.get(e.id) ?? 1) *
+                (this.stale.has(e.id) ? 0.6 : 1) *
+                (e.confidence === "proposed" ? 0.8 : 1);
+            return { entry: e, score: score * weight, via: [...via], stale: this.stale.has(e.id) };
+        })
+            .sort((a, b) => b.score - a.score)
+            .slice(0, limit);
+    }
+}
+/** Round-robin by rank: every KB's best match before any KB's second. */
+function interleave(lists) {
+    const out = [];
+    const longest = Math.max(0, ...lists.map((l) => l.length));
+    for (let i = 0; i < longest; i++)
+        for (const l of lists)
+            if (i < l.length)
+                out.push(l[i]);
+    return out;
+}
+/** How specifically an entry's scope covers a file: exact file > nearest folder. */
+export function scopeSpecificity(scope, file) {
+    if (!scope || !file)
+        return 0;
+    if (scope === file)
+        return 3;
+    const dir = scope.endsWith("/") ? scope : `${scope}/`;
+    if (file.startsWith(dir)) {
+        const depth = file.slice(dir.length).split("/").length; // 1 = file directly inside
+        return 2 / depth;
+    }
+    return 0;
+}
+function rankByScope(entries, files) {
+    if (files.length === 0)
+        return [];
+    return entries
+        .map((d) => ({
+        d,
+        s: Math.max(0, ...d.scope.flatMap((sc) => files.map((f) => scopeSpecificity(sc, f)))),
+    }))
+        .filter((x) => x.s > 0)
+        .sort((a, b) => b.s - a.s)
+        .map((x) => x.d);
+}
+/** Project-wide entries first, then by type; used when the query says nothing. */
+function rankByPrior(entries) {
+    return [...entries].sort((a, b) => Number(a.scope.length > 0) - Number(b.scope.length > 0) ||
+        TYPE_WEIGHT[b.type] - TYPE_WEIGHT[a.type] ||
+        a.title.localeCompare(b.title));
+}
+export function coversMatch(covers, files, text) {
+    const lower = text.toLowerCase();
+    return covers.some((c) => {
+        const cov = c.trim().toLowerCase();
+        if (!cov)
+            return false;
+        if (cov.includes("/") || cov.includes("*")) {
+            const prefix = cov.replace(/\*\*?.*$/, "");
+            return files.some((f) => f.toLowerCase().startsWith(prefix));
+        }
+        return tokenize(lower).includes(cov) || files.some((f) => f.toLowerCase().includes(cov));
+    });
+}
+async function listMarkdown(root) {
+    const out = [];
+    const walk = async (dir) => {
+        let items;
+        try {
+            items = await fs.promises.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const it of items) {
+            if (it.name.startsWith("."))
+                continue;
+            const abs = path.join(dir, it.name);
+            if (it.isDirectory())
+                await walk(abs);
+            else if (it.name.endsWith(".md") && it.name.toLowerCase() !== "readme.md") {
+                out.push(path.relative(root, abs).replaceAll("\\", "/"));
+            }
+        }
+    };
+    await walk(root);
+    return out.sort();
+}
+/** Compact lines for SessionStart: type, title, summary and how to read more. */
+export function formatContext(hits, tokenBudget) {
+    if (hits.length === 0)
+        return "";
+    const header = "Project knowledge (from the team knowledge base). Read an entry with `devboard kb show <id>`; " +
+        "search with `devboard kb search <words>`. Do not copy these notes into the repository.";
+    const lines = [];
+    let used = approxTokens(header);
+    for (const h of hits) {
+        const e = h.entry;
+        const line = `- [${e.type}] ${e.title} — ${e.summary} (${e.id}${h.stale ? ", may be outdated" : ""})`;
+        const cost = approxTokens(line);
+        if (used + cost > tokenBudget)
+            break;
+        lines.push(line);
+        used += cost;
+    }
+    return lines.length ? `${header}\n${lines.join("\n")}` : "";
+}
+/** ~4 characters per token is close enough for a budget. */
+export const approxTokens = (s) => Math.ceil(s.length / 4);