facult 2.5.0 → 2.5.2

package/README.md

@@ -282,6 +282,8 @@ bunx fclt index
 
 This seeds `<repo>/.ai` from the built-in Facult operating-model pack and writes a merged project index/graph under `<repo>/.ai/.facult/ai/`.
 
+Wide learning-review automations should use this same bootstrap when they hit a local writable repo with durable project-local signal but no repo-local `.ai` yet.
+
 ### 4. Inspect what you have
 
 ```bash

package/package.json

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

package/src/cli-context.ts

@@ -16,6 +16,11 @@ export interface ParsedCliContext {
   sourceKind?: AssetSourceKind;
 }
 
+function missingProjectAiRootMessage(pathValue?: string): string {
+  const suffix = pathValue ? `: ${pathValue}` : "";
+  return `No project-local .ai root found${suffix}. Run "fclt templates init project-ai" in the repo first, or pass --root <repo>/.ai.`;
+}
+
 function expandHomePath(pathValue: string, home: string): string {
   if (pathValue === "~") {
     return home;
@@ -173,9 +178,7 @@ export function resolveCliContextRoot(args?: {
   if (args?.rootArg) {
     const rootDir = coerceCanonicalRoot(args.rootArg, homeDir);
     if (scope === "project" && !projectRootFromAiRoot(rootDir, homeDir)) {
-      throw new Error(
-        `Project scope requires a repo-local .ai root: ${rootDir}`
-      );
+      throw new Error(missingProjectAiRootMessage(rootDir));
     }
     return rootDir;
   }
@@ -187,9 +190,7 @@ export function resolveCliContextRoot(args?: {
   if (scope === "project") {
     const projectRoot = findNearestProjectAiRoot(cwd);
     if (!projectRoot) {
-      throw new Error(
-        "No project-local .ai root found from the current directory"
-      );
+      throw new Error(missingProjectAiRootMessage(cwd));
     }
     return projectRoot;
   }

package/src/manage.ts

@@ -586,15 +586,34 @@ async function loadCanonicalAutomations(
   return await loadAutomationEntries(join(rootDir, "automations"));
 }
 
+function isAutomationRuntimeRelativePath(relPath: string): boolean {
+  return relPath === "memory.md";
+}
+
+function isAutomationRuntimeTargetPath(targetPath: string): boolean {
+  return basename(targetPath) === "memory.md";
+}
+
 function automationEntriesEqual(
   left: AutomationEntry,
   right: AutomationEntry
 ): boolean {
-  if (left.files.size !== right.files.size) {
+  const leftFiles = new Map(
+    [...left.files.entries()].filter(
+      ([relPath]) => !isAutomationRuntimeRelativePath(relPath)
+    )
+  );
+  const rightFiles = new Map(
+    [...right.files.entries()].filter(
+      ([relPath]) => !isAutomationRuntimeRelativePath(relPath)
+    )
+  );
+
+  if (leftFiles.size !== rightFiles.size) {
     return false;
   }
-  for (const [relPath, leftRaw] of left.files.entries()) {
-    if (right.files.get(relPath) !== leftRaw) {
+  for (const [relPath, leftRaw] of leftFiles.entries()) {
+    if (rightFiles.get(relPath) !== leftRaw) {
       return false;
     }
   }
@@ -816,23 +835,27 @@ async function planAutomationFileChanges(args: {
   const contents = new Map<string, string>();
   const sources = new Map<string, string>();
   const desiredPaths = new Set<string>();
+  const add = new Set<string>();
 
   for (const automation of automations) {
     for (const [relPath, raw] of automation.files.entries()) {
       const targetPath = join(args.automationDir, automation.name, relPath);
       const sourcePath = join(automation.sourceDir, relPath);
-      desiredPaths.add(targetPath);
       contents.set(targetPath, raw);
-      sources.set(targetPath, sourcePath);
-    }
-  }
 
-  const add = new Set<string>();
-  for (const targetPath of desiredPaths) {
-    const current = await readTextIfExists(targetPath);
-    const desired = contents.get(targetPath);
-    if (desired != null && current !== desired) {
-      add.add(targetPath);
+      if (isAutomationRuntimeRelativePath(relPath)) {
+        if ((await readTextIfExists(targetPath)) == null) {
+          add.add(targetPath);
+        }
+        continue;
+      }
+
+      desiredPaths.add(targetPath);
+      sources.set(targetPath, sourcePath);
+      const current = await readTextIfExists(targetPath);
+      if (current !== raw) {
+        add.add(targetPath);
+      }
     }
   }
 
@@ -841,6 +864,7 @@ async function planAutomationFileChanges(args: {
       (args.previouslyManagedTargets ?? []).filter(
         (targetPath) =>
           targetPath.startsWith(join(args.automationDir, "")) &&
+          !isAutomationRuntimeTargetPath(targetPath) &&
           !desiredPaths.has(targetPath)
       )
     )
@@ -2973,6 +2997,30 @@ function updateRenderedTargetState(args: {
   args.entry.renderedTargets = next;
 }
 
+function pruneAutomationRuntimeRenderedTargets(args: {
+  entry: ManagedToolState;
+  automationDir?: string;
+}) {
+  if (!(args.automationDir && args.entry.renderedTargets)) {
+    return;
+  }
+  const prefix = join(args.automationDir, "");
+  const next = { ...args.entry.renderedTargets };
+  let changed = false;
+  for (const targetPath of Object.keys(next)) {
+    if (
+      targetPath.startsWith(prefix) &&
+      isAutomationRuntimeTargetPath(targetPath)
+    ) {
+      delete next[targetPath];
+      changed = true;
+    }
+  }
+  if (changed) {
+    args.entry.renderedTargets = next;
+  }
+}
+
 function logSyncDryRun({
   tool,
   entry,
@@ -3177,6 +3225,11 @@ async function syncManagedToolEntry({
   dryRun?: boolean;
   builtinConflictMode?: "warn" | "overwrite";
 }) {
+  pruneAutomationRuntimeRenderedTargets({
+    entry,
+    automationDir: entry.automationDir,
+  });
+
   const adoptedSkills = dryRun
     ? []
     : await repairManagedCanonicalContent({

package/src/remote.ts

@@ -341,7 +341,7 @@ Use this memory for pattern continuity:
 - For wide reviews, partition evidence by cwd first; do not let one repo's evidence stand in for another.
 - Grounding: prefer evidence from session messages, tool calls, shell commands, diffs, tests, commits, and touched files.
 - Threshold: only encode signal when you can name what was learned, why it matters, and the most plausible destination.
-- Scope: default to project writeback unless the signal clearly belongs in global doctrine or a shared capability.
+- Scope: default to project writeback only when the repo has a project-local \`.ai\` root. If a local writable repo is missing one, bootstrap baseline project AI state with \`fclt templates init project-ai\` before retrying project-scoped writeback. If bootstrap fails or the repo is not writable, treat that as the blocker instead of silently falling back to global runtime state.
 - Promote to global only when the same signal appears across multiple repos or clearly targets shared doctrine, shared agents, or shared skills.
 - Verification: distinguish one-off friction from a repeated pattern before escalating it.
 - If available, use [$feedback-loop-setup]({{feedbackLoopSkill}}) when the review needs stronger feedback loops or verification framing.
@@ -367,6 +367,8 @@ Grounding rules:
 
 Decision rules:
 - Use \`fclt ai writeback add\` when the signal, target asset, and scope are clear.
+- Before attempting project-scoped writeback, verify the cwd has a repo-local \`.ai\` root. If it does not and the cwd is a local writable repo, run \`fclt templates init project-ai\` from that repo root, then continue. If bootstrap fails or the repo is not writable, report the writeback as blocked by missing project AI state rather than falling back to merged/global runtime state.
+- Before passing \`--asset\`, verify the target resolves in the Facult graph. If the destination is a raw file path or otherwise not graph-backed, report that as a missing-asset blocker instead of retrying blind.
 - Use \`fclt ai evolve\` only when repeated signal is strong enough to justify a reviewable capability change.
 - Prefer project scope unless the learning clearly belongs in shared global doctrine, shared agents, shared skills, or other cross-project capability.
 - For wide automations, require repeated evidence across more than one cwd before recommending a global/shared capability change unless the target is obviously global.