homeostat 0.1.0 → 0.1.2

package/README.md

@@ -6,7 +6,7 @@ Homeostat turns review feedback that led to a code change into short, scored rul
 
 ```sh
 # In a repo for your team's knowledge base:
-npx --yes homeostat@0.1.0 init
+npx --yes homeostat@0.1.2 init
 
 # In Claude Code:
 claude plugin marketplace add ysugarmen/homeostat

package/dist/src/cli.d.ts

@@ -12,6 +12,11 @@ export interface Io {
     now?: () => Date;
     /** Reads all of stdin; hooks receive their event JSON this way. */
     stdin?: () => Promise<string>;
+    /**
+     * Runs `homeostat <args>` detached, so a hook returns at once while a sync runs. Only the real
+     * process has one; tests and embedded callers leave it out, so nothing runs behind them.
+     */
+    background?: (args: string[]) => void;
     /** Test seams for the agents: a git-host provider and a drafter instead of the real ones. */
     provider?: Provider;
     drafter?: Drafter;
@@ -22,4 +27,4 @@ export interface Io {
 }
 export declare const processIo: Io;
 /** Runs the CLI with `argv` (as in `process.argv`) and returns the exit code. */
-export declare function runCli(argv: readonly string[], io?: Io): Promise<number>;
+export declare function runCli(argv: readonly string[], given?: Io): Promise<number>;

package/dist/src/cli.js

@@ -1,8 +1,10 @@
+import { spawn } from "node:child_process";
 import { createInterface } from "node:readline/promises";
 import { VERSION } from "@homeostat/core";
 import { Command, CommanderError } from "commander";
 import { runCodeowners } from "./codeowners.js";
 import { runCurate } from "./curate.js";
+import { runDaily } from "./daily.js";
 import { runDeepDive } from "./deep-dive.js";
 import { runDigest } from "./digest.js";
 import { runConvertDocs } from "./docs.js";
@@ -16,6 +18,7 @@ import { runLearn } from "./learn.js";
 import { runMcp } from "./mcp.js";
 import { runExplain, runList, runSearch, runStatus } from "./query.js";
 import { runSeed } from "./seed.js";
+import { runSync } from "./sync.js";
 import { runDashboard, runUp } from "./up.js";
 import { runValidate } from "./validate.js";
 async function readStdin() {
@@ -40,9 +43,24 @@ export const processIo = {
     ...(process.stdin.isTTY ? { ask: askTerminal } : {}),
     env: process.env,
     stdin: readStdin,
+    background: (args) => {
+        const bin = process.argv[1];
+        if (!bin)
+            return;
+        try {
+            spawn(process.execPath, [bin, ...args], { detached: true, stdio: "ignore" }).unref();
+        }
+        catch {
+            // Best effort: the next hook tries again.
+        }
+    },
 };
 /** Runs the CLI with `argv` (as in `process.argv`) and returns the exit code. */
-export async function runCli(argv, io = processIo) {
+export async function runCli(argv, given = processIo) {
+    // HOMEOSTAT_NO_SYNC=1 keeps hooks and learn from syncing in the background (`homeostat sync` by hand still works).
+    const io = { ...given };
+    if (given.env?.HOMEOSTAT_NO_SYNC)
+        delete io.background;
     let exitCode = 0;
     const program = new Command("homeostat")
         .description("Team knowledge base for coding agents.")
@@ -180,6 +198,25 @@ export async function runCli(argv, io = processIo) {
         .action(async (opts) => {
         exitCode = await runDigest(opts, io);
     });
+    program
+        .command("daily")
+        .description("The daily run (CI): one PR per developer from their pending lessons and the reviews on their PRs; merges, declines or asks a reviewer by confidence.")
+        .option("--dir <dir>", "knowledge base checkout", ".")
+        .option("--since <date>", "read reviews on PRs merged since this date (default: agents.curator.lookbackHours ago)")
+        .option("--dry-run", "decide and report, but commit, open and merge nothing")
+        .option("--no-reviews", "skip drafting from review comments (no model calls): pending lessons only")
+        .action(async (opts) => {
+        exitCode = await runDaily({ ...opts, ...(opts.reviews === false ? { noReviews: true } : {}) }, io);
+    });
+    program
+        .command("sync")
+        .description("Send your pending lessons to the daily run, pull the KB and clear decided lessons. The plugin runs it for you.")
+        .option("--dir <dir>", "knowledge base root (default: $HOMEOSTAT_DIR or the current dir)")
+        .option("--quiet", "print nothing")
+        .option("--push-only", "send pending lessons, skip the pull")
+        .action(async (opts) => {
+        exitCode = await runSync(opts, io);
+    });
     program
         .command("doctor")
         .description("Security review: what is read, what leaves, who can change the rules, and the blast radius.")

package/dist/src/daily.d.ts

@@ -0,0 +1,23 @@
+import type { Io } from "./cli.ts";
+/**
+ * `homeostat daily`: the one scheduled job (the KB repo's CI, or `homeostat up`). Laptops need not
+ * be on: it reads only what is already on the server. For each developer it:
+ *
+ * 1. takes their pending lessons (pushed to `candidates/<member>` by their sync) and the lessons
+ *    drafted from review comments on their own merged PRs
+ * 2. scores each lesson (confidence, step 3): merge, decline, or a reviewer
+ * 3. opens ONE daily PR with the confident lessons and merges it, every decision explained
+ * 4. opens a review PR for the uncertain ones, asking the area's owners to review
+ * 5. records decisions, heartbeats and a run report on `homeostat/state`, which the developers'
+ *    sync reads to clear decided lessons, and the dashboard reads to show it all
+ *
+ * It also settles earlier review PRs: merged by a reviewer means merged, closed means declined.
+ */
+export interface DailyOptions {
+    dir?: string;
+    since?: string;
+    dryRun?: boolean;
+    /** Skip drafting from review comments (no model calls): pending lessons only. */
+    noReviews?: boolean;
+}
+export declare function runDaily(opts: DailyOptions, io: Io): Promise<number>;

package/dist/src/daily.js

@@ -0,0 +1,442 @@
+import { resolve } from "node:path";
+import { ClaudeDocPatcher, ClaudeDrafter, candidatesBranch, confidence, curate, decisionsPath, detectConflicts, explainConfidence, HEARTBEAT_PATH, isDocPath, lessonHash, logEvent, parseEntry, REVIEW_REMINDER_DAYS, readKbFiles, STATE_BRANCH, validate, } from "@homeostat/core";
+import { askerFor } from "./agents.js";
+import { plural } from "./format.js";
+import { commitTree, forcePush, git, showFile } from "./git.js";
+import { CliError, providerFor } from "./provider.js";
+import { publish } from "./publish.js";
+const repoRef = (ref) => {
+    const [owner = "", name = ""] = ref.split("/");
+    return { owner, name };
+};
+const accepted = (text) => text.replace(/^status: candidate$/m, "status: accepted");
+export async function runDaily(opts, io) {
+    try {
+        return await daily(opts, io);
+    }
+    catch (e) {
+        if (e instanceof CliError) {
+            io.stderr(`${e.message}\n`);
+            return 1;
+        }
+        throw e;
+    }
+}
+async function daily(opts, io) {
+    const root = resolve(opts.dir ?? ".");
+    const files = readKbFiles(root);
+    const kb = validate(files);
+    const config = kb.config;
+    if (!config)
+        throw new CliError("homeostat.yaml is missing or invalid; run homeostat validate");
+    const sources = config.sources;
+    if (!sources)
+        throw new CliError("homeostat.yaml has no sources section; the daily run needs one");
+    const base = sources.baseBranch;
+    const kbRepo = repoRef(sources.kbRepo);
+    const now = io.now?.() ?? new Date();
+    const today = now.toISOString().slice(0, 10);
+    const provider = providerFor(sources.host, io, "read pull requests and open the daily PRs");
+    const remote = (ref) => `refs/remotes/origin/${ref}`;
+    git(root, "fetch", "--quiet", "origin", `+refs/heads/${base}:${remote(base)}`);
+    git(root, "fetch", "--quiet", "origin", "+refs/heads/candidates/*:refs/remotes/origin/candidates/*");
+    git(root, "fetch", "--quiet", "origin", `+refs/heads/${STATE_BRANCH}:${remote(STATE_BRANCH)}`);
+    const onState = (path) => git(root, "show", `${remote(STATE_BRANCH)}:${path}`);
+    const onBase = (path) => showFile(root, remote(base), path);
+    const members = config.team.members.map((m) => m.id);
+    const decisions = new Map();
+    for (const m of members) {
+        try {
+            decisions.set(m, JSON.parse(onState(decisionsPath(m)) ?? ""));
+        }
+        catch {
+            decisions.set(m, { member: m, decided: [] });
+        }
+    }
+    // Settle review PRs from earlier runs that a reviewer has since merged or closed.
+    const open = new Set((await provider.listOpenPullRequests(kbRepo)).map((p) => p.sourceBranch));
+    let settled = 0;
+    for (const d of decisions.values()) {
+        for (const r of d.decided) {
+            if (r.decision !== "review" || !r.pr || open.has(r.pr))
+                continue;
+            const onMain = onBase(r.path);
+            r.decision = onMain !== undefined && onMain.includes(`id: ${r.id}`) ? "merged" : "declined";
+            r.reason = r.decision === "merged" ? "merged by a reviewer" : "closed by a reviewer";
+            r.at = now.toISOString();
+            settled++;
+        }
+    }
+    const lessons = [];
+    const decidedHashes = (m) => new Set(decisions.get(m)?.decided.map((r) => r.hash));
+    const heartbeats = {};
+    // 1a. Pending lessons, from each developer's candidates branch.
+    for (const m of members) {
+        const branch = candidatesBranch(m);
+        const ref = remote(branch);
+        if (git(root, "rev-parse", "--verify", "--quiet", ref) === undefined)
+            continue;
+        const hb = git(root, "show", `${ref}:${HEARTBEAT_PATH}`);
+        if (hb)
+            heartbeats[m] = hb;
+        const changed = (git(root, "diff", "--name-status", "--no-renames", `${remote(base)}...${ref}`, "--", "knowledge") ?? "")
+            .split("\n")
+            .filter(Boolean);
+        const seen = decidedHashes(m);
+        for (const line of changed) {
+            const [status, path = ""] = line.split("\t");
+            if (status !== "A" && status !== "M")
+                continue;
+            const text = showFile(root, ref, path) ?? "";
+            const hash = lessonHash(text);
+            if (seen.has(hash))
+                continue;
+            lessons.push(pendingLesson(m, path, text, hash, status === "A" ? undefined : onBase(path)));
+        }
+    }
+    // 1b. Lessons from review comments, filed under the developer whose PR it was.
+    let drafted = [];
+    if (!opts.noReviews) {
+        const since = opts.since
+            ? new Date(opts.since)
+            : new Date(now.getTime() - config.agents.curator.lookbackHours * 3_600_000);
+        const asker = askerFor(config, "curator", io, root);
+        const result = await curate({
+            files,
+            provider,
+            drafter: io.drafter ?? new ClaudeDrafter(asker),
+            patcher: io.patcher ?? new ClaudeDocPatcher(asker),
+            since,
+            today,
+        });
+        drafted = result.entries;
+        for (const e of drafted) {
+            const member = e.prAuthor ?? e.frontmatter.source.author;
+            if (decidedHashes(member).has(lessonHash(e.text)))
+                continue;
+            lessons.push({
+                member,
+                path: e.path,
+                text: accepted(e.text),
+                hash: lessonHash(e.text),
+                id: e.frontmatter.id,
+                title: e.frontmatter.title,
+                kind: "new",
+                origin: "review",
+                originator: e.frontmatter.source.author,
+                ...(e.frontmatter.source.url ? { url: e.frontmatter.source.url } : {}),
+                decision: "review",
+                reason: "",
+            });
+        }
+        for (const d of result.docs) {
+            lessons.push({
+                member: d.sections[0]?.prAuthor ?? members[0] ?? "",
+                path: d.path,
+                text: d.text,
+                hash: lessonHash(d.text),
+                id: d.path,
+                title: `Update ${d.sections.map((s) => `#${s.id}`).join(", ")} in ${d.path}`,
+                kind: "doc",
+                origin: "review",
+                originator: d.sections[0]?.prAuthor ?? "",
+                decision: "review",
+                reason: "document edits go to the owning team",
+            });
+        }
+    }
+    // 2. Decide each lesson.
+    const acceptedFms = kb.entries
+        .filter((e) => e.entry.frontmatter.status === "accepted")
+        .map((e) => e.entry.frontmatter);
+    const newFms = lessons.flatMap((l) => l.kind === "new" ? [parseEntry(l.text).entry?.frontmatter ?? []].flat() : []);
+    for (const l of lessons)
+        decide(l, files, config, acceptedFms, newFms);
+    // 3–4. Per developer: one daily PR (merged), one review PR (assigned).
+    const report = { at: now.toISOString(), members: [], settled, lessons: [] };
+    const byMember = new Map();
+    for (const l of lessons)
+        byMember.set(l.member, [...(byMember.get(l.member) ?? []), l]);
+    for (const [member, list] of byMember) {
+        const merged = list.filter((l) => l.decision === "merged");
+        const review = list.filter((l) => l.decision === "review");
+        const declined = list.filter((l) => l.decision === "declined");
+        const row = {
+            member,
+            merged: merged.length,
+            declined: declined.length,
+            review: review.length,
+        };
+        report.members.push(row);
+        io.stdout(`${member}: ${merged.length} merged, ${review.length} to review, ${declined.length} declined\n`);
+        for (const l of list)
+            io.stdout(`  ${l.decision.padEnd(8)} ${l.id}: ${l.reason}\n`);
+        if (opts.dryRun)
+            continue;
+        const reconfirm = declined
+            .flatMap((l) => l.duplicateOf ? [reconfirmChange(files, kb.entries, l.duplicateOf, today)] : [])
+            .filter((c) => c !== undefined);
+        const changes = [...merged.map((l) => change(l, "merge")), ...reconfirm];
+        if (changes.length) {
+            const pr = await publish({
+                root,
+                branch: `homeostat/daily-${member}-${today}`,
+                changes,
+                provider,
+                kbRepo,
+                base,
+                title: `homeostat: daily lessons · ${member} · ${today}`,
+                body: prBody(member, today, list, "daily"),
+                io,
+            });
+            if (pr.pr) {
+                row.dailyPr = pr.pr.url;
+                try {
+                    await provider.mergePullRequest(kbRepo, pr.pr.id);
+                    io.stdout(`  merged ${pr.pr.url}\n`);
+                }
+                catch (e) {
+                    // Branch protection or a failing check: the confident lessons wait for a person instead.
+                    row.mergeError = e.message;
+                    for (const l of merged) {
+                        l.decision = "review";
+                        l.reason = `${l.reason}; the host refused the merge`;
+                    }
+                    io.stdout(`  could not merge ${pr.pr.url}: ${row.mergeError}; it stays open for a reviewer\n`);
+                }
+            }
+            for (const l of merged)
+                if (row.dailyPr)
+                    Object.assign(l, { pr: pr.branch });
+        }
+        if (review.length) {
+            const pr = await publish({
+                root,
+                branch: `homeostat/review-${member}-${today}`,
+                changes: review.map((l) => change(l, "review")),
+                provider,
+                kbRepo,
+                base,
+                title: `homeostat: ${plural(review.length, "lesson")} to review · ${member} · ${today}`,
+                body: prBody(member, today, list, "review"),
+                io,
+            });
+            if (pr.pr) {
+                row.reviewPr = pr.pr.url;
+                const logins = reviewerLogins(config, review, member);
+                if (logins.length)
+                    await provider.requestReviewers?.(kbRepo, pr.pr.id, logins).catch(() => undefined);
+            }
+            for (const l of review)
+                Object.assign(l, { pr: pr.branch });
+        }
+    }
+    // 5. Record decisions, heartbeats and the report for the laptops and the dashboard.
+    for (const l of lessons) {
+        report.lessons.push({
+            member: l.member,
+            id: l.id,
+            decision: l.decision,
+            ...(l.confidence ? { confidence: l.confidence.score } : {}),
+            reason: l.reason,
+        });
+        const record = {
+            path: l.path,
+            id: l.id,
+            hash: l.hash,
+            decision: l.decision,
+            reason: l.reason,
+            ...(l.confidence ? { confidence: l.confidence.score } : {}),
+            ...(l.pr ? { pr: l.pr } : {}),
+            at: now.toISOString(),
+        };
+        const d = decisions.get(l.member) ?? { member: l.member, decided: [] };
+        d.decided = [...d.decided.filter((r) => r.hash !== l.hash), record].slice(-500);
+        decisions.set(l.member, d);
+    }
+    if (!opts.dryRun) {
+        const state = {
+            [`runs/${today}.json`]: `${JSON.stringify(report, null, 1)}\n`,
+        };
+        for (const [m, d] of decisions)
+            if (d.decided.length)
+                state[decisionsPath(m)] = `${JSON.stringify(d, null, 1)}\n`;
+        for (const [m, hb] of Object.entries(heartbeats))
+            state[`heartbeats/${m}.json`] = `${hb}\n`;
+        const parent = git(root, "rev-parse", "--verify", "--quiet", remote(STATE_BRANCH));
+        const commit = commitTree(root, parent, state, `homeostat: daily run ${today}`);
+        forcePush(root, commit, STATE_BRANCH);
+        await notifyReviewQueue(config, report, [...decisions.values()], now, io);
+    }
+    logEvent(root, {
+        ts: now.toISOString(),
+        type: "agent-run",
+        agent: "daily",
+        ok: true,
+        summary: `${report.members.reduce((n, m) => n + m.merged, 0)} merged, ${report.members.reduce((n, m) => n + m.review, 0)} to review, ${report.members.reduce((n, m) => n + m.declined, 0)} declined, ${settled} settled`,
+    });
+    if (lessons.length === 0)
+        io.stdout("no new lessons\n");
+    if (opts.dryRun)
+        io.stdout("dry run: nothing committed, opened or merged\n");
+    return 0;
+}
+function pendingLesson(member, path, text, hash, before) {
+    const doc = isDocPath(path);
+    const fm = doc ? undefined : parseEntry(text).entry?.frontmatter;
+    const id = fm?.id ?? path;
+    const flagOnly = !!fm &&
+        before !== undefined &&
+        (parseEntry(before).entry?.frontmatter.flags?.length ?? 0) < (fm.flags?.length ?? 0);
+    return {
+        member,
+        path,
+        text: doc ? text : accepted(text),
+        hash,
+        id,
+        title: fm?.title ?? path,
+        kind: doc ? "doc" : before === undefined ? "new" : flagOnly ? "flag" : "update",
+        origin: "pending",
+        originator: fm?.source.author ?? member,
+        decision: "review",
+        reason: "",
+    };
+}
+function decide(l, files, config, acceptedFms, newFms) {
+    if (l.kind === "doc") {
+        l.decision = "review";
+        l.reason ||= "document edits go to the owning team";
+        return;
+    }
+    if (l.kind === "flag") {
+        // A flag needs no approval: it disputes the rule, which takes it out of sessions, until a
+        // reviewer resolves it. Making it wait would keep a wrong rule in force.
+        l.decision = "merged";
+        l.reason = "a flag disputes the rule at once; a reviewer resolves it";
+        l.text = l.text.replace(/^status: accepted$/m, "status: disputed");
+        return;
+    }
+    const entry = parseEntry(l.text).entry;
+    const issues = validate({ ...files, [l.path]: l.text }).issues.filter((i) => i.file === l.path && i.severity === "error");
+    if (!entry) {
+        l.decision = "declined";
+        l.reason = `does not parse: ${issues[0]?.message ?? "invalid entry"}`;
+        return;
+    }
+    const fm = entry.frontmatter;
+    const others = acceptedFms.filter((x) => x.id !== fm.id);
+    const dup = detectConflicts([...others, fm]).find((c) => c.kind === "possible-duplicate" && c.ids.includes(fm.id));
+    const occurrences = 1 +
+        detectConflicts(newFms).filter((c) => c.kind === "possible-duplicate" && c.ids.includes(fm.id))
+            .length;
+    const c = confidence({
+        entry,
+        config,
+        originator: l.originator,
+        occurrences,
+        risks: issues.filter((i) => i.code.startsWith("risk.")).map((i) => i.message),
+        errors: issues.filter((i) => !i.code.startsWith("risk.")).map((i) => i.message),
+        ...(dup && l.kind === "new" ? { duplicateOf: dup.ids.find((i) => i !== fm.id) ?? "" } : {}),
+        ...(fm.conflictsWith?.length ? { conflictsWith: fm.conflictsWith } : {}),
+    });
+    l.confidence = c;
+    l.decision = c.decision;
+    l.reason = c.reason;
+    if (dup && l.kind === "new")
+        l.duplicateOf = dup.ids.find((i) => i !== fm.id);
+}
+const change = (l, kind) => ({
+    path: l.path,
+    text: l.text,
+    message: `homeostat: ${kind === "merge" ? "merge" : "propose"} ${l.id} (${l.reason})`,
+});
+/** A duplicate reconfirms the rule it repeats: its lastConfirmed moves to today. */
+function reconfirmChange(files, entries, id, today) {
+    const found = entries.find((e) => e.entry.frontmatter.id === id);
+    const text = found ? files[found.path] : undefined;
+    if (!found || !text)
+        return undefined;
+    return {
+        path: found.path,
+        text: text.replace(/^lastConfirmed: .*$/m, `lastConfirmed: ${today}`),
+        message: `homeostat: reconfirm ${id} (a lesson repeated it)`,
+    };
+}
+function reviewerLogins(config, review, member) {
+    const handles = new Set();
+    for (const l of review) {
+        const area = parseEntry(l.text).entry?.frontmatter.area ?? "core";
+        const team = Object.values(config.teams).find((t) => t.areas.includes(area));
+        const owners = team
+            ? team.handle
+                ? [team.handle]
+                : team.members.map((id) => config.team.members.find((m) => m.id === id)?.handle)
+            : config.team.members
+                .filter((m) => m.areas.includes(area) && m.id !== member)
+                .map((m) => m.handle);
+        const fallback = config.team.members
+            .filter((m) => m.role === "lead" || m.role === "senior")
+            .map((m) => m.handle);
+        for (const h of owners.length ? owners : fallback)
+            if (h?.startsWith("@") && !h.includes("/"))
+                handles.add(h.slice(1));
+    }
+    const self = config.team.members.find((m) => m.id === member)?.handle?.slice(1);
+    return [...handles].filter((h) => h !== self);
+}
+function prBody(member, today, list, kind) {
+    const rows = list.map((l) => {
+        const why = l.confidence ? `${l.reason}<br>${explainConfidence(l.confidence)}` : l.reason;
+        const src = l.url ? `[review](${l.url})` : l.origin === "pending" ? "written by hand" : "";
+        return `| ${l.decision} | ${l.title} (\`${l.id}\`) | ${l.confidence?.score ?? ""} | ${src} | ${why} |`;
+    });
+    return [
+        kind === "daily"
+            ? `Daily lessons for ${member}, ${today}. The lessons marked merged passed every check and the confidence threshold, so this PR merges itself. Declined lessons are listed for the record; lessons to review are in a separate PR.`
+            : `Lessons for ${member}, ${today}, that the daily run could not decide. Merge to accept them, close to decline, or edit first. The developer's sync picks up the outcome.`,
+        "",
+        "| Decision | Lesson | Confidence | Source | Why |",
+        "| --- | --- | --- | --- | --- |",
+        ...rows,
+        "",
+        "Decided by `homeostat daily`. Thresholds and weights are in `scoring.confidence` in homeostat.yaml; `homeostat flag <id>` sends any rule back for review.",
+    ].join("\n");
+}
+/** The morning notice: today's review PRs, and a reminder for lessons waiting longer. */
+async function notifyReviewQueue(config, report, decisions, now, io) {
+    const variable = config.notifications.slackWebhookEnv;
+    const url = variable ? io.env?.[variable] : undefined;
+    const waiting = report.members.filter((m) => m.review > 0 && m.reviewPr);
+    const cutoff = new Date(now.getTime() - REVIEW_REMINDER_DAYS * 86_400_000).toISOString();
+    const overdue = decisions.flatMap((d) => d.decided
+        .filter((r) => r.decision === "review" && r.at < cutoff)
+        .map((r) => ({ member: d.member, ...r })));
+    if (!url || !/^https:\/\/hooks\.slack\.com\//.test(url))
+        return;
+    if (waiting.length === 0 && overdue.length === 0)
+        return;
+    const text = [
+        ...(waiting.length
+            ? [
+                `*Homeostat: ${plural(waiting.reduce((n, m) => n + m.review, 0), "lesson")} waiting for review*`,
+                ...waiting.map((m) => `• ${m.member}: ${m.review} — ${m.reviewPr}`),
+            ]
+            : []),
+        ...(overdue.length
+            ? [
+                `*Still waiting after ${REVIEW_REMINDER_DAYS} days: ${plural(overdue.length, "lesson")}*`,
+                ...overdue.map((r) => `• ${r.id} (${r.member}, since ${r.at.slice(0, 10)}) — ${r.pr ?? ""}`),
+            ]
+            : []),
+    ].join("\n");
+    try {
+        await (io.fetch ?? fetch)(url, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ text, mrkdwn: true }),
+        });
+    }
+    catch {
+        // The dashboard shows the queue too; a failed notice must not fail the run.
+    }
+}

