facult 2.8.5 → 2.8.7

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,10 +698,13 @@ 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)
-- `runtime/<version>/<platform-arch>/...` under the machine-local cache root (npm launcher binary cache)
+- `cache/runtime/<version>/<platform-arch>/...` under the macOS machine-local state root, or `runtime/<version>/<platform-arch>/...` under `FACULT_CACHE_DIR`/XDG cache roots on other platforms (npm launcher binary cache)
+  - if that cache root is unavailable, the npm launcher falls back to a temp-dir runtime cache before using the bundled source fallback
 
 ### Config reference
 

package/bin/fclt.cjs

@@ -45,7 +45,7 @@ function localCacheRoot(home) {
     return path.resolve(override);
   }
   if (process.platform === "darwin") {
-    return path.join(home, "Library", "Caches", "fclt");
+    return path.join(localStateRoot(home), "cache");
   }
   const xdg = String(process.env.XDG_CACHE_HOME || "").trim();
   return xdg
@@ -67,7 +67,7 @@ async function main() {
   }
 
   const home = os.homedir();
-  const cacheRoot = path.join(localCacheRoot(home), "runtime");
+  const cacheRoot = await runtimeCacheRoot(home);
   const installDir = path.join(
     cacheRoot,
     version,
@@ -174,6 +174,22 @@ async function main() {
   process.exit(1);
 }
 
+async function runtimeCacheRoot(home) {
+  const primary = path.join(localCacheRoot(home), "runtime");
+  try {
+    await fsp.mkdir(primary, { recursive: true });
+    return primary;
+  } catch {
+    const fallback = path.join(os.tmpdir(), "fclt", "runtime-cache");
+    try {
+      await fsp.mkdir(fallback, { recursive: true });
+      return fallback;
+    } catch {
+      return primary;
+    }
+  }
+}
+
 async function canUseSourceFallback(sourceEntry) {
   if (!(await fileExists(sourceEntry))) {
     return false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "facult",
-  "version": "2.8.5",
+  "version": "2.8.7",
   "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/paths.ts

@@ -114,7 +114,7 @@ export function facultLocalCacheRoot(home: string = defaultHomeDir()): string {
     return resolvePath(override, home);
   }
   if (process.platform === "darwin") {
-    return join(home, "Library", "Caches", "fclt");
+    return join(facultLocalStateRoot(home), "cache");
   }
   const xdg = process.env.XDG_CACHE_HOME?.trim();
   return xdg
@@ -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"