facult 2.8.0 → 2.8.2

package/README.md

@@ -295,10 +295,11 @@ Typical layout:
 
 Important split:
 - `.ai/` is canonical source
-- `.ai/.facult/ai/` is generated AI state that belongs with the canonical root
-- machine-local Facult state such as managed-tool state, autosync runtime/config, install metadata, and launcher caches lives outside `.ai/`
+- global `.ai/.facult/ai/` is generated AI state for the global canonical root
+- project generated AI state lives in machine-local per-project Facult state, outside the repo
+- machine-local Facult state such as project indexes, project graphs, managed-tool state, autosync runtime/config, install metadata, and launcher caches lives outside project `.ai/`
 - tool homes such as `.codex/` and `.claude/` are rendered outputs
-- the generated capability graph lives at `.ai/.facult/ai/graph.json`
+- the generated capability graph lives under the active generated AI state directory
 
 ### Asset types
 
@@ -442,11 +443,11 @@ 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/...`
-- project writeback state: `<repo>/.ai/.facult/ai/project/...`
+- 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`
-- writeback queues, journals, proposal records, trust state, autosync state, and other generated runtime/config state stay inside `.ai/.facult/`
+- global generated state stays inside `~/.ai/.facult/`; project generated state stays outside the repo in machine-local state
 - those records let agents inspect what changed, why it changed, and how it was reviewed
 
 Use writeback when:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "facult",
-  "version": "2.8.0",
+  "version": "2.8.2",
   "description": "Manage canonical AI capabilities, sync surfaces, and evolution state.",
   "type": "module",
   "license": "MIT",
@@ -43,7 +43,7 @@
     "facult": "bun run ./src/index.ts",
     "scan": "bun run ./src/index.ts scan",
     "build": "bun run scripts/build-binary.ts",
-    "build:verify": "./dist/fclt --help",
+    "build:verify": "bun run scripts/verify-binary.ts",
     "install:dev": "bun run scripts/install-cli.ts --mode=dev --force",
     "install:bin": "bun run build && bun run scripts/install-cli.ts --mode=bin --force",
     "install:status": "bun run scripts/install-status.ts",

package/src/ai-state.ts

@@ -5,6 +5,7 @@ import { buildIndex } from "./index-builder";
 import {
   facultAiGraphPath,
   facultAiIndexPath,
+  legacyFacultAiStateDirs,
   legacyFacultStateDirForRoot,
   preferredGlobalAiRoot,
   projectRootFromAiRoot,
@@ -123,6 +124,21 @@ function legacyGeneratedAiIndexPath(homeDir: string, rootDir: string): string {
   );
 }
 
