facult 2.8.1 → 2.8.3

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.1",
+  "version": "2.8.3",
   "description": "Manage canonical AI capabilities, sync surfaces, and evolution state.",
   "type": "module",
   "license": "MIT",

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,35 @@ 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) {
+        if (
+          await canonicalAssetsNewerThanIndex({
+            homeDir: args.homeDir,
+            rootDir: args.rootDir,
+            indexPath: legacyPath,
+          })
+        ) {
+          const { outputPath } = await buildIndex({
+            rootDir: args.rootDir,
+            homeDir: args.homeDir,
+            force: false,
+          });
+          return { path: outputPath, repaired: true, source: "rebuilt" };
+        }
+        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 +265,31 @@ 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) {
+        if (
+          await canonicalAssetsNewerThanIndex({
+            homeDir: args.homeDir,
+            rootDir: args.rootDir,
+            indexPath: legacyGeneratedPath,
+          })
+        ) {
+          const { graphPath } = await buildIndex({
+            rootDir: args.rootDir,
+            homeDir: args.homeDir,
+            force: false,
+          });
+          return { path: graphPath, rebuilt: true };
+        }
+        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,61 @@ 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 aiProposalReadDirs(homeDir: string, rootDir: string): string[] {
+  return uniqueStrings([
+    facultAiProposalDir(homeDir, rootDir),
+    ...legacyAiRuntimeScopeDirs(homeDir, rootDir).map((dir) =>
+      join(dir, "evolution", "proposals")
+    ),
+  ]);
+}
+
+async function firstExistingFile(paths: string[]): Promise<string | null> {
+  for (const pathValue of paths) {
+    if (await fileExists(pathValue)) {
+      return pathValue;
+    }
+  }
+  return null;
+}
+
 function supportedDraftTarget(pathValue: string): boolean {
   return pathValue.toLowerCase().endsWith(".md");
 }
@@ -285,8 +341,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 +357,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(
@@ -605,11 +663,15 @@ async function nextProposalId(
   homeDir: string,
   rootDir: string
 ): Promise<string> {
-  const dir = facultAiProposalDir(homeDir, rootDir);
-  const entries = await readdir(dir).catch(() => [] as string[]);
-  const ids = entries
-    .filter((entry) => entry.endsWith(".json"))
-    .map((entry) => basename(entry, ".json"));
+  const ids: string[] = [];
+  for (const dir of aiProposalReadDirs(homeDir, rootDir)) {
+    const entries = await readdir(dir).catch(() => [] as string[]);
+    ids.push(
+      ...entries
+        .filter((entry) => entry.endsWith(".json"))
+        .map((entry) => basename(entry, ".json"))
+    );
+  }
   return nextId("EV", ids);
 }
 
@@ -802,18 +864,19 @@ export async function listProposals(args?: {
     throw new Error("listProposals requires a rootDir");
   }
   const homeDir = args?.homeDir ?? process.env.HOME ?? "";
-  const dir = facultAiProposalDir(homeDir, args?.rootDir);
-  const entries = await readdir(dir).catch(() => [] as string[]);
-  const out: AiProposalRecord[] = [];
-  for (const entry of entries.sort()) {
-    if (!entry.endsWith(".json")) {
-      continue;
+  const byId = new Map<string, AiProposalRecord>();
+  for (const dir of [...aiProposalReadDirs(homeDir, args.rootDir)].reverse()) {
+    const entries = await readdir(dir).catch(() => [] as string[]);
+    for (const entry of entries.sort()) {
+      if (!entry.endsWith(".json")) {
+        continue;
+      }
+      const raw = await readFile(join(dir, entry), "utf8");
+      const parsed = JSON.parse(raw) as AiProposalRecord;
+      byId.set(parsed.id, parsed);
     }
-    const raw = await readFile(join(dir, entry), "utf8");
-    const parsed = JSON.parse(raw) as AiProposalRecord;
-    out.push(parsed);
   }
-  return out;
+  return [...byId.values()].sort((a, b) => a.id.localeCompare(b.id));
 }
 
 export async function showProposal(
@@ -821,15 +884,15 @@ export async function showProposal(
   args: { homeDir?: string; rootDir: string }
 ): Promise<AiProposalRecord | null> {
   const homeDir = args.homeDir ?? process.env.HOME ?? "";
-  const pathValue = join(
-    facultAiProposalDir(homeDir, args.rootDir),
-    `${id}.json`
-  );
-  if (!(await fileExists(pathValue))) {
-    return null;
+  for (const dir of aiProposalReadDirs(homeDir, args.rootDir)) {
+    const pathValue = join(dir, `${id}.json`);
+    if (!(await fileExists(pathValue))) {
+      continue;
+    }
+    const raw = await readFile(pathValue, "utf8");
+    return JSON.parse(raw) as AiProposalRecord;
   }
-  const raw = await readFile(pathValue, "utf8");
-  return JSON.parse(raw) as AiProposalRecord;
+  return null;
 }
 
 function promoteTargetRef(target: string, to: "global"): string {
@@ -1082,9 +1145,13 @@ export async function draftProposal(
   const patchPath = patchRefForProposal(homeDir, args.rootDir, id);
   await mkdir(dirname(draftPath), { recursive: true });
   const generatedBody = renderDraftBody(current, writebacks);
+  const existingDraftPath = await firstExistingFile([
+    draftPath,
+    ...current.draftRefs.filter((pathValue) => pathValue.endsWith(".md")),
+  ]);
   const priorDraft =
-    args.append && (await fileExists(draftPath))
-      ? await readFile(draftPath, "utf8")
+    args.append && existingDraftPath
+      ? await readFile(existingDraftPath, "utf8")
       : null;
   const draftBody = args.append
     ? `${(priorDraft ?? generatedBody).trimEnd()}\n\n## Draft Revision\n${args.append.trim()}\n`

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