package/dist/src/doctor.js

@@ -108,7 +108,9 @@ function pinnedVersions(root) {
     const checks = [];
     for (const path of ci) {
         const text = readFileSync(join(root, path), "utf8");
-        for (const m of text.matchAll(/\bhomeostat(@[^\s"']*)?\s+(validate|curate|deep-dive|export)\b/g)) {
+        // Only command lines (npx, dlx, a run: step or a script list item): a job's `name:` or a
+        // `git config user.name "homeostat deep-dive"` line reads the same but runs nothing.
+        for (const m of text.matchAll(/(?:\bnpx(?:\s+(?:--yes|-y))?|\bdlx|\brun:|^\s*-)\s+homeostat(@[^\s"']*)?\s+(validate|daily|curate|deep-dive|digest|export)\b/gm)) {
             const version = m[1]?.slice(1);
             if (!version || !/^\d+\.\d+\.\d+(-[\w.]+)?$/.test(version)) {
                 checks.push(fail(`${path} runs homeostat${m[1] ?? ""}: pin an exact version (homeostat@${VERSION}) so a new release cannot run unreviewed`));
@@ -147,8 +149,8 @@ export async function securityReport(root, config, io) {
     const changes = [
         ...access,
         am.enabled
-            ? info(`auto-merge: on for review feedback scoring ${config.scoring.autoMergeThreshold}+ with a code change and no findings; ${am.areas.length ? `areas ${am.areas.join(", ")}` : "all areas"}${am.excludeAreas.length ? ` except ${am.excludeAreas.join(", ")}` : ""}; at most ${am.maxPerRun} per run`)
-            : ok("auto-merge is off: every entry needs a reviewer"),
+            ? info(`the daily run merges lessons at confidence ${config.scoring.confidence.accept}+ (${config.scoring.confidence.coreAccept}+ for core), declines below ${config.scoring.confidence.decline}, and asks a reviewer in between; risky content, conflicts and document edits always go to a reviewer; ${am.areas.length ? `areas ${am.areas.join(", ")}` : "all areas"}${am.excludeAreas.length ? ` except ${am.excludeAreas.join(", ")}` : ""}`)
+            : ok("auto-merge is off: the daily run sends every lesson to a reviewer"),
         existsSync(join(root, ".github/CODEOWNERS")) || existsSync(join(root, "CODEOWNERS"))
             ? ok("CODEOWNERS routes each area to its reviewers")
             : warn("no CODEOWNERS file: run homeostat codeowners"),

package/dist/src/flag.js

@@ -1,8 +1,8 @@
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { join, resolve } from "node:path";
-import { flagEntry, logEvent, readKbFiles, scanSecrets, validate } from "@homeostat/core";
+import { resolve } from "node:path";
+import { flagEntry, logEvent, readKbView, scanSecrets, validate, writePendingFile, } from "@homeostat/core";
 import { commitFile, git, pushBranch } from "./git.js";
 import { memberIdFrom } from "./init.js";
+import { sendPending } from "./learn.js";
 import { CliError } from "./provider.js";
 /** `homeostat flag <id>`: reports that an entry is wrong. It loses score and goes back to review. */
 export function runFlag(id, opts, io) {
@@ -15,7 +15,7 @@ export function runFlag(id, opts, io) {
             throw new CliError(`the reason contains a possible ${leak.kind}; remove it before flagging`);
         if (opts.push && !opts.branch)
             throw new CliError("--push needs --branch");
-        const kb = validate(readKbFiles(root));
+        const kb = validate(readKbView(root).files);
         if (!kb.config) {
             throw new CliError("homeostat.yaml is missing or invalid; run homeostat validate");
         }
@@ -48,12 +48,9 @@ export function runFlag(id, opts, io) {
             io.stdout(`flagged ${id} on ${opts.branch}${opts.push ? " (pushed)" : ""}; it is ${status} until a reviewer decides\n`);
             return 0;
         }
-        const full = join(root, ...found.path.split("/"));
-        if (!existsSync(full) || readFileSync(full, "utf8") === text) {
-            throw new CliError(`could not update ${found.path}`);
-        }
-        writeFileSync(full, text);
-        io.stdout(`flagged ${id} in ${found.path}; it is ${status} until a reviewer decides. Commit it on a branch and open a PR.\n`);
+        writePendingFile(root, found.path, text);
+        sendPending(root, io);
+        io.stdout(`flagged ${id}: it no longer applies to your sessions (${status}), and tomorrow's daily run takes the flag to the team\n`);
         return 0;
     }
     catch (e) {

package/dist/src/git.d.ts

@@ -1,5 +1,7 @@
 /** Runs git in `dir`; undefined when it fails (not a repo, unknown ref, ...). */
 export declare function git(dir: string, ...args: string[]): string | undefined;
+/** A file's exact text on a ref (git() trims, which would change a lesson's hash). */
+export declare function showFile(dir: string, ref: string, path: string): string | undefined;
 /** True when `path` exists in the tree of `ref`. */
 export declare function existsOnRef(dir: string, ref: string, path: string): boolean;
 /**
@@ -8,3 +10,10 @@ export declare function existsOnRef(dir: string, ref: string, path: string): boo
  */
 export declare function commitFile(dir: string, branch: string, path: string, content: string, message: string): string;
 export declare function pushBranch(dir: string, branch: string, remote?: string): void;
+/**
+ * Builds a commit of `base` plus `files` (path → content) with a throwaway index, without touching
+ * the working tree, the real index or any branch. Returns the commit id.
+ */
+export declare function commitTree(dir: string, base: string | undefined, files: Record<string, string>, message: string): string;
+/** Force-pushes a commit to a branch on origin (for transport branches only). */
+export declare function forcePush(dir: string, commit: string, branch: string, remote?: string): void;