+function legacyGeneratedAiIndexPaths(
+  homeDir: string,
+  rootDir: string
+): string[] {
+  return [
+    ...new Set([
+      ...legacyFacultAiStateDirs(homeDir, rootDir).map((dir) =>
+        join(dir, "index.json")
+      ),
+      legacyGeneratedAiIndexPath(homeDir, rootDir),
+      legacyAiIndexPath(rootDir),
+    ]),
+  ];
+}
+
 function legacyGeneratedAiGraphPath(homeDir: string, rootDir: string): string {
   return join(
     legacyFacultStateDirForRoot(rootDir, homeDir),
@@ -131,6 +147,20 @@ function legacyGeneratedAiGraphPath(homeDir: string, rootDir: string): string {
   );
 }
 
+function legacyGeneratedAiGraphPaths(
+  homeDir: string,
+  rootDir: string
+): string[] {
+  return [
+    ...new Set([
+      ...legacyFacultAiStateDirs(homeDir, rootDir).map((dir) =>
+        join(dir, "graph.json")
+      ),
+      legacyGeneratedAiGraphPath(homeDir, rootDir),
+    ]),
+  ];
+}
+
 export async function ensureAiIndexPath(args: {
   homeDir: string;
   rootDir: string;
@@ -160,33 +190,21 @@ export async function ensureAiIndexPath(args: {
     return { path: generatedPath, repaired: false, source: "generated" };
   }
 
-  const legacyGeneratedPath = legacyGeneratedAiIndexPath(
+  for (const legacyPath of legacyGeneratedAiIndexPaths(
     args.homeDir,
     args.rootDir
-  );
-  if (await fileExists(legacyGeneratedPath)) {
-    if (args.repair !== false) {
-      await mkdir(dirname(generatedPath), { recursive: true });
-      await copyFile(legacyGeneratedPath, generatedPath);
-    }
-    return {
-      path: generatedPath,
-      repaired: args.repair !== false,
-      source: "legacy",
-    };
-  }
-
-  const legacyPath = legacyAiIndexPath(args.rootDir);
-  if (await fileExists(legacyPath)) {
-    if (args.repair !== false) {
-      await mkdir(dirname(generatedPath), { recursive: true });
-      await copyFile(legacyPath, generatedPath);
+  )) {
+    if (await fileExists(legacyPath)) {
+      if (args.repair !== false) {
+        await mkdir(dirname(generatedPath), { recursive: true });
+        await copyFile(legacyPath, generatedPath);
+      }
+      return {
+        path: generatedPath,
+        repaired: args.repair !== false,
+        source: "legacy",
+      };
     }
-    return {
-      path: generatedPath,
-      repaired: args.repair !== false,
-      source: "legacy",
-    };
   }
 
   if (args.repair !== false) {
@@ -233,16 +251,17 @@ export async function ensureAiGraphPath(args: {
     return { path: generatedPath, rebuilt: false };
   }
 
-  const legacyGeneratedPath = legacyGeneratedAiGraphPath(
+  for (const legacyGeneratedPath of legacyGeneratedAiGraphPaths(
     args.homeDir,
     args.rootDir
-  );
-  if (await fileExists(legacyGeneratedPath)) {
-    if (args.repair !== false) {
-      await mkdir(dirname(generatedPath), { recursive: true });
-      await copyFile(legacyGeneratedPath, generatedPath);
+  )) {
+    if (await fileExists(legacyGeneratedPath)) {
+      if (args.repair !== false) {
+        await mkdir(dirname(generatedPath), { recursive: true });
+        await copyFile(legacyGeneratedPath, generatedPath);
+      }
+      return { path: generatedPath, rebuilt: args.repair !== false };
     }
-    return { path: generatedPath, rebuilt: args.repair !== false };
   }
 
   if (args.repair !== false) {

package/src/ai.ts

@@ -11,6 +11,7 @@ import {
   facultAiProposalDir,
   facultAiWritebackQueuePath,
   facultRootDir,
+  legacyFacultAiStateDirs,
   projectRootFromAiRoot,
   projectSlugFromAiRoot,
 } from "./paths";
@@ -218,6 +219,43 @@ async function readJsonLines<T>(pathValue: string): Promise<T[]> {
     .map((line) => JSON.parse(line) as T);
 }
 
+async function readJsonLinesFromPaths<T>(pathValues: string[]): Promise<T[]> {
+  const entries: T[] = [];
+  for (const pathValue of pathValues) {
+    entries.push(...(await readJsonLines<T>(pathValue)));
+  }
+  return entries;
+}
+
+function aiRuntimeScopeName(rootDir: string, homeDir: string): AssetScope {
+  return projectRootFromAiRoot(rootDir, homeDir) ? "project" : "global";
+}
+
+function legacyAiRuntimeScopeDirs(homeDir: string, rootDir: string): string[] {
+  const scope = aiRuntimeScopeName(rootDir, homeDir);
+  return legacyFacultAiStateDirs(homeDir, rootDir).map((dir) =>
+    join(dir, scope)
+  );
+}
+
+function aiWritebackQueueReadPaths(homeDir: string, rootDir: string): string[] {
+  return [
+    ...legacyAiRuntimeScopeDirs(homeDir, rootDir).map((dir) =>
+      join(dir, "writeback", "queue.jsonl")
+    ),
+    facultAiWritebackQueuePath(homeDir, rootDir),
+  ];
+}
+
+function aiJournalReadPaths(homeDir: string, rootDir: string): string[] {
+  return [
+    ...legacyAiRuntimeScopeDirs(homeDir, rootDir).map((dir) =>
+      join(dir, "journal", "events.jsonl")
+    ),
+    facultAiJournalPath(homeDir, rootDir),
+  ];
+}
+
 function supportedDraftTarget(pathValue: string): boolean {
   return pathValue.toLowerCase().endsWith(".md");
 }
@@ -285,8 +323,8 @@ async function latestWritebackMap(args: {
   homeDir: string;
   rootDir: string;
 }): Promise<Map<string, AiWritebackRecord>> {
-  const entries = await readJsonLines<AiWritebackRecord>(
-    facultAiWritebackQueuePath(args.homeDir, args.rootDir)
+  const entries = await readJsonLinesFromPaths<AiWritebackRecord>(
+    aiWritebackQueueReadPaths(args.homeDir, args.rootDir)
   );
   const latest = new Map<string, AiWritebackRecord>();
   for (const entry of entries) {
@@ -301,7 +339,9 @@ async function appendEvent(
   event: AiJournalEvent
 ): Promise<void> {
   const pathValue = facultAiJournalPath(homeDir, rootDir);
-  const existing = await readJsonLines<AiJournalEvent>(pathValue);
+  const existing = await readJsonLinesFromPaths<AiJournalEvent>(
+    aiJournalReadPaths(homeDir, rootDir)
+  );
   const next = {
     ...event,
     id: nextId(

package/src/doctor.ts

@@ -727,6 +727,17 @@ export async function doctorCommand(argv: string[]) {
       return;
     }
 
+    if (
+      result.source === "legacy" &&
+      projectRootFromAiRoot(rootDir, home) &&
+      (await hasCanonicalSource(rootDir))
+    ) {
+      console.log(
+        "Legacy repo-local generated AI state detected. Run `fclt doctor --repair` or `fclt index` to migrate it into machine-local project state."
+      );
+      return;
+    }
+
     if (result.source === "legacy") {
       console.log(
         "Legacy root index detected. Run `fclt doctor --repair` to reconcile it."

package/src/paths.ts

@@ -229,6 +229,9 @@ export function facultStateDir(
   rootDir?: string
 ): string {
   const resolvedRoot = rootDir ?? facultRootDir(home);
+  if (projectRootFromAiRoot(resolvedRoot, home)) {
+    return facultMachineStateDir(home, resolvedRoot);
+  }
   if (shouldUsePreferredGlobalStateDir(resolvedRoot, home)) {
     return preferredGlobalFacultStateDir(home);
   }
@@ -317,6 +320,36 @@ export function facultAiStateDir(
   return join(facultGeneratedStateDir({ home, rootDir }), "ai");
 }
 
+export function legacyRepoLocalFacultAiStateDir(
+  home: string = defaultHomeDir(),
+  rootDir?: string
+): string | null {
+  const resolvedRoot = rootDir ?? facultRootDir(home);
+  return projectRootFromAiRoot(resolvedRoot, home)
+    ? join(resolvedRoot, ".facult", "ai")
+    : null;
+}
+
+export function legacyFacultAiStateDirs(
+  home: string = defaultHomeDir(),
+  rootDir?: string
+): string[] {
+  const resolvedRoot = rootDir ?? facultRootDir(home);
+  const current = resolve(facultAiStateDir(home, resolvedRoot));
+  const legacyDirs = [
+    legacyRepoLocalFacultAiStateDir(home, resolvedRoot),
+    join(legacyFacultStateDirForRoot(resolvedRoot, home), "ai"),
+  ];
+
+  return [
+    ...new Set(
+      legacyDirs
+        .filter((pathValue): pathValue is string => Boolean(pathValue))
+        .filter((pathValue) => resolve(pathValue) !== current)
+    ),
+  ];
+}
+
 export function facultAiIndexPath(
   home: string = defaultHomeDir(),
   rootDir?: string

package/src/status.ts

@@ -13,6 +13,8 @@ import {
 } from "./paths";
 import { parseJsonLenient } from "./util/json";
 
+declare const FCLT_COMPILED_VERSION: string | undefined;
+
 export interface StatusIssue {
   severity: "info" | "warning" | "error";
   code: string;
@@ -120,8 +122,25 @@ async function countActiveProposals(
 }
 
 export async function packageVersion(): Promise<string> {
+  const envVersion =
+    process.env.FACULT_NPM_PACKAGE_VERSION ?? process.env.npm_package_version;
+  if (envVersion?.trim()) {
+    return envVersion.trim();
+  }
+
+  if (
+    typeof FCLT_COMPILED_VERSION === "string" &&
+    FCLT_COMPILED_VERSION.trim()
+  ) {
+    return FCLT_COMPILED_VERSION.trim();
+  }
+
   const packagePath = join(dirname(import.meta.dir), "package.json");
-  const parsed = parseJsonLenient(await Bun.file(packagePath).text());
+  const parsed = parseJsonLenient(
+    await Bun.file(packagePath)
+      .text()
+      .catch(() => "{}")
+  );
   if (
     parsed &&
     typeof parsed === "object" &&