facult 2.2.0 → 2.3.1

package/README.md

@@ -694,13 +694,21 @@ fclt snippets sync [--dry-run] [file...]
 
 ### Codex automations
 
-`templates init automation` can scaffold two Codex automation forms:
+`templates init automation` can scaffold three Codex automation forms:
 
 - `--scope project` (single repo): set `--project-root` (or infer from current working directory)
 - `--scope wide|global` (multiple repos): set `--cwds` explicitly; if omitted, created automation has no `cwds` by default.
 - If you run it interactively without `--scope`, `fclt` prompts for scope and, where possible, known workspaces (git worktrees, configured scan roots, and existing Codex automation paths).
 - Built-in automation templates are opinionated: they reference the global Codex operating model, point at relevant Codex skills, and tell Codex when to use focused subagents for bounded review work.
 
+Recommended topology:
+
+- Use `learning-review --scope project` for repo-local writeback and evolution. This keeps review state, verification, and follow-up scoped to the repo that actually produced the evidence.
+- Use `evolution-review` on a slower cadence, usually weekly, to triage open proposals and proposal-worthy clusters and suggest the next operator action (`draft`, `review`, `accept`, `reject`, `promote`, or `apply`).
+- Use a separate wide/global automation only for cross-repo or shared-surface review, such as global doctrine, shared skills, or repeated tool/agent patterns across repos.
+- If you do use a wide learning review, keep the `cwds` list intentionally small and related. The prompt is designed to partition by cwd first, not to blur unrelated repos together.
+- A practical default is daily `learning-review` plus weekly `evolution-review`. The first finds and records durable signal; the second keeps proposal review from stalling.
+
 Files are written to:
 
 - `~/.codex/automations/<name>/automation.toml`
@@ -725,6 +733,16 @@ fclt templates init automation learning-review \
   --status PAUSED
 ```
 
+Example weekly evolution automation:
+
+```bash
+fclt templates init automation evolution-review \
+  --scope wide \
+  --cwds /path/to/repo-a,/path/to/repo-b \
+  --name weekly-evolution-review \
+  --status PAUSED
+```
+
 Interactive prompt example:
 
 ```bash

package/bin/fclt.cjs

@@ -38,15 +38,17 @@ async function main() {
   );
   const binaryName = resolved.platform === "windows" ? "fclt.exe" : "fclt";
   const binaryPath = path.join(installDir, binaryName);
