facult 2.8.4 → 2.8.6

package/README.md

@@ -441,13 +441,13 @@ fclt ai evolve apply EV-00001
 fclt ai evolve promote EV-00003 --to global --project
 ```
 
-Runtime state stays generated and local inside the active canonical root:
-- global writeback state: `~/.ai/.facult/ai/global/...`
+Runtime writeback and evolution state stays generated and machine-local:
+- global writeback state: machine-local Facult state under `.../global/ai/global/...`
 - project writeback state: machine-local per-project Facult state under `.../projects/<slug-hash>/ai/project/...`
 
 That split is intentional:
 - canonical source remains in `~/.ai` or `<repo>/.ai`
-- global generated state stays inside `~/.ai/.facult/`; project generated state stays outside the repo in machine-local state
+- global generated index and graph state stays inside `~/.ai/.facult/`; writebacks, journals, proposals, drafts, and managed runtime state stay outside canonical source in machine-local state
 - those records let agents inspect what changed, why it changed, and how it was reviewed
 
 Use writeback when:
@@ -698,6 +698,8 @@ Under canonical generated AI state (`~/.ai/.facult/` or `<repo>/.ai/.facult/`):
 Under machine-local Facult state:
 - `install.json` (machine-local install metadata)
 - `global/managed.json` or `projects/<slug-hash>/managed.json` (managed tool state)
+- `global/ai/global/writeback/queue.jsonl` and `projects/<slug-hash>/ai/project/writeback/queue.jsonl` (writeback queues)
+- `global/ai/global/evolution/` and `projects/<slug-hash>/ai/project/evolution/` (proposal metadata, markdown drafts, and patch artifacts)
 - `.../autosync/services/*.json` (autosync service configs)
 - `.../autosync/state/*.json` (autosync runtime state)
 - `.../autosync/logs/*` (autosync service logs)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "facult",
-  "version": "2.8.4",
+  "version": "2.8.6",
   "description": "Manage canonical AI capabilities, sync surfaces, and evolution state.",
   "type": "module",
   "license": "MIT",

package/src/ai.ts

@@ -9,6 +9,7 @@ import {
   facultAiDraftDir,
   facultAiJournalPath,
   facultAiProposalDir,
+  facultAiStateDir,
   facultAiWritebackQueuePath,
   facultRootDir,
   legacyFacultAiStateDirs,
@@ -233,9 +234,10 @@ function aiRuntimeScopeName(rootDir: string, homeDir: string): AssetScope {
 
 function legacyAiRuntimeScopeDirs(homeDir: string, rootDir: string): string[] {
   const scope = aiRuntimeScopeName(rootDir, homeDir);
-  return legacyFacultAiStateDirs(homeDir, rootDir).map((dir) =>
-    join(dir, scope)
-  );
+  return uniqueStrings([
+    join(facultAiStateDir(homeDir, rootDir), scope),
+    ...legacyFacultAiStateDirs(homeDir, rootDir).map((dir) => join(dir, scope)),
+  ]);
 }
 
 function aiWritebackQueueReadPaths(homeDir: string, rootDir: string): string[] {
@@ -1604,15 +1606,15 @@ function parseEvidence(argv: string[]): WritebackEvidence[] {
 }
 
 async function writebackCommand(argv: string[]) {
-  const [sub, ...rest] = argv;
-  const parsed = parseCliContextArgs(rest);
+  const parsed = parseCliContextArgs(argv);
+  const [sub, ...commandArgs] = parsed.argv;
 
   if (!sub || sub === "--help" || sub === "-h" || sub === "help") {
     console.log(writebackHelp());
     return;
   }
 
-  if (parsed.argv.includes("--help") || parsed.argv.includes("-h")) {
+  if (commandArgs.includes("--help") || commandArgs.includes("-h")) {
     console.log(writebackHelp());
     return;
   }
@@ -1625,8 +1627,8 @@ async function writebackCommand(argv: string[]) {
 
   try {
     if (sub === "add") {
-      const kind = parseStringFlag(parsed.argv, "--kind");
-      const summary = parseStringFlag(parsed.argv, "--summary");
+      const kind = parseStringFlag(commandArgs, "--kind");
+      const summary = parseStringFlag(commandArgs, "--summary");
       if (!(kind && summary)) {
         throw new Error("writeback add requires --kind and --summary");
       }
@@ -1634,18 +1636,18 @@ async function writebackCommand(argv: string[]) {
         rootDir,
         kind,
         summary,
-        asset: parseStringFlag(parsed.argv, "--asset"),
-        allowEmptyEvidence: parsed.argv.includes("--allow-empty-evidence"),
+        asset: parseStringFlag(commandArgs, "--asset"),
+        allowEmptyEvidence: commandArgs.includes("--allow-empty-evidence"),
         confidence:
-          (parseStringFlag(parsed.argv, "--confidence") as
+          (parseStringFlag(commandArgs, "--confidence") as
             | ConfidenceLevel
             | undefined) ?? undefined,
         suggestedDestination: parseStringFlag(
-          parsed.argv,
+          commandArgs,
           "--suggested-destination"
         ),
-        tags: parseRepeatedFlag(parsed.argv, "--tag"),
-        evidence: parseEvidence(parsed.argv),
+        tags: parseRepeatedFlag(commandArgs, "--tag"),
+        evidence: parseEvidence(commandArgs),
       });
       console.log(`Recorded writeback ${record.id}`);
       console.log(JSON.stringify(record, null, 2));
@@ -1654,7 +1656,7 @@ async function writebackCommand(argv: string[]) {
 
     if (sub === "list") {
       const rows = await listWritebacks({ rootDir });
-      if (parsed.argv.includes("--json")) {
+      if (commandArgs.includes("--json")) {
         console.log(JSON.stringify(rows, null, 2));
         return;
       }
@@ -1665,7 +1667,7 @@ async function writebackCommand(argv: string[]) {
     }
 
     if (sub === "group" || sub === "summarize") {
-      const byValue = parseStringFlag(parsed.argv, "--by") ?? "asset";
+      const byValue = parseStringFlag(commandArgs, "--by") ?? "asset";
       if (byValue !== "asset" && byValue !== "kind" && byValue !== "domain") {
         throw new Error(`Unsupported writeback grouping: ${byValue}`);
       }
@@ -1673,7 +1675,7 @@ async function writebackCommand(argv: string[]) {
         sub === "group"
           ? await groupWritebacks({ rootDir, by: byValue })
           : await summarizeWritebacks({ rootDir, by: byValue });
-      if (parsed.argv.includes("--json")) {
+      if (commandArgs.includes("--json")) {
         console.log(JSON.stringify(rows, null, 2));
         return;
       }
@@ -1686,7 +1688,7 @@ async function writebackCommand(argv: string[]) {
     }
 
     if (sub === "show") {
-      const id = parsed.argv.find((arg) => !arg.startsWith("-"));
+      const id = commandArgs.find((arg) => !arg.startsWith("-"));
       if (!id) {
         throw new Error("writeback show requires an id");
       }
@@ -1699,7 +1701,7 @@ async function writebackCommand(argv: string[]) {
     }
 
     if (sub === "dismiss" || sub === "promote") {
-      const id = parsed.argv.find((arg) => !arg.startsWith("-"));
+      const id = commandArgs.find((arg) => !arg.startsWith("-"));
       if (!id) {
         throw new Error(`writeback ${sub} requires an id`);
       }
@@ -1720,15 +1722,15 @@ async function writebackCommand(argv: string[]) {
 }
 
 async function evolveCommand(argv: string[]) {
-  const [sub, ...rest] = argv;
-  const parsed = parseCliContextArgs(rest);
+  const parsed = parseCliContextArgs(argv);
+  const [sub, ...commandArgs] = parsed.argv;
 
   if (!sub || sub === "--help" || sub === "-h" || sub === "help") {
     console.log(evolveHelp());
     return;
   }
 
-  if (parsed.argv.includes("--help") || parsed.argv.includes("-h")) {
+  if (commandArgs.includes("--help") || commandArgs.includes("-h")) {
     console.log(evolveHelp());
     return;
   }
@@ -1743,9 +1745,9 @@ async function evolveCommand(argv: string[]) {
     if (sub === "propose") {
       const proposals = await proposeEvolution({
         rootDir,
-        asset: parseStringFlag(parsed.argv, "--asset"),
+        asset: parseStringFlag(commandArgs, "--asset"),
       });
-      if (parsed.argv.includes("--json")) {
+      if (commandArgs.includes("--json")) {
         console.log(JSON.stringify(proposals, null, 2));
         return;
       }
@@ -1759,7 +1761,7 @@ async function evolveCommand(argv: string[]) {
 
     if (sub === "list") {
       const rows = await listProposals({ rootDir });
-      if (parsed.argv.includes("--json")) {
+      if (commandArgs.includes("--json")) {
         console.log(JSON.stringify(rows, null, 2));
         return;
       }
@@ -1770,7 +1772,7 @@ async function evolveCommand(argv: string[]) {
     }
 
     if (sub === "show") {
-      const id = parsed.argv.find((arg) => !arg.startsWith("-"));
+      const id = commandArgs.find((arg) => !arg.startsWith("-"));
       if (!id) {
         throw new Error("evolve show requires an id");
       }
@@ -1791,7 +1793,7 @@ async function evolveCommand(argv: string[]) {
       sub === "apply" ||
       sub === "promote"
     ) {
-      const id = parsed.argv.find((arg) => !arg.startsWith("-"));
+      const id = commandArgs.find((arg) => !arg.startsWith("-"));
       if (!id) {
         throw new Error(`evolve ${sub} requires an id`);
       }
@@ -1799,7 +1801,7 @@ async function evolveCommand(argv: string[]) {
         sub === "draft"
           ? await draftProposal(id, {
               rootDir,
-              append: parseStringFlag(parsed.argv, "--append"),
+              append: parseStringFlag(commandArgs, "--append"),
             })
           : sub === "review"
             ? await reviewProposal(id, { rootDir })
@@ -1809,7 +1811,7 @@ async function evolveCommand(argv: string[]) {
                 ? await rejectProposal(id, {
                     rootDir,
                     reason:
-                      parseStringFlag(parsed.argv, "--reason") ??
+                      parseStringFlag(commandArgs, "--reason") ??
                       (() => {
                         throw new Error("evolve reject requires --reason");
                       })(),
@@ -1817,7 +1819,7 @@ async function evolveCommand(argv: string[]) {
                 : sub === "supersede"
                   ? await supersedeProposal(
                       id,
-                      parseStringFlag(parsed.argv, "--by") ??
+                      parseStringFlag(commandArgs, "--by") ??
                         (() => {
                           throw new Error("evolve supersede requires --by");
                         })(),
@@ -1827,7 +1829,7 @@ async function evolveCommand(argv: string[]) {
                     ? await promoteProposal(id, {
                         rootDir,
                         to:
-                          (parseStringFlag(parsed.argv, "--to") as
+                          (parseStringFlag(commandArgs, "--to") as
                             | "global"
                             | undefined) ??
                           (() => {

package/src/index-builder.ts

@@ -1,5 +1,5 @@
 import { mkdir, readdir } from "node:fs/promises";
-import { basename, dirname, join, relative } from "node:path";
+import { basename, dirname, isAbsolute, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
 import { getAdapter } from "./adapters";
 import { parseCliContextArgs, resolveCliContextRoot } from "./cli-context";
@@ -215,7 +215,8 @@ function extractIndexMeta(entry: unknown): {
 function findPreviousEntryByCanonicalRef(
   previous: Record<string, unknown> | undefined,
   canonicalRef: string | undefined,
-  fallbackName: string
+  fallbackName: string,
+  source: IndexedSource
 ): unknown {
   if (!previous) {
     return undefined;
@@ -233,7 +234,8 @@ function findPreviousEntryByCanonicalRef(
   const legacyFallback = previous[fallbackName];
   if (
     isPlainObject(legacyFallback) &&
-    typeof legacyFallback.canonicalRef !== "string"
+    typeof legacyFallback.canonicalRef !== "string" &&
+    legacyFallbackMatchesSource(legacyFallback, source)
   ) {
     return legacyFallback;
   }
@@ -243,7 +245,8 @@ function findPreviousEntryByCanonicalRef(
 function findPreviousMcpEntry(
   previous: Record<string, unknown> | undefined,
   canonicalRef: string | undefined,
-  name: string
+  name: string,
+  source: IndexedSource
 ): unknown {
   if (!previous) {
     return undefined;
@@ -252,11 +255,73 @@ function findPreviousMcpEntry(
   if (!isPlainObject(candidate)) {
     return undefined;
   }
-  return typeof candidate.canonicalRef !== "string" ||
-    (typeof canonicalRef === "string" &&
-      candidate.canonicalRef === canonicalRef)
-    ? candidate
-    : undefined;
+  if (typeof candidate.canonicalRef !== "string") {
+    return legacyFallbackMatchesSource(candidate, source)
+      ? candidate
+      : undefined;
+  }
+  if (
+    typeof canonicalRef === "string" &&
+    candidate.canonicalRef === canonicalRef
+  ) {
+    return candidate;
+  }
+  return undefined;
+}
+
+function pathIsWithinRoot(pathValue: string, rootDir: string): boolean {
+  if (!isAbsolute(pathValue)) {
+    return false;
+  }
+  const rel = relative(rootDir, pathValue);
+  return rel === "" || !(rel.startsWith("..") || isAbsolute(rel));
+}
+
+function legacyFallbackMatchesSource(
+  entry: Record<string, unknown>,
+  source: IndexedSource
+): boolean {
+  let hasSourceSignal = false;
+
+  const entrySourceKind = entry.sourceKind;
+  if (typeof entrySourceKind === "string") {
+    hasSourceSignal = true;
+    if (entrySourceKind !== source.sourceKind) {
+      return false;
+    }
+  }
+
+  const entryScope = entry.scope;
+  if (typeof entryScope === "string") {
+    hasSourceSignal = true;
+    if (entryScope !== source.scope) {
+      return false;
+    }
+  }
+
+  const entryProjectRoot = entry.projectRoot;
+  if (typeof entryProjectRoot === "string") {
+    hasSourceSignal = true;
+    if (entryProjectRoot !== source.projectRoot) {
+      return false;
+    }
+  }
+
+  const entrySourceRoot = entry.sourceRoot;
+  if (typeof entrySourceRoot === "string") {
+    hasSourceSignal = true;
+    if (entrySourceRoot !== source.rootDir) {
+      return false;
+    }
+  }
+
+  const entryPath = entry.path;
+  if (typeof entryPath === "string") {
+    hasSourceSignal = true;
+    return pathIsWithinRoot(entryPath, source.rootDir);
+  }
+
+  return hasSourceSignal;
 }
 
 function stripQuotes(s: string): string {
@@ -556,7 +621,8 @@ async function indexSkills(
       const prev = findPreviousEntryByCanonicalRef(
         previous,
         canonicalRef,
-        name
+        name,
+        source
       );
       const meta = extractIndexMeta(prev);
 
@@ -618,7 +684,7 @@ async function indexMcpServers(
     const lm = await statIsoTime(mcpConfigPath);
     for (const name of Object.keys(serversObj).sort()) {
       const canonicalRef = canonicalRefForPath(source, "mcp", mcpConfigPath);
-      const prev = findPreviousMcpEntry(previous, canonicalRef, name);
+      const prev = findPreviousMcpEntry(previous, canonicalRef, name, source);
       const meta = extractIndexMeta(prev);
       out[name] = {
         name,
@@ -666,7 +732,12 @@ async function indexAgents(
     const name =
       basename(p) === "agent.toml" ? basename(dirname(p)) : basename(p);
     const canonicalRef = canonicalRefForPath(source, "agents", p);
-    const prev = findPreviousEntryByCanonicalRef(previous, canonicalRef, name);
+    const prev = findPreviousEntryByCanonicalRef(
+      previous,
+      canonicalRef,
+      name,
+      source
+    );
     const meta = extractIndexMeta(prev);
     let description: string | undefined;
     try {

package/src/paths.ts

@@ -369,7 +369,8 @@ export function facultAiRuntimeScopeDir(
   rootDir?: string
 ): string {
   return join(
-    facultAiStateDir(home, rootDir),
+    facultMachineStateDir(home, rootDir),
+    "ai",
     projectRootFromAiRoot(rootDir ?? facultRootDir(home), home)
       ? "project"
       : "global"