facult 2.17.3 → 2.17.6

package/package.json

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

package/src/ai.ts

@@ -491,6 +491,18 @@ async function writeProposalReviewArtifact(args: {
   await Bun.write(pathValue, `${body.trimEnd()}\n`);
 }
 
+async function currentDraftBodyForProposal(
+  proposal: AiProposalRecord
+): Promise<string | null> {
+  const draftPath = proposal.draftRefs.find((pathValue) =>
+    pathValue.endsWith(".md")
+  );
+  if (!(draftPath && (await fileExists(draftPath)))) {
+    return null;
+  }
+  return readFile(draftPath, "utf8");
+}
+
 function slugToTitle(value: string): string {
   return value
     .split(SLUG_SPLIT_RE)
@@ -988,7 +1000,11 @@ export async function proposeEvolution(args: {
     : null;
 
   const candidates = writebacks.filter((entry) => {
-    if (entry.status === "dismissed" || entry.status === "superseded") {
+    if (
+      entry.status === "dismissed" ||
+      entry.status === "resolved" ||
+      entry.status === "superseded"
+    ) {
       return false;
     }
     if (entry.evidence.length === 0) {
@@ -1371,6 +1387,7 @@ export async function refreshAiReviewArtifacts(args: {
       rootDir: args.rootDir,
       proposal,
       writebacks: sourceWritebacks,
+      draftBody: await currentDraftBodyForProposal(proposal),
     });
   }
 

package/src/doctor.ts

@@ -476,7 +476,12 @@ async function repairCanonicalGlobalDocs(args: {
   home: string;
   rootDir: string;
 }): Promise<{ changed: boolean; backupPath?: string }> {
-  const inspected = await inspectCanonicalGlobalDocs(args.rootDir);
+  if (projectRootFromAiRoot(args.rootDir, args.home)) {
+    return { changed: false };
+  }
+  const inspected = await inspectCanonicalGlobalDocs(args.rootDir, {
+    projectRoot: null,
+  });
   if (!(inspected.exists && !inspected.valid)) {
     return { changed: false };
   }
@@ -494,13 +499,13 @@ async function repairCanonicalGlobalDocs(args: {
   await copyFile(targetPath, backupPath);
   await mkdir(dirname(targetPath), { recursive: true });
   await writeFile(targetPath, await readFile(sourcePath, "utf8"), "utf8");
-  await copyMissingBuiltinOperatingModelSnippets(args.rootDir);
+  await repairBuiltinOperatingModelSnippets(args.rootDir);
   await ensureAiIndexPath({ homeDir: args.home, rootDir: args.rootDir });
   await ensureAiGraphPath({ homeDir: args.home, rootDir: args.rootDir });
   return { changed: true, backupPath };
 }
 
-async function copyMissingBuiltinOperatingModelSnippets(
+async function repairBuiltinOperatingModelSnippets(
   rootDir: string
 ): Promise<void> {
   const relPaths = [
@@ -515,7 +520,10 @@ async function copyMissingBuiltinOperatingModelSnippets(
   for (const relPath of relPaths) {
     const sourcePath = join(sourceRoot, relPath);
     const targetPath = join(rootDir, relPath);
-    if (await pathExists(targetPath)) {
+    const existing = (await pathExists(targetPath))
+      ? await readFile(targetPath, "utf8")
+      : null;
+    if (existing !== null && existing.trim().length > 0) {
       continue;
     }
     await mkdir(dirname(targetPath), { recursive: true });
@@ -601,7 +609,10 @@ const UNRESOLVED_REFS_TEMPLATE_RE = /\$\{refs\.([A-Za-z0-9_.-]+)\}/g;
 const FCLTY_BLOCK_RE =
   /<!--\s*fclty:([^>]+?)\s*-->([\s\S]*?)<!--\s*\/fclty:\1\s*-->/g;
 
-async function inspectCanonicalGlobalDocs(rootDir: string): Promise<{
+async function inspectCanonicalGlobalDocs(
+  rootDir: string,
+  opts: { projectRoot?: string | null } = {}
+): Promise<{
   exists: boolean;
   valid: boolean;
   issues: DoctorIssue[];
@@ -613,6 +624,12 @@ async function inspectCanonicalGlobalDocs(rootDir: string): Promise<{
 
   const text = await readFile(pathValue, "utf8");
   const issues: DoctorIssue[] = [];
+  const refreshCommand = opts.projectRoot
+    ? "fclt templates init project-ai --force"
+    : "fclt templates init operating-model --global --force";
+  const docLabel = opts.projectRoot
+    ? "project AGENTS.global.md"
+    : "AGENTS.global.md";
   const withSnippets = await renderSnippetText({
     text,
     filePath: pathValue,
@@ -623,7 +640,7 @@ async function inspectCanonicalGlobalDocs(rootDir: string): Promise<{
       severity: "warning",
       code: "canonical-global-docs-render-error",
       message: error,
-      fix: "Review AGENTS.global.md snippet markers or refresh the built-in operating model with `fclt templates init operating-model --global --force`.",
+      fix: `Review ${docLabel} snippet markers or refresh the selected capability root with \`${refreshCommand}\`.`,
     });
   }
   const rendered = await renderCanonicalText(withSnippets.text, {
@@ -636,9 +653,8 @@ async function inspectCanonicalGlobalDocs(rootDir: string): Promise<{
     issues.push({
       severity: "warning",
       code: "canonical-global-docs-unresolved-template",
-      message:
-        "Rendered AGENTS.global.md contains unresolved template references.",
-      fix: "Review AGENTS.global.md refs or refresh the built-in operating model with `fclt templates init operating-model --global --force`.",
+      message: `Rendered ${docLabel} contains unresolved template references.`,
+      fix: `Review ${docLabel} refs or refresh the selected capability root with \`${refreshCommand}\`.`,
     });
   }
 
@@ -654,8 +670,8 @@ async function inspectCanonicalGlobalDocs(rootDir: string): Promise<{
     issues.push({
       severity: "warning",
       code: "canonical-global-docs-empty-managed-sections",
-      message: `Rendered AGENTS.global.md has empty fclty managed sections: ${emptySections.join(", ")}.`,
-      fix: "Add the missing snippets or refresh the built-in operating model with `fclt templates init operating-model --global --force`.",
+      message: `Rendered ${docLabel} has empty fclty managed sections: ${emptySections.join(", ")}.`,
+      fix: `Add the missing snippets or refresh the selected capability root with \`${refreshCommand}\`.`,
     });
   }
 
@@ -976,7 +992,7 @@ export async function buildDoctorReport(opts?: {
     pathExists(generatedGraph),
     pathExists(writebackReviewDir),
     pathExists(evolutionReviewDir),
-    inspectCanonicalGlobalDocs(rootDir),
+    inspectCanonicalGlobalDocs(rootDir, { projectRoot }),
     inspectCanonicalTemplateRefs(rootDir),
     planProjectSyncPolicyRepair({ home, rootDir }),
   ]);
@@ -1019,9 +1035,15 @@ export async function buildDoctorReport(opts?: {
   }
   if (canonicalGlobalDocs.exists && !canonicalGlobalDocs.valid) {
     actions.push({
-      id: "refresh-global-operating-model",
-      label: "Refresh global operating model",
-      command: "fclt templates init operating-model --global --force",
+      id: projectRoot
+        ? "refresh-project-operating-model"
+        : "refresh-global-operating-model",
+      label: projectRoot
+        ? "Refresh project operating model"
+        : "Refresh global operating model",
+      command: projectRoot
+        ? "fclt templates init project-ai --force"
+        : "fclt templates init operating-model --global --force",
       risk: "canonical_write",
     });
   }
@@ -1369,7 +1391,9 @@ export async function doctorCommand(argv: string[]) {
         `Project sync is still implicit for managed tools (${projectSyncRepairTools.join(", ")}). Run \`fclt doctor --repair\` to write explicit [project_sync.<tool>] entries.`
       );
     }
-    const canonicalGlobalDocs = await inspectCanonicalGlobalDocs(rootDir);
+    const canonicalGlobalDocs = await inspectCanonicalGlobalDocs(rootDir, {
+      projectRoot: projectRootFromAiRoot(rootDir, home),
+    });
     if (canonicalGlobalDocs.exists && !canonicalGlobalDocs.valid) {
       for (const issue of canonicalGlobalDocs.issues) {
         console.log(`${issue.message} ${issue.fix ?? ""}`.trim());

package/src/global-docs.ts

@@ -6,7 +6,7 @@ import {
   facultBuiltinAgentsGlobalSourcePath,
   facultBuiltinPackRoot,
 } from "./builtin";
-import { projectRootFromAiRoot } from "./paths";
+import { pathIsInsideOrEqual, projectRootFromAiRoot } from "./paths";
 import { projectSyncAllowsToolSurface } from "./project-sync";
 import { renderSnippetText } from "./snippets";
 
@@ -233,7 +233,7 @@ async function renderSourceTarget(args: {
 }): Promise<string> {
   const raw = await Bun.file(args.sourcePath).text();
   const builtinRoot = facultBuiltinPackRoot();
-  const sourceRoot = args.sourcePath.startsWith(`${builtinRoot}/`)
+  const sourceRoot = pathIsInsideOrEqual(args.sourcePath, builtinRoot)
     ? builtinRoot
     : args.rootDir;
   const withSnippets = await renderSnippetText({

package/src/manage.ts

@@ -48,6 +48,7 @@ import {
   facultMachineStateDir,
   facultRootDir,
   legacyFacultStateDirForRoot,
+  pathIsInsideOrEqual,
   projectRootFromAiRoot,
 } from "./paths";
 import { loadProjectToolSyncPolicy } from "./project-sync";
@@ -289,8 +290,8 @@ async function isGeneratedOnlyProjectRoot(args: {
 function renderedSourceKindForPath(
   sourcePath: string
 ): ManagedRenderedTargetState["sourceKind"] {
-  return sourcePath.startsWith(facultBuiltinPackRoot()) ||
-    sourcePath.startsWith(facultBuiltinCodexPluginRoot())
+  return pathIsInsideOrEqual(sourcePath, facultBuiltinPackRoot()) ||
+    pathIsInsideOrEqual(sourcePath, facultBuiltinCodexPluginRoot())
     ? "builtin"
     : "canonical";
 }

package/src/paths.ts

@@ -1,9 +1,19 @@
 import { createHash } from "node:crypto";
 import { readdirSync, readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
-import { basename, dirname, join, resolve } from "node:path";
+import {
+  basename,
+  dirname,
+  isAbsolute,
+  join,
+  relative,
+  resolve,
+  win32,
+} from "node:path";
 import { parseJsonLenient } from "./util/json";
 
+const WINDOWS_ABSOLUTE_PATH_RE = /^[A-Za-z]:[\\/]/;
+
 export interface FacultConfig {
   /**
    * Override the canonical root directory.
@@ -88,6 +98,41 @@ export function preferredGlobalAiRoot(home: string = defaultHomeDir()): string {
   return join(home, ".ai");
 }
 
+function looksLikeWindowsAbsolutePath(pathValue: string): boolean {
+  return (
+    WINDOWS_ABSOLUTE_PATH_RE.test(pathValue) || pathValue.startsWith("\\\\")
+  );
+}
+
+function relativePathIsInsideOrEqual(args: {
+  rel: string;
+  isAbsolutePath: (pathValue: string) => boolean;
+}): boolean {
+  const { isAbsolutePath, rel } = args;
+  return rel === "" || (!!rel && !rel.startsWith("..") && !isAbsolutePath(rel));
+}
+
+export function pathIsInsideOrEqual(
+  pathValue: string,
+  rootDir: string
+): boolean {
+  if (
+    looksLikeWindowsAbsolutePath(pathValue) &&
+    looksLikeWindowsAbsolutePath(rootDir)
+  ) {
+    return relativePathIsInsideOrEqual({
+      isAbsolutePath: win32.isAbsolute,
+      rel: win32.relative(rootDir, pathValue),
+    });
+  }
+
+  const rel = relative(rootDir, pathValue);
+  return relativePathIsInsideOrEqual({
+    isAbsolutePath: isAbsolute,
+    rel,
+  });
+}
+
 export function preferredGlobalFacultStateDir(
   home: string = defaultHomeDir()
 ): string {

package/src/self-update.ts

@@ -195,9 +195,6 @@ async function activeFcltUsesMiseNpmFacult(): Promise<boolean> {
   if (looksLikeMiseNpmFacultExecutable(fcltPath ?? "")) {
     return true;
   }
-  if (await miseHasCurrentFacultTool()) {
-    return true;
-  }
   if (!looksLikeMiseShim(fcltPath)) {
     return false;
   }
@@ -218,20 +215,21 @@ async function activeFcltUsesMiseNpmFacult(): Promise<boolean> {
   return looksLikeMiseNpmFacultExecutable(stdout.trim());
 }
 
-async function miseHasCurrentFacultTool(): Promise<boolean> {
-  const proc = Bun.spawn({
-    cmd: ["mise", "current", `npm:${PACKAGE_NAME}`],
-    stdin: "ignore",
-    stdout: "ignore",
-    stderr: "ignore",
-    env: process.env,
-  });
-  return (await proc.exited) === 0;
+export function buildCommandLookupFallback(
+  command: string,
+  platform: NodeJS.Platform = process.platform
+): string[] {
+  if (platform === "win32") {
+    return ["where.exe", command];
+  }
+  const quoted = `'${command.replaceAll("'", "'\\''")}'`;
+  return ["sh", "-lc", `command -v ${quoted}`];
 }
 
 async function resolveCommandPath(command: string): Promise<string | null> {
+  const cmd = buildCommandLookupFallback(command);
   const proc = Bun.spawn({
-    cmd: ["sh", "-lc", `command -v ${command}`],
+    cmd,
     stdin: "ignore",
     stdout: "pipe",
     stderr: "ignore",
@@ -247,6 +245,17 @@ async function resolveCommandPath(command: string): Promise<string | null> {
   return stdout.trim() || null;
 }
 
+export function looksLikeMiseNpmFacultExecutableForVersion(
+  executablePath: string,
+  version: string
+): boolean {
+  const normalized = executablePath.split("\\").join(sep);
+  return (
+    looksLikeMiseNpmFacultExecutable(normalized) &&
+    normalized.includes(`${sep}npm-facult${sep}${version}${sep}`)
+  );
+}
+
 function resolvePlatformTarget(): {
   platform: string;
   arch: string;
@@ -516,17 +525,38 @@ async function assertActiveFcltVersion(
   expectedVersion: string,
   packageManager: PackageManager
 ): Promise<void> {
-  const cmd =
-    packageManager === "mise"
-      ? [
-          "mise",
-          "exec",
-          `npm:${PACKAGE_NAME}@${expectedVersion}`,
-          "--",
-          "fclt",
-          "--version",
-        ]
-      : ["fclt", "--version"];
+  let cmd = ["fclt", "--version"];
+  if (packageManager === "mise") {
+    const which = Bun.spawn({
+      cmd: ["mise", "which", "fclt"],
+      stdin: "ignore",
+      stdout: "pipe",
+      stderr: "pipe",
+      env: process.env,
+    });
+    const [whichStdout, whichStderr, whichCode] = await Promise.all([
+      new Response(which.stdout).text(),
+      new Response(which.stderr).text(),
+      which.exited,
+    ]);
+    const resolvedPath = whichStdout.trim();
+    if (whichCode !== 0) {
+      throw new Error(
+        `Updated package, but could not verify active mise fclt path: ${whichStderr.trim()}`
+      );
+    }
+    if (
+      !looksLikeMiseNpmFacultExecutableForVersion(resolvedPath, expectedVersion)
+    ) {
+      throw new Error(
+        [
+          `Updated package to ${expectedVersion}, but mise resolves fclt to ${resolvedPath || "nothing"}.`,
+          "Run `mise which fclt` and `mise current npm:facult` to inspect the active tool selection.",
+        ].join("\n")
+      );
+    }
+    cmd = [resolvedPath, "--version"];
+  }
   const proc = Bun.spawn({
     cmd,
     stdin: "ignore",