+  const sourceEntry = path.join(__dirname, "..", "src", "index.ts");
+  let installedBinaryThisRun = false;
 
   if (!(await fileExists(binaryPath))) {
     const tag = `v${version}`;
     const assetName = `${PACKAGE_NAME}-${version}-${resolved.platform}-${resolved.arch}${resolved.ext}`;
     const url = `https://github.com/${REPO_OWNER}/${REPO_NAME}/releases/download/${tag}/${assetName}`;
-
-    await fsp.mkdir(installDir, { recursive: true });
     const tmpPath = `${binaryPath}.tmp-${Date.now()}`;
+
     try {
+      await fsp.mkdir(installDir, { recursive: true });
       await downloadWithRetry(url, tmpPath, {
         attempts: DOWNLOAD_RETRIES,
         delayMs: DOWNLOAD_RETRY_DELAY_MS,
@@ -55,8 +57,17 @@ async function main() {
         await fsp.chmod(tmpPath, 0o755);
       }
       await fsp.rename(tmpPath, binaryPath);
+      installedBinaryThisRun = true;
     } catch (error) {
       await safeUnlink(tmpPath);
+      if (await canUseSourceFallback(sourceEntry)) {
+        return runSourceFallback({
+          sourceEntry,
+          version,
+          packageManager: detectPackageManager(),
+          reason: error,
+        });
+      }
       const message =
         error instanceof Error ? error.message : String(error ?? "");
       console.error(
@@ -75,12 +86,14 @@ async function main() {
   }
 
   const packageManager = detectPackageManager();
-  await writeInstallState({
-    method: "npm-binary-cache",
-    version,
-    binaryPath,
-    packageManager,
-  });
+  if (installedBinaryThisRun) {
+    await bestEffortWriteInstallState({
+      method: "npm-binary-cache",
+      version,
+      binaryPath,
+      packageManager,
+    });
+  }
 
   const args = process.argv.slice(2);
   const result = spawnSync(binaryPath, args, {
@@ -100,6 +113,41 @@ async function main() {
   process.exit(1);
 }
 
+async function canUseSourceFallback(sourceEntry) {
+  if (!(await fileExists(sourceEntry))) {
+    return false;
+  }
+  const result = spawnSync("bun", ["--version"], {
+    stdio: "ignore",
+    env: process.env,
+  });
+  return result.status === 0;
+}
+
+function runSourceFallback({ sourceEntry, version, packageManager, reason }) {
+  const message =
+    reason instanceof Error ? reason.message : String(reason ?? "");
+  console.error(
+    `fclt: cached runtime unavailable, falling back to Bun source entry (${message})`
+  );
+  const args = process.argv.slice(2);
+  const result = spawnSync("bun", [sourceEntry, ...args], {
+    stdio: "inherit",
+    env: {
+      ...process.env,
+      FACULT_INSTALL_METHOD: "npm-source-fallback",
+      FACULT_NPM_PACKAGE_VERSION: version,
+      FACULT_SOURCE_ENTRY: sourceEntry,
+      FACULT_INSTALL_PM: packageManager,
+    },
+  });
+
+  if (typeof result.status === "number") {
+    process.exit(result.status);
+  }
+  process.exit(1);
+}
+
 function resolveTarget() {
   const platform = process.platform;
   const arch = process.arch;
@@ -257,6 +305,14 @@ async function writeInstallState(state) {
   await fsp.rename(`${installStatePath}.tmp`, installStatePath);
 }
 
+async function bestEffortWriteInstallState(state) {
+  try {
+    await writeInstallState(state);
+  } catch {
+    // Install state is useful metadata, but it should not block normal CLI usage.
+  }
+}
+
 main().catch((error) => {
   const message = error instanceof Error ? error.message : String(error ?? "");
   console.error(message);

package/package.json

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

package/src/ai.ts

@@ -171,6 +171,7 @@ interface AddWritebackArgs {
   summary: string;
   asset?: string;
   evidence?: WritebackEvidence[];
+  allowEmptyEvidence?: boolean;
   confidence?: ConfidenceLevel;
   source?: string;
   suggestedDestination?: string;
@@ -348,6 +349,12 @@ export async function addWriteback(
   args: AddWritebackArgs
 ): Promise<AiWritebackRecord> {
   const homeDir = args.homeDir ?? process.env.HOME ?? "";
+  const evidence = args.evidence ?? [];
+  if (evidence.length === 0 && !args.allowEmptyEvidence) {
+    throw new Error(
+      "writeback add requires at least one evidence item; pass --evidence <type:ref> or use --allow-empty-evidence for scratch/demo notes"
+    );
+  }
   const scopeContext = resolveScopeContext(args.rootDir, homeDir);
   const latest = await latestWritebackMap({
     homeDir,
@@ -368,7 +375,7 @@ export async function addWriteback(
     projectRoot: scopeContext.projectRoot,
     kind: args.kind.trim(),
     summary: args.summary.trim(),
-    evidence: args.evidence ?? [],
+    evidence,
     confidence: args.confidence ?? "medium",
     source: args.source ?? "facult:manual",
     assetRef: asset.assetRef,
@@ -669,6 +676,9 @@ export async function proposeEvolution(args: {
     if (entry.status === "dismissed" || entry.status === "superseded") {
       return false;
     }
+    if (entry.evidence.length === 0) {
+      return false;
+    }
     if (filterAsset) {
       return (
         entry.assetId === filterAsset.assetId ||
@@ -1405,7 +1415,7 @@ function writebackHelp(): string {
   return `fclt ai writeback
 
 Usage:
-  fclt ai writeback add --kind <kind> --summary <text> [--asset <selector>] [--tag <tag>] [--evidence <type:ref>]
+  fclt ai writeback add --kind <kind> --summary <text> [--asset <selector>] [--tag <tag>] [--evidence <type:ref>] [--allow-empty-evidence]
   fclt ai writeback list [--json]
   fclt ai writeback show <id> [--json]
   fclt ai writeback group --by <asset|kind|domain> [--json]
@@ -1521,6 +1531,7 @@ async function writebackCommand(argv: string[]) {
         kind,
         summary,
         asset: parseStringFlag(parsed.argv, "--asset"),
+        allowEmptyEvidence: parsed.argv.includes("--allow-empty-evidence"),
         confidence:
           (parseStringFlag(parsed.argv, "--confidence") as
             | ConfidenceLevel

package/src/remote.ts

@@ -338,9 +338,11 @@ const BUILTIN_AUTOMATION_TEMPLATES: BuiltinAutomationTemplate[] = [
 Use this memory for pattern continuity:
 
 - Primary goal: convert repeated, evidence-backed session signal into durable writeback or evolution, not chat-only summary.
+- 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.
+- 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.
 - If available, use [$capability-evolution]({{capabilityEvolutionSkill}}) when repeated signal should become a concrete proposal.
@@ -358,6 +360,7 @@ Before producing output:
 
 Grounding rules:
 - Work only from evidence in Codex sessions and nearby repo artifacts for the configured CWDs.
+- Partition the review by cwd first. Name which configured cwds had real evidence this run and which did not.
 - Prefer evidence from session messages, tool calls, shell commands, diffs, tests, commits, and touched files.
 - Do not speculate about intent or propose changes that are not anchored in evidence.
 - Distinguish one-off friction from repeated signal. Escalate only when the signal is durable enough to matter.
@@ -366,6 +369,7 @@ Decision rules:
 - Use \`fclt ai writeback add\` when the signal, target asset, and scope are clear.
 - 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.
 - Skip weak, speculative, or purely anecdotal observations.
 
 Verification:
@@ -374,12 +378,77 @@ Verification:
 - Separate missing context, weak verification, failed execution, and reusable pattern; do not collapse them together.
 
 Output:
+- Coverage: which cwds had concrete evidence, and which were effectively idle for this run.
 - Recorded writebacks: what you recorded, why, and the target asset or command used.
 - Evolution candidates: only the strongest repeated signals, with rationale and likely scope.
 - Watch list: promising signals not yet strong enough to encode.
 - Gaps in current operating model or verification harness: only if evidence supports them.
 
 Keep the result concise, high-signal, and operational. If nothing crosses the threshold, say what you reviewed and why no writeback or evolution was justified.`,
+  },
+  {
+    id: "evolution-review",
+    title: "Evolution Review Loop",
+    description:
+      "Weekly Codex review of open evolution proposals and strong writeback clusters, with suggested next actions for review, acceptance, rejection, promotion, or apply.",
+    defaultRRule: "RRULE:FREQ=WEEKLY;BYHOUR=16;BYMINUTE=0;BYDAY=FR",
+    defaultStatus: "PAUSED",
+    defaultModel: "gpt-5.4",
+    defaultReasoningEffort: "high",
+    scope: "wide",
+    memory: `# Evolution Review Loop
+
+Use this memory for continuity:
+
+- Primary goal: keep proposal review moving so durable changes do not stall after writeback.
+- Review continuity matters: track which proposals were already seen, what changed since the last review, and which action was previously recommended.
+- Prefer reviewing existing proposal and writeback state over rediscovering the entire history from scratch.
+- Scope: default to project evolution unless the proposal clearly belongs in shared doctrine, shared agents, shared skills, or another cross-project capability.
+- For wide reviews, partition by cwd first and only recommend shared/global promotion when evidence truly spans multiple repos or the target asset is obviously shared.
+- Recommend actions, do not silently apply high-risk changes.
+- If available, use [$capability-evolution]({{capabilityEvolutionSkill}}) when proposal shaping or promotion decisions need stronger structure.
+- If available, use [$feedback-loop-setup]({{feedbackLoopSkill}}) when proposal validity depends on weak or stale verification.
+- If available, delegate bounded slices to \`evolution-planner\`, \`scope-promoter\`, \`writeback-curator\`, or \`verification-auditor\` when that materially improves rigor.
+`,
+    prompt: `Goal: review current evolution state in the configured CWDs, keep proposal continuity intact, and suggest the highest-signal next actions for draft, review, accept, reject, promote, supersede, or apply.
+
+Before producing output:
+- Treat [AGENTS.md]({{codexAgents}}) as the rendered operating-model baseline for this Codex environment.
+- Use [EVOLUTION.md]({{aiEvolution}}), [LEARNING_AND_WRITEBACK.md]({{aiLearningAndWriteback}}), and [VERIFICATION.md]({{aiVerification}}) as the doctrine for proposal quality, thresholding, and proof.
+- Use [FEEDBACK_LOOPS.md]({{aiFeedbackLoops}}) when a proposal depends on a weak or gameable verification loop.
+- If available, use [$capability-evolution]({{capabilityEvolutionSkill}}) when you need stronger proposal-shaping or promotion judgment.
+- If available, use [$feedback-loop-setup]({{feedbackLoopSkill}}) when proposal validity depends on missing or stale verification.
+- If it will materially improve quality, explicitly ask Codex to spawn narrow subagents such as \`evolution-planner\`, \`scope-promoter\`, \`writeback-curator\`, or \`verification-auditor\`. Only use them for bounded, non-overlapping review slices.
+
+Grounding rules:
+- Work from concrete proposal and writeback artifacts first, then confirm with nearby repo evidence when needed.
+- Preserve continuity: compare this run against the automation memory and note what is actually new, unchanged, strengthened, weakened, accepted, rejected, or stale.
+- Partition the review by cwd first. Name which configured cwds had real proposal or writeback state this run and which did not.
+- Do not speculate about intent or recommend advancing a proposal without citing the evidence that still supports it.
+- Distinguish proposal quality problems from execution gaps, stale evidence, missing verification, and simple lack of reviewer attention.
+
+Decision rules:
+- Prefer suggesting the next operator action over narrating the whole proposal history.
+- Recommend \`draft\` when a proposal exists but is under-specified.
+- Recommend \`review\` or \`accept\` only when the rationale, scope, and evidence are strong enough.
+- Recommend \`apply\` only for already-accepted proposals whose evidence still looks valid and whose risk is appropriate.
+- Recommend \`reject\` or \`supersede\` when the proposal is stale, contradicted, duplicated, or too weak.
+- Recommend \`promote --to global\` only when a project-scoped proposal now clearly belongs in shared doctrine, shared agents, shared skills, or another cross-project surface.
+- For wide automations, require repeated evidence across more than one cwd before recommending shared/global promotion unless the target is obviously global.
+
+Verification:
+- Verify every recommendation against at least one concrete artifact.
+- Call out residual uncertainty instead of overstating confidence.
+- If a proposal should move forward but the proof is weak, say exactly what verification is missing.
+
+Output:
+- Coverage: which cwds had concrete proposal/writeback evidence, and which were effectively idle for this run.
+- Proposal queue: the strongest active proposals or proposal-worthy clusters, with what changed since the last review.
+- Recommended actions: for each important item, the next operator action and why.
+- Hold or reject: proposals that should stay parked, be rejected, or be superseded.
+- Verification gaps: only the missing proof that materially blocks a recommendation.
+
+Keep the result concise, continuity-aware, and operational. If nothing is ready to move, say what you reviewed and why no proposal should advance this run.`,
   },
   {
     id: "tool-call-audit",
@@ -2874,7 +2943,7 @@ export async function templatesCommand(
     const templateId = positional[0];
     if (!templateId) {
       console.error(
-        "templates init automation requires a <template-id> (learning-review|tool-call-audit)"
+        "templates init automation requires a <template-id> (learning-review|evolution-review|tool-call-audit)"
       );
       process.exitCode = 2;
       return;