homeostat 0.1.1 → 0.1.3

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.1 init
+npx --yes homeostat@0.1.3 init
 
 # In Claude Code:
 claude plugin marketplace add ysugarmen/homeostat

package/dist/src/curate.js

@@ -168,8 +168,13 @@ async function curateRun(opts, io) {
     for (const d of result.docs) {
         io.stdout(`~ ${d.path} (${d.sections.map((s) => `#${s.id}`).join(", ")})\n`);
     }
-    for (const s of result.skipped)
-        io.stdout(`- ${s.url}: ${s.reason}\n`);
+    for (const s of result.skipped) {
+        // With --show-prompts nothing was sent, so the empty answer is not the model's verdict.
+        const reason = opts.showPrompts && s.reason === "no lasting rule in the thread"
+            ? "prompt shown above; nothing sent"
+            : s.reason;
+        io.stdout(`- ${s.url}: ${reason}\n`);
+    }
     if (result.redacted) {
         io.stdout(`redacted ${result.redacted} secret(s) from review threads before drafting\n`);
     }

package/dist/src/daily.js

@@ -1,8 +1,8 @@
 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 { ClaudeDocPatcher, ClaudeDrafter, candidatesBranch, confidence, curate, decisionsPath, explainConfidence, HEARTBEAT_PATH, isDocPath, lessonHash, logEvent, parseEntry, REVIEW_REMINDER_DAYS, readKbFiles, STATE_BRANCH, sameLesson, validate, } from "@homeostat/core";
 import { askerFor } from "./agents.js";
 import { plural } from "./format.js";
-import { commitTree, forcePush, git, showFile } from "./git.js";
+import { commitTree, forcePush, git, mergeText, showFile } from "./git.js";
 import { CliError, providerFor } from "./provider.js";
 import { publish } from "./publish.js";
 const repoRef = (ref) => {
@@ -140,18 +140,52 @@ async function daily(opts, io) {
                 kind: "doc",
                 origin: "review",
                 originator: d.sections[0]?.prAuthor ?? "",
+                ...(d.sections[0]?.url ? { url: d.sections[0].url } : {}),
                 decision: "review",
                 reason: "document edits go to the owning team",
             });
         }
     }
+    // A developer's pending edit and a review-drafted patch to the same document become one change:
+    // merged three ways against the base branch, or the developer's edit alone if they conflict.
+    for (const doc of lessons.filter((l) => l.kind === "doc" && l.origin === "review")) {
+        const mine = lessons.find((l) => l !== doc && l.kind === "doc" && l.path === doc.path && l.member === doc.member);
+        if (!mine)
+            continue;
+        const merged = mergeText(onBase(doc.path) ?? "", mine.text, doc.text);
+        lessons.splice(lessons.indexOf(doc), 1);
+        if (merged === undefined) {
+            mine.reason = `document edits go to the owning team; a section patch from review (${doc.url ?? "a review thread"}) touched the same lines and was left out`;
+        }
+        else {
+            mine.text = merged;
+            mine.reason = "document edits go to the owning team; includes a section patch from review";
+        }
+    }
     // 2. Decide each lesson.
-    const acceptedFms = kb.entries
+    const inForce = 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() : []);
+        .map((e) => e.entry);
+    // New lessons that teach the same thing, from anyone in this run, are decided together.
+    const fresh = lessons.flatMap((l) => {
+        const entry = l.kind === "new" ? parseEntry(l.text).entry : undefined;
+        return entry ? [{ l, entry }] : [];
+    });
+    const groups = new Map();
+    for (const a of fresh) {
+        groups.set(a.l, fresh.filter((b) => b === a || sameLesson(a.entry, b.entry)).map((b) => b.l));
+    }
     for (const l of lessons)
-        decide(l, files, config, acceptedFms, newFms);
+        decide(l, files, config, inForce, groups.get(l)?.length ?? 1);
+    for (const [l, group] of groups) {
+        if (group.length < 2)
+            continue;
+        const winner = group.reduce((best, x) => (x.confidence?.score ?? -1) > (best.confidence?.score ?? -1) ? x : best);
+        if (winner === l || l.decision === "declined")
+            continue;
+        l.decision = "declined";
+        l.reason = `the same lesson as ${winner.id} in this run, which carries it (${winner.decision})`;
+    }
     // 3–4. Per developer: one daily PR (merged), one review PR (assigned).
     const report = { at: now.toISOString(), members: [], settled, lessons: [] };
     const byMember = new Map();
@@ -302,7 +336,7 @@ function pendingLesson(member, path, text, hash, before) {
         reason: "",
     };
 }
-function decide(l, files, config, acceptedFms, newFms) {
+function decide(l, files, config, inForce, occurrences) {
     if (l.kind === "doc") {
         l.decision = "review";
         l.reason ||= "document edits go to the owning team";
@@ -324,11 +358,9 @@ function decide(l, files, config, acceptedFms, newFms) {
         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 dupOf = l.kind === "new"
+        ? inForce.find((x) => x.frontmatter.id !== fm.id && sameLesson(x, entry))?.frontmatter.id
+        : undefined;
     const c = confidence({
         entry,
         config,
@@ -336,14 +368,14 @@ function decide(l, files, config, acceptedFms, newFms) {
         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) ?? "" } : {}),
+        ...(dupOf ? { duplicateOf: dupOf } : {}),
         ...(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);
+    if (dupOf)
+        l.duplicateOf = dupOf;
 }
 const change = (l, kind) => ({
     path: l.path,

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|daily|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/git.d.ts

@@ -17,3 +17,8 @@ export declare function pushBranch(dir: string, branch: string, remote?: string)
 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;
+/**
+ * Three-way merge of two edits to one file (`git merge-file`), or undefined when they conflict.
+ * Section edits to different sections of a document merge cleanly.
+ */
+export declare function mergeText(base: string, ours: string, theirs: string): string | undefined;

package/dist/src/git.js

@@ -1,5 +1,5 @@
 import { execFileSync } from "node:child_process";
-import { mkdtempSync, rmSync } from "node:fs";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 /** Runs git in `dir`; undefined when it fails (not a repo, unknown ref, ...). */
@@ -119,3 +119,26 @@ export function commitTree(dir, base, files, message) {
 export function forcePush(dir, commit, branch, remote = "origin") {
     gitOrThrow(dir, ["push", "--quiet", "--force", remote, `${commit}:refs/heads/${branch}`]);
 }
+/**
+ * Three-way merge of two edits to one file (`git merge-file`), or undefined when they conflict.
+ * Section edits to different sections of a document merge cleanly.
+ */
+export function mergeText(base, ours, theirs) {
+    const dir = mkdtempSync(join(tmpdir(), "homeostat-merge-"));
+    try {
+        const [o, b, t] = ["ours", "base", "theirs"].map((n) => join(dir, n));
+        writeFileSync(o, ours);
+        writeFileSync(b, base);
+        writeFileSync(t, theirs);
+        return execFileSync("git", ["merge-file", "-p", o, b, t], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+    }
+    catch {
+        return undefined; // a non-zero exit is the number of conflicts
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}

package/dist/src/hook.js

@@ -4,7 +4,7 @@ import { AGENT_ENV, CONFIG_FILE, CORE_AREA, docContext, logEvent, pruneEvents, r
 import { git } from "./git.js";
 import { memberIdFrom } from "./init.js";
 import { pendingFingerprint, readSyncState, syncDue, takeNotices } from "./sync.js";
-import { touchedPaths } from "./touched.js";
+import { touchedPaths, uncommitted } from "./touched.js";
 /** Claude Code's limit on SessionStart `additionalContext`. */
 const MAX_CONTEXT_CHARS = 10_000;
 /** The KB checkout: the plugin's kb_dir option, then $HOMEOSTAT_DIR, then the session dir itself. */
@@ -58,10 +58,13 @@ async function sessionStart(input, io) {
         });
     }
     if (input.session_id) {
+        const previous = readState(kbRoot, input.session_id);
         writeState(kbRoot, input.session_id, {
-            ...readState(kbRoot, input.session_id),
+            ...previous,
             injected: selection.items.map((i) => i.entry.frontmatter.id),
             view: viewKey(kbRoot),
+            // Kept from the first start: resume, clear and compact start the same session again.
+            dirtyAtStart: previous.dirtyAtStart ?? uncommitted(cwd),
         });
     }
     // Catch up with the daily run in the background; this session starts with what is local now.
@@ -141,7 +144,11 @@ async function stop(input, io) {
     const state = readState(kbRoot, input.session_id);
     if (state.asked)
         return;
-    const edits = countEdits(input.transcript_path);
+    // Edit tool calls, or files changed since the session started, whichever is more: agents also
+    // edit through the shell (sed, scripts), which no tool call shows.
+    const before = new Set(state.dirtyAtStart ?? []);
+    const changed = state.dirtyAtStart ? uncommitted(cwd).filter((p) => !before.has(p)).length : 0;
+    const edits = Math.max(countEdits(input.transcript_path), changed);
     if (edits < config.agents.handoff.minEdits && !state.compacted)
         return;
     const member = memberIdFrom(git(cwd, "config", "user.name"));

package/dist/src/init.js

@@ -36,8 +36,10 @@ ${handleLine}
 #   payments: ["services/payments/**"]
 areas: {}
 
-scoring:
-  autoMergeThreshold: 3
+# The daily run decides each lesson by a 0-100 confidence: it merges at 70+ (80+ for core),
+# declines below 35, and sends the rest to a reviewer. Tune it under scoring.confidence.
+# scoring:
+#   confidence: { accept: 70, coreAccept: 80, decline: 35 }
 
 distribution:
   tokenBudget: 2000

package/dist/src/learn.js

@@ -134,7 +134,9 @@ async function learn(url, opts, io) {
     };
     frontmatter.score = score(frontmatter, { config }).score;
     const text = formatEntry(frontmatter, body);
-    const issues = validate({ ...files, [path]: text }).issues.filter((i) => i.file === path && i.severity === "error");
+    const found = validate({ ...files, [path]: text }).issues.filter((i) => i.file === path);
+    const issues = found.filter((i) => i.severity === "error");
+    const warnings = found.filter((i) => i.severity !== "error");
     if (issues.length > 0) {
         io.stdout(`${formatIssues(issues, io).text}nothing written\n`);
         return 1;
@@ -166,6 +168,8 @@ async function learn(url, opts, io) {
     writePendingFile(root, path, text);
     sendPending(root, io);
     io.stdout(`saved ${id} ${summary}: it applies to your sessions now, and tomorrow's daily run decides it for the team\n`);
+    if (warnings.length)
+        io.stdout(formatIssues(warnings, io).text);
     return 0;
 }
 /**
@@ -203,7 +207,9 @@ function learnDoc(root, files, config, opts, io) {
             throw new LearnError(e.message);
         throw e;
     }
-    const issues = validate({ ...files, [path]: text }).issues.filter((i) => i.file === path && i.severity === "error");
+    const found = validate({ ...files, [path]: text }).issues.filter((i) => i.file === path);
+    const issues = found.filter((i) => i.severity === "error");
+    const warnings = found.filter((i) => i.severity !== "error");
     if (issues.length > 0) {
         io.stdout(`${formatIssues(issues, io).text}nothing written\n`);
         return 1;
@@ -226,6 +232,8 @@ function learnDoc(root, files, config, opts, io) {
     writePendingFile(root, path, text);
     sendPending(root, io);
     io.stdout(`${what}: it applies to your sessions now, and tomorrow's daily run decides it for the team\n`);
+    if (warnings.length)
+        io.stdout(formatIssues(warnings, io).text);
     return 0;
 }
 /** Sends pending lessons to the daily run in the background, when the KB has an origin. */

package/dist/src/query.js

@@ -18,6 +18,7 @@ function load(opts, io, view = {}) {
     const pendingIds = new Set(kb.entries.filter((e) => pending.has(e.path)).map((e) => e.entry.frontmatter.id));
     return {
         root,
+        issues: kb.issues,
         config: kb.config,
         entries: kb.entries.map((e) => e.entry),
         docs: kb.docs,
@@ -75,9 +76,11 @@ export function runExplain(id, opts, io) {
         }
         io.stdout(opts.json
             ? `${JSON.stringify({ ...entry.frontmatter, sections: entry.sections }, null, 2)}\n`
-            : `${explainEntry(entry, config)}\n${pendingIds.has(id)
-                ? "Pending in this clone: it applies to your sessions now; the next daily run decides it for the team.\n"
-                : ""}`);
+            : `${explainEntry(entry, config)}\n${!pendingIds.has(id)
+                ? ""
+                : entry.frontmatter.flags?.length
+                    ? "Pending in this clone, flagged: it is out of your sessions until the next daily run takes the flag to the team.\n"
+                    : "Pending in this clone: it applies to your sessions now; the next daily run decides it for the team.\n"}`);
         return 0;
     });
 }
@@ -105,7 +108,7 @@ export function runList(opts, io) {
 }
 export function runStatus(opts, io) {
     return guard(io, () => {
-        const { root, config, entries, docs } = load(opts, io);
+        const { root, config, entries, docs, issues } = load(opts, io);
         const days = opts.days ? Number(opts.days) : 7;
         const now = io.now?.() ?? new Date();
         // The report counts its own window; document decay looks back 90 days.
@@ -113,6 +116,14 @@ export function runStatus(opts, io) {
             since: new Date(now.getTime() - Math.max(days, 90) * 86_400_000).toISOString(),
         });
         io.stdout(`${kbReport(entries, config, { days, now, events, docs })}\n`);
+        // Includes pending lessons, which CI's validate never sees: say so here, before the daily run.
+        const errors = issues.filter((i) => i.severity === "error");
+        if (errors.length) {
+            io.stdout(`- Problems: ${errors.length}, including pending lessons\n${errors
+                .slice(0, 5)
+                .map((i) => `  ${i.file ?? ""}: ${i.message}\n`)
+                .join("")}`);
+        }
         return 0;
     });
 }

package/dist/src/sync.js

@@ -28,7 +28,9 @@ export function pendingFingerprint(root) {
 const idOf = (path) => path.split("/").at(-1)?.replace(/\.md$/, "") ?? path;
 export async function runSync(opts, io) {
     const root = resolve(opts.dir ?? io.env?.HOMEOSTAT_DIR ?? ".");
+    let said = false;
     const say = (s) => {
+        said = true;
         if (!opts.quiet)
             io.stdout(s);
     };
@@ -124,6 +126,15 @@ export async function runSync(opts, io) {
     }
     for (const n of notices)
         say(`${n.text}\n`);
+    // A sync by hand that changed nothing still says so, rather than printing nothing.
+    if (!said) {
+        const count = Object.keys(readPendingFiles(root)).length;
+        say(!isMember
+            ? `up to date with ${base}; "${member}" is not a member in homeostat.yaml, so lessons stay local\n`
+            : count
+                ? `up to date: ${count} pending lesson(s) already on ${candidatesBranch(member)}\n`
+                : `up to date with ${base}; no pending lessons\n`);
+    }
     writeSyncState(root, {
         lastSync: now,
         ...(lastHeartbeat ? { lastHeartbeat } : {}),

package/dist/src/touched.d.ts

@@ -1,3 +1,5 @@
+/** Paths from `git status --porcelain`, using the new name for renames. */
+export declare function uncommitted(dir: string): string[];
 /**
  * Repo-relative paths a session in `dir` is likely to touch: uncommitted changes, the current
  * branch's changes against its base, then files from recent commits. Best first, de-duplicated.

package/dist/src/touched.js

@@ -3,7 +3,7 @@ const MAX_PATHS = 500;
 const RECENT_COMMITS = 10;
 const lines = (text) => (text ?? "").split("\n").filter(Boolean);
 /** Paths from `git status --porcelain`, using the new name for renames. */
-function uncommitted(dir) {
+export function uncommitted(dir) {
     return lines(git(dir, "status", "--porcelain=v1", "--untracked-files=all")).map((line) => {
         const path = line.slice(3);
         const arrow = path.indexOf(" -> ");

package/dist/src/validate.js

@@ -1,10 +1,12 @@
 import { resolve } from "node:path";
-import { applyFixes, readKbFiles, validate, writeKbFile, } from "@homeostat/core";
+import { applyFixes, readKbView, validate, writeKbFile, writePendingFile, } from "@homeostat/core";
 import { formatIssues, painter, plural } from "./format.js";
 /** `homeostat validate [dir]`. Returns the process exit code: 1 when there are errors. */
 export function runValidate(dir, opts, io) {
     const root = resolve(dir);
-    let files = readKbFiles(root);
+    // Pending lessons are checked too: CI never sees them, so this is where a developer would.
+    let view = readKbView(root);
+    let files = view.files;
     let result = validate(files);
     if (opts.fix) {
         const byFile = new Map();
@@ -15,16 +17,24 @@ export function runValidate(dir, opts, io) {
         }
         let fields = 0;
         for (const [path, fixes] of byFile) {
-            writeKbFile(root, path, applyFixes(files[path] ?? "", fixes));
+            const fixed = applyFixes(files[path] ?? "", fixes);
+            if (view.pending.has(path))
+                writePendingFile(root, path, fixed);
+            else
+                writeKbFile(root, path, fixed);
             fields += fixes.length;
         }
         if (byFile.size > 0 && !opts.json) {
             io.stdout(`fixed ${plural(fields, "field")} in ${plural(byFile.size, "file")}\n`);
-            files = readKbFiles(root);
+            view = readKbView(root);
+            files = view.files;
             result = validate(files);
         }
     }
     io.stdout(opts.json ? `${JSON.stringify(toJson(result), null, 2)}\n` : format(result, io));
+    if (!opts.json && view.pending.size > 0) {
+        io.stdout(`(including ${plural(view.pending.size, "pending lesson")} from .homeostat/pending, which the daily run decides)\n`);
+    }
     return result.ok ? 0 : 1;
 }
 function toJson(result) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "homeostat",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Turn your team's code-review lessons into rules every coding agent follows: Claude Code, MCP, Cursor, Copilot, AGENTS.md.",
   "keywords": [
     "claude-code",
@@ -39,9 +39,9 @@
   },
   "dependencies": {
     "commander": "^15.0.0",
-    "@homeostat/core": "0.1.1",
-    "@homeostat/dashboard": "0.1.1",
-    "@homeostat/mcp": "0.1.1"
+    "@homeostat/core": "0.1.3",
+    "@homeostat/mcp": "0.1.3",
+    "@homeostat/dashboard": "0.1.3"
   },
   "publishConfig": {
     "access": "public",