facult 2.8.12 → 2.10.0

package/README.md

@@ -127,7 +127,7 @@ fclt index
 
 Why `keep-current`: it is deterministic and non-interactive for duplicate sources.
 
-### 4. Manage a tool and sync
+### 4. Optional: manage a tool and sync
 
 ```bash
 fclt manage codex --dry-run
@@ -140,7 +140,11 @@ fclt enable requesting-code-review receiving-code-review brainstorming systemati
 fclt sync
 ```
 
-Use `--dry-run` first if the live tool already has local content. If the tool already contains skills, agents, rules, docs, config, or MCP definitions, rerun with `--adopt-existing` and add `--existing-conflicts keep-canonical|keep-existing` if names collide.
+Managed rendering is an advanced mode. Prefer `fclt inventory`, `fclt list`, `fclt consolidate`, and explicit writeback/evolution when you mainly want visibility and normalization across Codex, Claude, and other tool homes. Use `manage` only when you want fclt to write rendered files back into a tool.
+
+Use `--dry-run` first if the live tool already has local content. If the tool already contains skills, agents, rules, docs, config, or MCP definitions, rerun `manage` with `--adopt-existing` and add `--existing-conflicts keep-canonical|keep-existing` if names collide.
+
+Ordinary `fclt sync` does not import live tool edits into canonical state. If you intentionally edited skills, agents, docs, rules, config, or MCP entries in Codex/Claude and want fclt to pick them up, run `fclt sync --adopt-live`.
 
 Codex path policy:
 - skills render to `.agents/skills`
@@ -200,6 +204,8 @@ Useful AI behavior is composable. You need small reusable parts, a clean way to
 - discovery and graph views for dependencies, provenance, and rendered targets
 - writeback and evolution flows for improving canonical assets over time
 
+The renderer is optional. The low-friction default is to let tools keep their native files, use `fclt inventory`/`scan`/`list` to see the full global set, and use `fclt consolidate` or `fclt sync --adopt-live` only when you explicitly want to promote live tool edits into canonical `~/.ai`.
+
 ## Built-in Defaults
 
 `fclt` includes a built-in layer for writeback and evolution. By default, that layer provides:
@@ -231,9 +237,10 @@ Put that in `config.toml` or `config.local.toml` under the active canonical root
 
 `fclt` is CLI-first. The practical setup is:
 1. Install `fclt` globally so any agent runtime can execute it.
-2. Manage each agent tool with `fclt manage <tool>` and `fclt sync`.
-3. Let the built-in operating-model layer render global writeback/evolution instructions into the tool.
-4. Optionally scaffold MCP wrappers if you want an MCP entry that delegates to `fclt`.
+2. Use `fclt inventory`, `fclt list`, and `fclt consolidate` to inspect and normalize existing tool-native state.
+3. If you want fclt-owned rendered outputs, manage each agent tool with `fclt manage <tool>` and `fclt sync`.
+4. Let the built-in operating-model layer render global writeback/evolution instructions into the tool only where managed rendering is worth the ownership tradeoff.
+5. Optionally scaffold MCP wrappers if you want an MCP entry that delegates to `fclt`.
 
 ```bash
 # Scaffold reusable templates in the canonical store
@@ -450,14 +457,18 @@ fclt ai evolve apply EV-00001
 fclt ai evolve promote EV-00003 --to global --project
 ```
 
-Runtime writeback and evolution state stays generated and machine-local:
+Runtime writeback and evolution source state stays generated and machine-local:
 - global writeback state: machine-local Facult state under `.../global/ai/global/...`
 - project writeback state: machine-local per-project Facult state under `.../projects/<slug-hash>/ai/project/...`
+- editor-facing writeback review artifacts: `~/.ai/writebacks/global/*.md` and `~/.ai/writebacks/projects/<slug-hash>/*.md`
+- editor-facing evolution review artifacts: `~/.ai/evolution/global/*.md` and `~/.ai/evolution/projects/<slug-hash>/*.md`
 
 That split is intentional:
 - canonical source remains in `~/.ai` or `<repo>/.ai`
-- global generated index and graph state stays inside `~/.ai/.facult/`; writebacks, journals, proposals, drafts, and managed runtime state stay outside canonical source in machine-local state
-- those records let agents inspect what changed, why it changed, and how it was reviewed
+- global generated index and graph state stays inside `~/.ai/.facult/`; JSON queues, proposal metadata, journals, draft refs, patches, and managed runtime state stay outside canonical source in machine-local state
+- human-readable review artifacts always live under the global `~/.ai` root, even when the signal is project-scoped
+- project repos do not receive bundled writeback/evolution review artifacts; project metadata such as cwd, project root, project slug, target refs, status, and evidence is captured in frontmatter instead
+- those records let agents and humans inspect what changed, why it changed, and how it was reviewed
 
 Use writeback when:
 - a task exposed a weak or misleading verification loop
@@ -485,12 +496,14 @@ Current apply semantics are intentionally policy-bound:
 
 Current review/draft semantics:
 - `writeback group` and `writeback summarize` expose recurring patterns across `asset`, `kind`, and `domain` without mutating canonical assets
-- drafted proposals emit both a human-readable markdown draft and a patch artifact under generated state
+- every writeback/proposal mutation refreshes a Markdown review artifact under global `~/.ai/writebacks/...` or `~/.ai/evolution/...` with frontmatter metadata
+- drafted proposals emit both a human-readable markdown draft and a patch artifact under machine-local generated state, and the latest draft body is mirrored into the global evolution review artifact
 - rerunning `evolve draft <id> --append ...` revises the draft and records draft history
 - `evolve promote --to global` creates a new high-risk global proposal from a project-scoped proposal; that promoted proposal can then be drafted, reviewed, and applied into `~/.ai`
 
 Review surfaces:
-- `fclt status --json` reports queue/proposal paths and counts for the active scope
+- open `~/.ai/writebacks/` and `~/.ai/evolution/` in a Markdown editor for global and project-scoped review artifacts
+- `fclt status --json` reports queue/proposal paths, review artifact paths, and counts for the active scope
 - `fclt ai writeback list|show|group|summarize` reviews raw and clustered signal
 - `fclt ai evolve list|show|review` reviews proposal state without applying changes
 - `fclt templates init automation learning-review` scaffolds background writeback capture/review
@@ -586,7 +599,7 @@ fclt disable <name> [--for <tool1,tool2,...>]
 fclt trust --all
 fclt trust skills --all
 fclt untrust mcp --all
-fclt sync [tool] [--dry-run] [--builtin-conflicts overwrite]
+fclt sync [tool] [--dry-run] [--adopt-live] [--builtin-conflicts overwrite]
 fclt autosync install [tool] [--git-remote <name>] [--git-branch <name>] [--git-interval-minutes <n>] [--git-disable]
 fclt autosync status [tool]
 fclt autosync restart [tool]
@@ -635,7 +648,7 @@ fclt snippets sync [--dry-run] [file...]
 
 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 `learning-review --scope project` for project-scoped writeback and evolution. This keeps verification and follow-up scoped to the repo that produced the evidence while storing human-readable review artifacts under global `~/.ai/writebacks/projects/...` and `~/.ai/evolution/projects/...`.
 - 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.
@@ -734,6 +747,10 @@ Under machine-local Facult state:
 - `cache/runtime/<version>/<platform-arch>/...` under the macOS machine-local state root, or `runtime/<version>/<platform-arch>/...` under `FACULT_CACHE_DIR`/XDG cache roots on other platforms (npm launcher binary cache)
   - if that cache root is unavailable, the npm launcher falls back to a temp-dir runtime cache before using the bundled source fallback
 
+Under global Markdown review state (`~/.ai/`):
+- `writebacks/global/*.md` and `writebacks/projects/<slug-hash>/*.md` (frontmatter-rich writeback review artifacts)
+- `evolution/global/*.md` and `evolution/projects/<slug-hash>/*.md` (frontmatter-rich proposal review artifacts, including latest draft body when present)
+
 ### Config reference
 
 `~/.ai/.facult/config.json` supports:

package/assets/packs/facult-operating-model/instructions/EVOLUTION.md

@@ -78,7 +78,8 @@ Use `fclt ai evolve draft <id> --append "..."` to revise a draft while preservin
 
 Review surfaces:
 
-- `fclt status --json` for queue/proposal paths, counts, and active scope
+- open `~/.ai/writebacks/` and `~/.ai/evolution/` in a Markdown editor for frontmatter-rich global and project-scoped review artifacts
+- `fclt status --json` for queue/proposal paths, review artifact paths, counts, and active scope
 - `fclt ai writeback list|show|group|summarize` for raw and clustered signal
 - `fclt ai evolve list|show|review` for proposal state without applying changes
 - `fclt templates init automation learning-review` for recurring capture/review
@@ -86,9 +87,12 @@ Review surfaces:
 - `fclt templates init automation tool-call-audit` for repeated tool-friction review
 
 Evolution proposal metadata, markdown drafts, patch artifacts, writeback queues,
-and journals are runtime state. `fclt` stores them in machine-local Facult state;
-canonical assets in `~/.ai` or `<repo>/.ai` should only change when a proposal is
-applied.
+and journals are runtime state. `fclt` stores JSON queues, proposal records,
+draft refs, patches, and journals in machine-local Facult state. It mirrors
+human-readable review artifacts into global `~/.ai/writebacks/...` and
+`~/.ai/evolution/...`, including project-scoped artifacts under
+`projects/<slug-hash>/` with cwd/project metadata in frontmatter. Canonical
+assets in `~/.ai` or `<repo>/.ai` should only change when a proposal is applied.
 
 ## Default Agent Behavior
 

package/assets/packs/facult-operating-model/instructions/LEARNING_AND_WRITEBACK.md

@@ -28,10 +28,18 @@ Use:
 fclt ai writeback add --kind <kind> --summary "<summary>" --asset <asset-selector>
 ```
 
-The writeback queue is runtime state, not canonical source. `fclt` stores it in
-machine-local Facult state so sandboxed agents can record durable friction
-without mutating `~/.ai` or a repo-local `.ai` unless an evolution proposal is
-later reviewed and applied.
+The writeback queue is runtime state, not canonical source. `fclt` stores JSON
+queue state in machine-local Facult state so sandboxed agents can record durable
+friction without mutating canonical assets unless an evolution proposal is later
+reviewed and applied.
+
+Every writeback also refreshes a Markdown review artifact under the global
+`~/.ai/writebacks/...` tree. Global signal lands in `~/.ai/writebacks/global/`;
+project-scoped signal lands in `~/.ai/writebacks/projects/<slug-hash>/` with
+frontmatter for scope, project root, cwd, target asset, status, tags, evidence,
+and timestamps. Do not write writeback review artifacts into a repo-local `.ai`;
+repo-local state should contribute project metadata and evidence, not bundled
+private review files.
 
 Project-scoped writebacks should usually be recorded from the repo that produced
 the evidence. Global writebacks should be reserved for shared doctrine, shared

package/package.json

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

package/src/ai-state.ts

@@ -58,15 +58,7 @@ async function newestPathMtime(path: string): Promise<number> {
 }
 
 async function watchedPathMtime(path: string): Promise<number> {
-  const newest = await newestPathMtime(path);
-  if (newest > 0) {
-    return newest;
-  }
-  try {
-    return (await stat(dirname(path))).mtimeMs;
-  } catch {
-    return 0;
-  }
+  return await newestPathMtime(path);
 }
 
 async function canonicalAssetsNewerThanIndex(args: {

package/src/ai.ts

@@ -7,10 +7,12 @@ import type { AssetScope, GraphNodeKind } from "./graph";
 import { loadGraph, resolveGraphNode } from "./graph-query";
 import {
   facultAiDraftDir,
+  facultAiEvolutionReviewDir,
   facultAiJournalPath,
   facultAiProposalDir,
   facultAiStateDir,
   facultAiWritebackQueuePath,
+  facultAiWritebackReviewDir,
   facultRootDir,
   legacyFacultAiStateDirs,
   projectRootFromAiRoot,
@@ -284,6 +286,176 @@ function uniqueStrings(values: string[]): string[] {
   return [...new Set(values.filter(Boolean))];
 }
 
+function yamlScalar(value: unknown): string {
+  if (typeof value === "string") {
+    return JSON.stringify(value);
+  }
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  if (Array.isArray(value)) {
+    return JSON.stringify(value);
+  }
+  if (value && typeof value === "object") {
+    return JSON.stringify(value);
+  }
+  return "null";
+}
+
+function renderFrontmatter(values: Record<string, unknown>): string {
+  const lines = Object.entries(values)
+    .filter(([, value]) => value !== undefined)
+    .map(([key, value]) => `${key}: ${yamlScalar(value)}`);
+  return ["---", ...lines, "---"].join("\n");
+}
+
+function markdownList(values: string[]): string[] {
+  return values.length > 0 ? values.map((value) => `- ${value}`) : ["- none"];
+}
+
+function renderEvidenceList(evidence: WritebackEvidence[]): string[] {
+  return evidence.length > 0
+    ? evidence.map((entry) => `- ${entry.type}: ${entry.ref}`)
+    : ["- none"];
+}
+
+function writebackReviewPath(
+  homeDir: string,
+  rootDir: string,
+  id: string
+): string {
+  return join(facultAiWritebackReviewDir(homeDir, rootDir), `${id}.md`);
+}
+
+function proposalReviewPath(
+  homeDir: string,
+  rootDir: string,
+  id: string
+): string {
+  return join(facultAiEvolutionReviewDir(homeDir, rootDir), `${id}.md`);
+}
+
+async function writeWritebackReviewArtifact(args: {
+  homeDir: string;
+  rootDir: string;
+  record: AiWritebackRecord;
+}): Promise<void> {
+  const pathValue = writebackReviewPath(
+    args.homeDir,
+    args.rootDir,
+    args.record.id
+  );
+  await ensureParentDir(pathValue);
+  const body = [
+    renderFrontmatter({
+      id: args.record.id,
+      artifact: "writeback",
+      status: args.record.status,
+      scope: args.record.scope,
+      kind: args.record.kind,
+      confidence: args.record.confidence,
+      source: args.record.source,
+      assetRef: args.record.assetRef,
+      assetId: args.record.assetId,
+      assetType: args.record.assetType,
+      suggestedDestination: args.record.suggestedDestination,
+      domain: args.record.domain,
+      tags: args.record.tags,
+      projectSlug: args.record.projectSlug,
+      projectRoot: args.record.projectRoot,
+      cwd: args.record.projectRoot,
+      rootDir: args.rootDir,
+      createdAt: args.record.ts,
+      updatedAt: args.record.updatedAt ?? args.record.ts,
+    }),
+    "",
+    `# ${args.record.id}: ${args.record.summary}`,
+    "",
+    "## Summary",
+    args.record.summary,
+    "",
+    "## Evidence",
+    ...renderEvidenceList(args.record.evidence),
+    "",
+    "## Target",
+    `- asset: ${args.record.assetRef ?? "unassigned"}`,
+    `- destination: ${args.record.suggestedDestination ?? "unassigned"}`,
+    "",
+  ].join("\n");
+  await Bun.write(pathValue, `${body.trimEnd()}\n`);
+}
+
+async function writeProposalReviewArtifact(args: {
+  homeDir: string;
+  rootDir: string;
+  proposal: AiProposalRecord;
+  writebacks?: AiWritebackRecord[];
+  draftBody?: string | null;
+}): Promise<void> {
+  const pathValue = proposalReviewPath(
+    args.homeDir,
+    args.rootDir,
+    args.proposal.id
+  );
+  await ensureParentDir(pathValue);
+  const body = [
+    renderFrontmatter({
+      id: args.proposal.id,
+      artifact: "evolution_proposal",
+      status: args.proposal.status,
+      scope: args.proposal.scope,
+      kind: args.proposal.kind,
+      confidence: args.proposal.confidence,
+      policyClass: args.proposal.policyClass,
+      reviewRequired: args.proposal.reviewRequired,
+      targets: args.proposal.targets,
+      sourceWritebacks: args.proposal.sourceWritebacks,
+      sourceProposals: args.proposal.sourceProposals,
+      draftRefs: args.proposal.draftRefs,
+      projectSlug: args.proposal.projectSlug,
+      projectRoot: args.proposal.projectRoot,
+      cwd: args.proposal.projectRoot,
+      rootDir: args.rootDir,
+      createdAt: args.proposal.ts,
+      updatedAt:
+        args.proposal.review?.reviewedAt ??
+        args.proposal.applyResult?.appliedAt ??
+        args.proposal.draftHistory?.at(-1)?.ts ??
+        args.proposal.ts,
+    }),
+    "",
+    `# ${args.proposal.id}: ${args.proposal.summary}`,
+    "",
+    "## Rationale",
+    args.proposal.rationale,
+    "",
+    "## Targets",
+    ...markdownList(args.proposal.targets),
+    "",
+    "## Source Writebacks",
+    ...(args.writebacks && args.writebacks.length > 0
+      ? args.writebacks.map(
+          (entry) => `- ${entry.id} (${entry.kind}): ${entry.summary}`
+        )
+      : markdownList(args.proposal.sourceWritebacks)),
+    "",
+    "## Draft Refs",
+    ...markdownList(args.proposal.draftRefs),
+    "",
+    ...(args.draftBody
+      ? [
+          "## Current Draft",
+          "",
+          "```markdown",
+          args.draftBody.trimEnd(),
+          "```",
+          "",
+        ]
+      : []),
+  ].join("\n");
+  await Bun.write(pathValue, `${body.trimEnd()}\n`);
+}
+
 function slugToTitle(value: string): string {
   return value
     .split(SLUG_SPLIT_RE)
@@ -498,6 +670,11 @@ export async function addWriteback(
     evidence: record.evidence,
     tags: record.tags,
   });
+  await writeWritebackReviewArtifact({
+    homeDir,
+    rootDir: args.rootDir,
+    record,
+  });
   return record;
 }
 
@@ -556,6 +733,11 @@ async function updateWritebackStatus(
     refs: next.assetRef ? [next.assetRef] : undefined,
     tags: next.tags,
   });
+  await writeWritebackReviewArtifact({
+    homeDir,
+    rootDir: args.rootDir,
+    record: next,
+  });
   return next;
 }
 
@@ -743,6 +925,7 @@ async function writeProposalFile(
     join(dir, `${proposal.id}.json`),
     `${JSON.stringify(proposal, null, 2)}\n`
   );
+  await writeProposalReviewArtifact({ homeDir, rootDir, proposal });
 }
 
 export async function proposeEvolution(args: {
@@ -835,6 +1018,12 @@ export async function proposeEvolution(args: {
       draftRefs: [],
     };
     await writeProposalFile(homeDir, args.rootDir, proposal);
+    await writeProposalReviewArtifact({
+      homeDir,
+      rootDir: args.rootDir,
+      proposal,
+      writebacks: entries,
+    });
     await appendEvent(homeDir, args.rootDir, {
       id: nextId("EVT", []),
       ts: proposal.ts,
@@ -1203,6 +1392,13 @@ export async function draftProposal(
       }),
     })
   );
+  await writeProposalReviewArtifact({
+    homeDir,
+    rootDir: args.rootDir,
+    proposal: next,
+    writebacks,
+    draftBody,
+  });
   await appendEvent(homeDir, args.rootDir, {
     id: "",
     ts: nowIso(),
@@ -1490,6 +1686,12 @@ export async function promoteProposal(
     applyResult: undefined,
   };
   await writeProposalFile(homeDir, targetRoot, promoted);
+  await writeProposalReviewArtifact({
+    homeDir,
+    rootDir: targetRoot,
+    proposal: promoted,
+    writebacks: sourceWritebacks,
+  });
   await appendEvent(homeDir, targetRoot, {
     id: "",
     ts: promoted.ts,

package/src/builtin-assets.ts

@@ -1,5 +1,5 @@
 // Generated by scripts/generate-builtin-assets.ts. Do not edit by hand.
 
 export const BUILTIN_OPERATING_MODEL_FILES = JSON.parse(
-  '{"AGENTS.global.md":"# Facult Operating Defaults\\n\\nThis machine has a default Facult operating-model layer available.\\n\\nWhen work produces durable friction, weak verification, stale guidance, or a missing skill/tool capability, preserve that signal with `fclt ai writeback ...` when the target and scope are clear. When repeated writebacks or clearly missing capability point at a concrete improvement, use `fclt ai evolve ...` or the `capability-evolution` skill to make a reviewable proposal.\\n\\nFor writeback and evolution, read `@builtin/facult-operating-model/instructions/EVOLUTION.md`.\\nFor learning and writeback defaults, read `@builtin/facult-operating-model/instructions/LEARNING_AND_WRITEBACK.md`.\\nFor deciding whether capability belongs in global or project scope, read `@builtin/facult-operating-model/instructions/PROJECT_CAPABILITY.md`.\\nFor project operating-layer design, read `@builtin/facult-operating-model/instructions/INTEGRATION.md`.\\n\\nBuiltin specialist agents are available for:\\n- writeback curation\\n- evolution planning\\n- scope promotion\\n- integration auditing\\n\\nBuiltin skills are available for:\\n- capability evolution\\n- project operating-layer design\\n","agents/evolution-planner/agent.toml":"name = \\"evolution-planner\\"\\ndescription = \\"Turn repeated writeback into concrete capability proposals.\\"\\n\\ndeveloper_instructions = \\"\\"\\"\\nYou plan capability evolution.\\n\\nPrioritize:\\n- smallest useful change\\n- correct target asset type\\n- correct target scope\\n- evidence that justifies the change\\n- repeated writeback clusters or clearly missing capabilities, not isolated preferences\\n\\nProposal kinds you should consider first:\\n- update_asset\\n- create_asset\\n- extract_snippet\\n- add_skill\\n- promote_asset\\n\\nDefault to project scope when the pattern is repo-local.\\nPromote to global only when reuse is demonstrated and pollution risk is low.\\n\\nReturn concise proposals ordered by expected leverage, including:\\n- proposal kind\\n- target asset\\n- target scope\\n- why this is the smallest durable change\\n\\nDo not escalate to evolution when a single writeback is enough.\\nDo not use evolution as a substitute for executable task tracking when the main need is owner, priority, state, or implementation follow-through.\\n\\"\\"\\"\\n","agents/integration-auditor/agent.toml":"name = \\"integration-auditor\\"\\ndescription = \\"Find where local success can still fail system-wide.\\"\\n\\ndeveloper_instructions = \\"\\"\\"\\nYou audit integration risk.\\n\\nPrioritize:\\n- hidden dependencies\\n- rollout hazards\\n- operational constraints\\n- gaps between local verification and real system behavior\\n\\nReturn concise findings ordered by impact.\\n\\"\\"\\"\\n","agents/scope-promoter/agent.toml":"name = \\"scope-promoter\\"\\ndescription = \\"Decide whether learning belongs at project or global scope.\\"\\n\\ndeveloper_instructions = \\"\\"\\"\\nYou decide scope.\\n\\nPrioritize:\\n- project specificity\\n- cross-project reuse potential\\n- pollution risk from globalizing too early\\n\\nWhen recommending promotion, make the standard path explicit:\\n- keep the source capability in project scope until promotion is approved\\n- create a reviewable global proposal\\n- do not treat promotion as implicit apply\\n\\nReturn concise decisions with rationale.\\n\\"\\"\\"\\n","agents/writeback-curator/agent.toml":"name = \\"writeback-curator\\"\\ndescription = \\"Turn noisy outcomes into high-signal writeback.\\"\\n\\ndeveloper_instructions = \\"\\"\\"\\nYou curate durable writeback.\\n\\nPrioritize:\\n- repeated failures\\n- repeated wins\\n- stale guidance\\n- missing capability edges\\n- tool, skill, MCP, plugin, automation, or instruction friction that repeatedly slows work down\\n\\nFor each recommendation, prefer returning:\\n- suggested writeback kind\\n- best target asset or destination\\n- best scope (`project` or `global`)\\n- the evidence that justifies recording it\\n\\nDo not emit low-signal noise.\\nIf the learning is repo-specific, keep it project-scoped by default.\\nWhen the signal is already strong and the target is clear, prefer recommending direct writeback capture rather than abstract advice.\\nWhen the issue is executable tooling work, recommend task tracking for the fix and writeback only for the reusable operating-model learning.\\n\\"\\"\\"\\n","instructions/EVOLUTION.md":"---\\ndescription: Turn repeated signal into concrete capability changes.\\ntags: [facult, evolution, writeback]\\n---\\n\\n# Evolution\\n\\nUse writeback and evolution to improve the AI operating layer itself.\\n\\nEvolution is the synthesis and change side of the feedback loop. It turns accumulated writebacks, repeated tool friction, stale canonical assets, or clearly missing capability into small reviewable changes to instructions, skills, snippets, agents, or other markdown canonical assets.\\n\\n## When To Record Writeback\\n\\nRecord writeback when one of these is true:\\n\\n- the same failure repeats\\n- the same success pattern repeats\\n- guidance is stale or missing\\n- a prompt or loop has to be restated often\\n- a project-specific pattern looks reusable\\n\\nDo not record low-signal noise:\\n\\n- one-off annoyance with no reuse value\\n- generic \\"could be better\\" commentary\\n- duplicate observations with no new evidence\\n\\nThe intended default is that agents record strong writebacks themselves when the signal is clear enough, rather than only recommending that a user do it manually later.\\n\\nDo not wait for a weekly review to preserve high-signal evidence. Do wait for repeated evidence or a clearly missing capability before drafting a proposal.\\n\\n## Scope\\n\\nChoose `project` scope when the learning depends on:\\n\\n- repo architecture\\n- team workflow\\n- project tooling\\n- local testing or verification behavior\\n\\nChoose `global` scope when the learning is reusable across projects.\\n\\nPromote from project to global only after repeated reuse or strong evidence.\\n\\n## Writeback Kinds\\n\\nCommon kinds:\\n\\n- `weak_verification`\\n- `false_positive`\\n- `missing_context`\\n- `reusable_pattern`\\n- `capability_gap`\\n- `bad_default`\\n\\nEvery good writeback should try to include:\\n\\n- a concrete summary\\n- the best target asset if known\\n- the right scope\\n- domain or tags when useful\\n\\n## Operator Flow\\n\\nTypical workflow:\\n\\n```bash\\nfclt ai writeback add --kind weak_verification --summary \\"Checks were too shallow\\" --asset instruction:VERIFICATION\\nfclt ai writeback group --by asset\\nfclt ai writeback summarize --by domain\\nfclt ai evolve propose\\nfclt ai evolve draft EV-00001\\nfclt ai evolve accept EV-00001\\nfclt ai evolve apply EV-00001\\n```\\n\\nUse `fclt ai evolve draft <id> --append \\"...\\"` to revise a draft while preserving draft history.\\n\\nReview surfaces:\\n\\n- `fclt status --json` for queue/proposal paths, counts, and active scope\\n- `fclt ai writeback list|show|group|summarize` for raw and clustered signal\\n- `fclt ai evolve list|show|review` for proposal state without applying changes\\n- `fclt templates init automation learning-review` for recurring capture/review\\n- `fclt templates init automation evolution-review` for recurring proposal review\\n- `fclt templates init automation tool-call-audit` for repeated tool-friction review\\n\\nEvolution proposal metadata, markdown drafts, patch artifacts, writeback queues,\\nand journals are runtime state. `fclt` stores them in machine-local Facult state;\\ncanonical assets in `~/.ai` or `<repo>/.ai` should only change when a proposal is\\napplied.\\n\\n## Default Agent Behavior\\n\\nUse the smallest action that fits the signal:\\n\\n1. record one strong writeback when there is a clear durable learning\\n2. use `writeback-curator` when the target, kind, or scope is ambiguous\\n3. use `capability-evolution` or `evolution-planner` when repeated signal should become a proposal\\n4. do not draft or apply proposals just because a writeback exists; require repeated evidence or a clearly missing capability\\n\\nAvoid creating writeback/evolution noise for one-off nits, vague preferences, or speculative ideas without evidence.\\n\\nWhen the friction is executable product/tooling work that needs ownership,\\npriority, state, or implementation follow-through, create or update a real task\\nsystem item instead of forcing it into capability evolution. Use evolution for\\nthe reusable operating-layer change.\\n\\n## Proposal Kinds\\n\\nCurrent supported proposal kinds:\\n\\n- `update_asset`\\n- `create_asset`\\n- `extract_snippet`\\n- `add_skill`\\n- `promote_asset`\\n\\nUse the smallest durable change that fits the evidence.\\n\\n## Review And Apply Rules\\n\\n- draft before apply\\n- accept before apply\\n- prefer the smallest safe change\\n- keep reviewable evidence tied to source writebacks\\n- do not globalize project behavior too early\\n- do not apply high-risk global instruction, skill, plugin, or non-COS changes without explicit review/approval\\n\\nApply is for markdown canonical assets only. If the target is wrong, revise the proposal rather than forcing it through.\\n","instructions/INTEGRATION.md":"---\\ndescription: Detect where local success can still fail at integration boundaries.\\ntags: [facult, integration, verification]\\n---\\n\\n# Integration\\n\\nDistinguish local correctness from system correctness. Check hidden dependencies, rollout order, and operational constraints before calling work done.\\n","instructions/LEARNING_AND_WRITEBACK.md":"---\\ndescription: Preserve durable signal and record writeback when the operating layer should learn.\\ntags: [facult, learning, writeback]\\n---\\n\\n# Learning And Writeback\\n\\nUse this when work produces a durable decision, failure, success pattern, or missing guardrail that should outlive the current task.\\n\\nThis is the capture side of the feedback loop. The goal is to let normal agent work produce reusable signal without requiring a human to manually restate every friction point later.\\n\\n## Default Behavior\\n\\nThe normal path should be agent-driven.\\n\\nIf you can clearly answer:\\n\\n- what was learned\\n- why it matters\\n- where it should land\\n- whether it belongs in `project` or `global`\\n\\nthen record the writeback instead of only suggesting that someone should do it later.\\n\\nUse:\\n\\n```bash\\nfclt ai writeback add --kind <kind> --summary \\"<summary>\\" --asset <asset-selector>\\n```\\n\\nThe writeback queue is runtime state, not canonical source. `fclt` stores it in\\nmachine-local Facult state so sandboxed agents can record durable friction\\nwithout mutating `~/.ai` or a repo-local `.ai` unless an evolution proposal is\\nlater reviewed and applied.\\n\\nProject-scoped writebacks should usually be recorded from the repo that produced\\nthe evidence. Global writebacks should be reserved for shared doctrine, shared\\nskills, shared agents, tool behavior, or cross-project capability gaps.\\n\\n## Record Writeback When\\n\\n- the same failure or weak loop appears again\\n- a reusable success pattern shows up\\n- guidance is clearly stale or missing\\n- a repo-local behavior probably belongs in project capability\\n- a cross-project behavior probably belongs in global capability\\n- a skill, tool, MCP, plugin, automation, or instruction gap repeatedly slows work down\\n- an agent has to restate the same workaround, verification rule, or review rule\\n\\n## Do Not Record Writeback For\\n\\n- one-off annoyance with no durable value\\n- weak commentary with no target\\n- speculative ideas without evidence\\n- duplicate noise with no new signal\\n\\n## Follow Through\\n\\n- prefer one strong writeback over many weak ones\\n- mention the writeback id when summarizing what changed\\n- escalate to `capability-evolution` or `fclt ai evolve ...` only when the signal is repeated or clearly points at a durable capability change\\n- use `fclt ai writeback group --by asset` or `fclt ai writeback summarize --by domain` to review accumulated signal before proposing broad changes\\n- use scheduled `learning-review`, `evolution-review`, or `tool-call-audit` automations when the signal should be reviewed in the background\\n","instructions/PROJECT_CAPABILITY.md":"---\\ndescription: Decide what belongs in repo-local .ai versus the global store.\\ntags: [facult, project, scope]\\n---\\n\\n# Project Capability\\n\\nPrefer project scope when the guidance depends on repo architecture, team workflow, or colocated tooling. Promote to global only after repeated cross-project reuse.\\n\\n## Project First\\n\\nDefault to `<repo>/.ai` when the capability is about:\\n\\n- local architecture\\n- repo-specific testing or verification\\n- team conventions\\n- project tools and workflows\\n\\n## Promote Carefully\\n\\nPromote to `~/.ai` only when:\\n\\n- the same pattern succeeds in more than one repo\\n- the capability is not coupled to local architecture\\n- the global version will not create noise for unrelated projects\\n\\nUse:\\n\\n```bash\\nfclt ai evolve promote EV-00001 --to global --project\\n```\\n\\nThat creates a new global proposal for review. It does not auto-apply the promotion.\\n","skills/capability-evolution/SKILL.md":"---\\ndescription: Convert repeated writeback into concrete fclt capability proposals.\\ntags: [facult, evolution, writeback]\\n---\\n\\n# capability-evolution\\n\\n## When To Use\\nUse this skill when the same missing guidance, weak loop, or recurring win appears often enough that the AI system itself should probably change.\\n\\nDo not wait for a human operator by default if the signal is already clear and the environment permits local AI runtime state to be updated.\\n\\nUse writeback first when the signal is useful but not yet repeated. Use evolution when accumulated writebacks, repeated tool friction, or a clearly missing capability point at a specific target asset or new capability.\\n\\n## Scope Decision\\n\\nChoose `project` when the behavior depends on repo-local architecture or workflow.\\n\\nChoose `global` when the behavior is broadly reusable.\\n\\nIf unsure, start at project scope and promote later with evidence.\\n\\n## Working Flow\\n\\n1. record the strongest writeback\\n2. group or summarize repeated signal\\n3. choose the smallest valid proposal kind\\n4. draft the proposal\\n5. accept only after the target and scope are correct\\n6. apply only when the markdown target is the intended canonical asset\\n\\nUse:\\n\\n```bash\\nfclt ai writeback add ...\\nfclt ai writeback group --by asset\\nfclt ai writeback summarize --by domain\\nfclt ai evolve propose\\nfclt ai evolve draft EV-00001\\nfclt ai evolve draft EV-00001 --append \\"tighten the rule with a concrete verification step\\"\\nfclt ai evolve accept EV-00001\\nfclt ai evolve apply EV-00001\\n```\\n\\nFor background review loops, use:\\n\\n```bash\\nfclt templates init automation learning-review\\nfclt templates init automation evolution-review\\nfclt templates init automation tool-call-audit\\n```\\n\\nIf there is not yet enough repeated signal for evolution, record the writeback and stop there.\\n\\n## Proposal Kind Selection\\n\\n- `update_asset` for tightening existing guidance\\n- `create_asset` for missing instructions or docs\\n- `extract_snippet` for reusable partial guidance\\n- `add_skill` for reusable workflow instruction\\n- `promote_asset` for project-to-global promotion\\n\\nUse task tracking instead of evolution when the main work is an executable tool or product fix that needs an owner, priority, state, or delivery plan. Use evolution for the reusable instruction, skill, or operating-model change that should survive that fix.\\n\\n## Output Contract\\n- repeated signal\\n- proposed asset change\\n- target scope\\n- evidence\\n- smallest useful next step\\n","skills/project-operating-layer-design/SKILL.md":"---\\ndescription: Design or improve a repo-local .ai operating layer.\\ntags: [facult, project, design]\\n---\\n\\n# project-operating-layer-design\\n\\n## When To Use\\nUse this skill when a project needs its own `.ai/` structure, repo-specific instructions, or local bootstrap guidance.\\n\\n## Output Contract\\n- recommended `.ai/` layout\\n- what stays project-local\\n- what stays global\\n- what should remain generated runtime output only\\n"}'
+  '{"AGENTS.global.md":"# Facult Operating Defaults\\n\\nThis machine has a default Facult operating-model layer available.\\n\\nWhen work produces durable friction, weak verification, stale guidance, or a missing skill/tool capability, preserve that signal with `fclt ai writeback ...` when the target and scope are clear. When repeated writebacks or clearly missing capability point at a concrete improvement, use `fclt ai evolve ...` or the `capability-evolution` skill to make a reviewable proposal.\\n\\nFor writeback and evolution, read `@builtin/facult-operating-model/instructions/EVOLUTION.md`.\\nFor learning and writeback defaults, read `@builtin/facult-operating-model/instructions/LEARNING_AND_WRITEBACK.md`.\\nFor deciding whether capability belongs in global or project scope, read `@builtin/facult-operating-model/instructions/PROJECT_CAPABILITY.md`.\\nFor project operating-layer design, read `@builtin/facult-operating-model/instructions/INTEGRATION.md`.\\n\\nBuiltin specialist agents are available for:\\n- writeback curation\\n- evolution planning\\n- scope promotion\\n- integration auditing\\n\\nBuiltin skills are available for:\\n- capability evolution\\n- project operating-layer design\\n","agents/evolution-planner/agent.toml":"name = \\"evolution-planner\\"\\ndescription = \\"Turn repeated writeback into concrete capability proposals.\\"\\n\\ndeveloper_instructions = \\"\\"\\"\\nYou plan capability evolution.\\n\\nPrioritize:\\n- smallest useful change\\n- correct target asset type\\n- correct target scope\\n- evidence that justifies the change\\n- repeated writeback clusters or clearly missing capabilities, not isolated preferences\\n\\nProposal kinds you should consider first:\\n- update_asset\\n- create_asset\\n- extract_snippet\\n- add_skill\\n- promote_asset\\n\\nDefault to project scope when the pattern is repo-local.\\nPromote to global only when reuse is demonstrated and pollution risk is low.\\n\\nReturn concise proposals ordered by expected leverage, including:\\n- proposal kind\\n- target asset\\n- target scope\\n- why this is the smallest durable change\\n\\nDo not escalate to evolution when a single writeback is enough.\\nDo not use evolution as a substitute for executable task tracking when the main need is owner, priority, state, or implementation follow-through.\\n\\"\\"\\"\\n","agents/integration-auditor/agent.toml":"name = \\"integration-auditor\\"\\ndescription = \\"Find where local success can still fail system-wide.\\"\\n\\ndeveloper_instructions = \\"\\"\\"\\nYou audit integration risk.\\n\\nPrioritize:\\n- hidden dependencies\\n- rollout hazards\\n- operational constraints\\n- gaps between local verification and real system behavior\\n\\nReturn concise findings ordered by impact.\\n\\"\\"\\"\\n","agents/scope-promoter/agent.toml":"name = \\"scope-promoter\\"\\ndescription = \\"Decide whether learning belongs at project or global scope.\\"\\n\\ndeveloper_instructions = \\"\\"\\"\\nYou decide scope.\\n\\nPrioritize:\\n- project specificity\\n- cross-project reuse potential\\n- pollution risk from globalizing too early\\n\\nWhen recommending promotion, make the standard path explicit:\\n- keep the source capability in project scope until promotion is approved\\n- create a reviewable global proposal\\n- do not treat promotion as implicit apply\\n\\nReturn concise decisions with rationale.\\n\\"\\"\\"\\n","agents/writeback-curator/agent.toml":"name = \\"writeback-curator\\"\\ndescription = \\"Turn noisy outcomes into high-signal writeback.\\"\\n\\ndeveloper_instructions = \\"\\"\\"\\nYou curate durable writeback.\\n\\nPrioritize:\\n- repeated failures\\n- repeated wins\\n- stale guidance\\n- missing capability edges\\n- tool, skill, MCP, plugin, automation, or instruction friction that repeatedly slows work down\\n\\nFor each recommendation, prefer returning:\\n- suggested writeback kind\\n- best target asset or destination\\n- best scope (`project` or `global`)\\n- the evidence that justifies recording it\\n\\nDo not emit low-signal noise.\\nIf the learning is repo-specific, keep it project-scoped by default.\\nWhen the signal is already strong and the target is clear, prefer recommending direct writeback capture rather than abstract advice.\\nWhen the issue is executable tooling work, recommend task tracking for the fix and writeback only for the reusable operating-model learning.\\n\\"\\"\\"\\n","instructions/EVOLUTION.md":"---\\ndescription: Turn repeated signal into concrete capability changes.\\ntags: [facult, evolution, writeback]\\n---\\n\\n# Evolution\\n\\nUse writeback and evolution to improve the AI operating layer itself.\\n\\nEvolution is the synthesis and change side of the feedback loop. It turns accumulated writebacks, repeated tool friction, stale canonical assets, or clearly missing capability into small reviewable changes to instructions, skills, snippets, agents, or other markdown canonical assets.\\n\\n## When To Record Writeback\\n\\nRecord writeback when one of these is true:\\n\\n- the same failure repeats\\n- the same success pattern repeats\\n- guidance is stale or missing\\n- a prompt or loop has to be restated often\\n- a project-specific pattern looks reusable\\n\\nDo not record low-signal noise:\\n\\n- one-off annoyance with no reuse value\\n- generic \\"could be better\\" commentary\\n- duplicate observations with no new evidence\\n\\nThe intended default is that agents record strong writebacks themselves when the signal is clear enough, rather than only recommending that a user do it manually later.\\n\\nDo not wait for a weekly review to preserve high-signal evidence. Do wait for repeated evidence or a clearly missing capability before drafting a proposal.\\n\\n## Scope\\n\\nChoose `project` scope when the learning depends on:\\n\\n- repo architecture\\n- team workflow\\n- project tooling\\n- local testing or verification behavior\\n\\nChoose `global` scope when the learning is reusable across projects.\\n\\nPromote from project to global only after repeated reuse or strong evidence.\\n\\n## Writeback Kinds\\n\\nCommon kinds:\\n\\n- `weak_verification`\\n- `false_positive`\\n- `missing_context`\\n- `reusable_pattern`\\n- `capability_gap`\\n- `bad_default`\\n\\nEvery good writeback should try to include:\\n\\n- a concrete summary\\n- the best target asset if known\\n- the right scope\\n- domain or tags when useful\\n\\n## Operator Flow\\n\\nTypical workflow:\\n\\n```bash\\nfclt ai writeback add --kind weak_verification --summary \\"Checks were too shallow\\" --asset instruction:VERIFICATION\\nfclt ai writeback group --by asset\\nfclt ai writeback summarize --by domain\\nfclt ai evolve propose\\nfclt ai evolve draft EV-00001\\nfclt ai evolve accept EV-00001\\nfclt ai evolve apply EV-00001\\n```\\n\\nUse `fclt ai evolve draft <id> --append \\"...\\"` to revise a draft while preserving draft history.\\n\\nReview surfaces:\\n\\n- open `~/.ai/writebacks/` and `~/.ai/evolution/` in a Markdown editor for frontmatter-rich global and project-scoped review artifacts\\n- `fclt status --json` for queue/proposal paths, review artifact paths, counts, and active scope\\n- `fclt ai writeback list|show|group|summarize` for raw and clustered signal\\n- `fclt ai evolve list|show|review` for proposal state without applying changes\\n- `fclt templates init automation learning-review` for recurring capture/review\\n- `fclt templates init automation evolution-review` for recurring proposal review\\n- `fclt templates init automation tool-call-audit` for repeated tool-friction review\\n\\nEvolution proposal metadata, markdown drafts, patch artifacts, writeback queues,\\nand journals are runtime state. `fclt` stores JSON queues, proposal records,\\ndraft refs, patches, and journals in machine-local Facult state. It mirrors\\nhuman-readable review artifacts into global `~/.ai/writebacks/...` and\\n`~/.ai/evolution/...`, including project-scoped artifacts under\\n`projects/<slug-hash>/` with cwd/project metadata in frontmatter. Canonical\\nassets in `~/.ai` or `<repo>/.ai` should only change when a proposal is applied.\\n\\n## Default Agent Behavior\\n\\nUse the smallest action that fits the signal:\\n\\n1. record one strong writeback when there is a clear durable learning\\n2. use `writeback-curator` when the target, kind, or scope is ambiguous\\n3. use `capability-evolution` or `evolution-planner` when repeated signal should become a proposal\\n4. do not draft or apply proposals just because a writeback exists; require repeated evidence or a clearly missing capability\\n\\nAvoid creating writeback/evolution noise for one-off nits, vague preferences, or speculative ideas without evidence.\\n\\nWhen the friction is executable product/tooling work that needs ownership,\\npriority, state, or implementation follow-through, create or update a real task\\nsystem item instead of forcing it into capability evolution. Use evolution for\\nthe reusable operating-layer change.\\n\\n## Proposal Kinds\\n\\nCurrent supported proposal kinds:\\n\\n- `update_asset`\\n- `create_asset`\\n- `extract_snippet`\\n- `add_skill`\\n- `promote_asset`\\n\\nUse the smallest durable change that fits the evidence.\\n\\n## Review And Apply Rules\\n\\n- draft before apply\\n- accept before apply\\n- prefer the smallest safe change\\n- keep reviewable evidence tied to source writebacks\\n- do not globalize project behavior too early\\n- do not apply high-risk global instruction, skill, plugin, or non-COS changes without explicit review/approval\\n\\nApply is for markdown canonical assets only. If the target is wrong, revise the proposal rather than forcing it through.\\n","instructions/INTEGRATION.md":"---\\ndescription: Detect where local success can still fail at integration boundaries.\\ntags: [facult, integration, verification]\\n---\\n\\n# Integration\\n\\nDistinguish local correctness from system correctness. Check hidden dependencies, rollout order, and operational constraints before calling work done.\\n","instructions/LEARNING_AND_WRITEBACK.md":"---\\ndescription: Preserve durable signal and record writeback when the operating layer should learn.\\ntags: [facult, learning, writeback]\\n---\\n\\n# Learning And Writeback\\n\\nUse this when work produces a durable decision, failure, success pattern, or missing guardrail that should outlive the current task.\\n\\nThis is the capture side of the feedback loop. The goal is to let normal agent work produce reusable signal without requiring a human to manually restate every friction point later.\\n\\n## Default Behavior\\n\\nThe normal path should be agent-driven.\\n\\nIf you can clearly answer:\\n\\n- what was learned\\n- why it matters\\n- where it should land\\n- whether it belongs in `project` or `global`\\n\\nthen record the writeback instead of only suggesting that someone should do it later.\\n\\nUse:\\n\\n```bash\\nfclt ai writeback add --kind <kind> --summary \\"<summary>\\" --asset <asset-selector>\\n```\\n\\nThe writeback queue is runtime state, not canonical source. `fclt` stores JSON\\nqueue state in machine-local Facult state so sandboxed agents can record durable\\nfriction without mutating canonical assets unless an evolution proposal is later\\nreviewed and applied.\\n\\nEvery writeback also refreshes a Markdown review artifact under the global\\n`~/.ai/writebacks/...` tree. Global signal lands in `~/.ai/writebacks/global/`;\\nproject-scoped signal lands in `~/.ai/writebacks/projects/<slug-hash>/` with\\nfrontmatter for scope, project root, cwd, target asset, status, tags, evidence,\\nand timestamps. Do not write writeback review artifacts into a repo-local `.ai`;\\nrepo-local state should contribute project metadata and evidence, not bundled\\nprivate review files.\\n\\nProject-scoped writebacks should usually be recorded from the repo that produced\\nthe evidence. Global writebacks should be reserved for shared doctrine, shared\\nskills, shared agents, tool behavior, or cross-project capability gaps.\\n\\n## Record Writeback When\\n\\n- the same failure or weak loop appears again\\n- a reusable success pattern shows up\\n- guidance is clearly stale or missing\\n- a repo-local behavior probably belongs in project capability\\n- a cross-project behavior probably belongs in global capability\\n- a skill, tool, MCP, plugin, automation, or instruction gap repeatedly slows work down\\n- an agent has to restate the same workaround, verification rule, or review rule\\n\\n## Do Not Record Writeback For\\n\\n- one-off annoyance with no durable value\\n- weak commentary with no target\\n- speculative ideas without evidence\\n- duplicate noise with no new signal\\n\\n## Follow Through\\n\\n- prefer one strong writeback over many weak ones\\n- mention the writeback id when summarizing what changed\\n- escalate to `capability-evolution` or `fclt ai evolve ...` only when the signal is repeated or clearly points at a durable capability change\\n- use `fclt ai writeback group --by asset` or `fclt ai writeback summarize --by domain` to review accumulated signal before proposing broad changes\\n- use scheduled `learning-review`, `evolution-review`, or `tool-call-audit` automations when the signal should be reviewed in the background\\n","instructions/PROJECT_CAPABILITY.md":"---\\ndescription: Decide what belongs in repo-local .ai versus the global store.\\ntags: [facult, project, scope]\\n---\\n\\n# Project Capability\\n\\nPrefer project scope when the guidance depends on repo architecture, team workflow, or colocated tooling. Promote to global only after repeated cross-project reuse.\\n\\n## Project First\\n\\nDefault to `<repo>/.ai` when the capability is about:\\n\\n- local architecture\\n- repo-specific testing or verification\\n- team conventions\\n- project tools and workflows\\n\\n## Promote Carefully\\n\\nPromote to `~/.ai` only when:\\n\\n- the same pattern succeeds in more than one repo\\n- the capability is not coupled to local architecture\\n- the global version will not create noise for unrelated projects\\n\\nUse:\\n\\n```bash\\nfclt ai evolve promote EV-00001 --to global --project\\n```\\n\\nThat creates a new global proposal for review. It does not auto-apply the promotion.\\n","skills/capability-evolution/SKILL.md":"---\\ndescription: Convert repeated writeback into concrete fclt capability proposals.\\ntags: [facult, evolution, writeback]\\n---\\n\\n# capability-evolution\\n\\n## When To Use\\nUse this skill when the same missing guidance, weak loop, or recurring win appears often enough that the AI system itself should probably change.\\n\\nDo not wait for a human operator by default if the signal is already clear and the environment permits local AI runtime state to be updated.\\n\\nUse writeback first when the signal is useful but not yet repeated. Use evolution when accumulated writebacks, repeated tool friction, or a clearly missing capability point at a specific target asset or new capability.\\n\\n## Scope Decision\\n\\nChoose `project` when the behavior depends on repo-local architecture or workflow.\\n\\nChoose `global` when the behavior is broadly reusable.\\n\\nIf unsure, start at project scope and promote later with evidence.\\n\\n## Working Flow\\n\\n1. record the strongest writeback\\n2. group or summarize repeated signal\\n3. choose the smallest valid proposal kind\\n4. draft the proposal\\n5. accept only after the target and scope are correct\\n6. apply only when the markdown target is the intended canonical asset\\n\\nUse:\\n\\n```bash\\nfclt ai writeback add ...\\nfclt ai writeback group --by asset\\nfclt ai writeback summarize --by domain\\nfclt ai evolve propose\\nfclt ai evolve draft EV-00001\\nfclt ai evolve draft EV-00001 --append \\"tighten the rule with a concrete verification step\\"\\nfclt ai evolve accept EV-00001\\nfclt ai evolve apply EV-00001\\n```\\n\\nFor background review loops, use:\\n\\n```bash\\nfclt templates init automation learning-review\\nfclt templates init automation evolution-review\\nfclt templates init automation tool-call-audit\\n```\\n\\nIf there is not yet enough repeated signal for evolution, record the writeback and stop there.\\n\\n## Proposal Kind Selection\\n\\n- `update_asset` for tightening existing guidance\\n- `create_asset` for missing instructions or docs\\n- `extract_snippet` for reusable partial guidance\\n- `add_skill` for reusable workflow instruction\\n- `promote_asset` for project-to-global promotion\\n\\nUse task tracking instead of evolution when the main work is an executable tool or product fix that needs an owner, priority, state, or delivery plan. Use evolution for the reusable instruction, skill, or operating-model change that should survive that fix.\\n\\n## Output Contract\\n- repeated signal\\n- proposed asset change\\n- target scope\\n- evidence\\n- smallest useful next step\\n","skills/project-operating-layer-design/SKILL.md":"---\\ndescription: Design or improve a repo-local .ai operating layer.\\ntags: [facult, project, design]\\n---\\n\\n# project-operating-layer-design\\n\\n## When To Use\\nUse this skill when a project needs its own `.ai/` structure, repo-specific instructions, or local bootstrap guidance.\\n\\n## Output Contract\\n- recommended `.ai/` layout\\n- what stays project-local\\n- what stays global\\n- what should remain generated runtime output only\\n"}'
 ) as Record<string, string>;

package/src/manage.ts

@@ -137,6 +137,7 @@ export interface SyncOptions {
   tool?: string;
   dryRun?: boolean;
   builtinConflictMode?: "warn" | "overwrite";
+  adoptLive?: boolean;
 }
 
 const MANAGED_VERSION = 1 as const;
@@ -2421,12 +2422,14 @@ async function syncSkillSymlinks({
   rootDir,
   tool,
   dryRun,
+  adoptLive,
 }: {
   homeDir: string;
   toolSkillsDir: string;
   rootDir: string;
   tool: string;
   dryRun?: boolean;
+  adoptLive?: boolean;
 }): Promise<SkillSymlinkPlan> {
   const plan = await planSkillSymlinkChanges({
     homeDir,
@@ -2438,10 +2441,12 @@ async function syncSkillSymlinks({
     return plan;
   }
 
-  const adoptedConflicts = await adoptSkillSymlinkConflictsIntoCanonical({
-    rootDir,
-    conflicts: plan.conflicts,
-  });
+  const adoptedConflicts = adoptLive
+    ? await adoptSkillSymlinkConflictsIntoCanonical({
+        rootDir,
+        conflicts: plan.conflicts,
+      })
+    : [];
   const adoptedNames = new Set(
     adoptedConflicts.map((conflict) => conflict.name)
   );
@@ -3646,7 +3651,8 @@ function logRenderedConflicts(
 function logSkillSymlinkConflicts(
   tool: string,
   conflicts: SkillSymlinkConflict[],
-  dryRun?: boolean
+  dryRun?: boolean,
+  mode: "adopt" | "skip" = "skip"
 ) {
   for (const conflict of conflicts) {
     const verb =
@@ -3654,9 +3660,13 @@ function logSkillSymlinkConflicts(
         ? dryRun
           ? "would preserve"
           : "preserved"
-        : dryRun
-          ? "would adopt"
-          : "adopted";
+        : mode === "adopt"
+          ? dryRun
+            ? "would adopt"
+            : "adopted"
+          : dryRun
+            ? "would skip"
+            : "skipped";
     const state =
       conflict.reason === "unmanaged"
         ? "it is not in canonical skill state"
@@ -3667,7 +3677,7 @@ function logSkillSymlinkConflicts(
       ? ` (canonical ${conflict.canonicalPath})`
       : "";
     console.warn(
-      `${tool}: ${verb} skill ${conflict.name} from ${conflict.livePath}${canonical} because ${state}.`
+      `${tool}: ${verb} skill ${conflict.name} from ${conflict.livePath}${canonical} because ${state}.${mode === "skip" && conflict.reason !== "disabled" ? ' Rerun with "--adopt-live" to import it into canonical state.' : ""}`
     );
   }
 }
@@ -4470,6 +4480,7 @@ async function syncManagedToolEntry({
   rootDir,
   dryRun,
   builtinConflictMode,
+  adoptLive,
 }: {
   homeDir: string;
   tool: string;
@@ -4477,6 +4488,7 @@ async function syncManagedToolEntry({
   rootDir: string;
   dryRun?: boolean;
   builtinConflictMode?: "warn" | "overwrite";
+  adoptLive?: boolean;
 }) {
   const correlationId = randomUUID();
   const baseLedger = syncLedgerBase({
@@ -4515,14 +4527,15 @@ async function syncManagedToolEntry({
     automationDir: entry.automationDir,
   });
 
-  const adoptedSkills = dryRun
-    ? []
-    : await repairManagedCanonicalContent({
-        homeDir,
-        rootDir,
-        tool,
-        entry,
-      });
+  const adoptedSkills =
+    dryRun || !adoptLive
+      ? []
+      : await repairManagedCanonicalContent({
+          homeDir,
+          rootDir,
+          tool,
+          entry,
+        });
 
   const skillPlan = entry.skillsDir
     ? await syncSkillSymlinks({
@@ -4531,6 +4544,7 @@ async function syncManagedToolEntry({
         rootDir,
         tool,
         dryRun,
+        adoptLive,
       })
     : { add: [], remove: [], conflicts: [], adopted: [] };
   const skillLedgerEvents = collectSkillLedgerEvents({
@@ -4895,8 +4909,8 @@ async function syncManagedToolEntry({
     logRenderedConflicts(tool, configRendered.conflicts);
     logRenderedConflicts(tool, mcpRendered.conflicts);
     logRenderedConflicts(tool, pluginRendered.conflicts);
-    logSkillSymlinkConflicts(tool, skillPlan.adopted);
-    logSkillSymlinkConflicts(tool, skillPlan.conflicts);
+    logSkillSymlinkConflicts(tool, skillPlan.adopted, false, "adopt");
+    logSkillSymlinkConflicts(tool, skillPlan.conflicts, false, "skip");
 
     updateRenderedTargetState({
       entry,
@@ -5004,6 +5018,7 @@ export async function syncManagedTools(opts: SyncOptions = {}) {
       rootDir,
       dryRun: opts.dryRun,
       builtinConflictMode: opts.builtinConflictMode,
+      adoptLive: opts.adoptLive,
     });
   }
 
@@ -5196,16 +5211,20 @@ export async function syncCommand(argv: string[]) {
     console.log(`fclt sync — sync managed tools with canonical state
 
 Usage:
-  fclt sync [tool] [--dry-run] [--builtin-conflicts overwrite] [--root PATH|--global|--project]
+  fclt sync [tool] [--dry-run] [--adopt-live] [--builtin-conflicts overwrite] [--root PATH|--global|--project]
 
 Options:
   --dry-run   Show what would change
+  --adopt-live   Import live tool content into canonical state before rendering
   --builtin-conflicts overwrite   Replace locally modified builtin-backed rendered files
 `);
     return;
   }
   const tool = parsed.argv.find((arg) => !arg.startsWith("-"));
   const dryRun = parsed.argv.includes("--dry-run");
+  const adoptLive =
+    parsed.argv.includes("--adopt-live") ||
+    parsed.argv.includes("--adopt-live-skills");
   const builtinConflictIndex = parsed.argv.indexOf("--builtin-conflicts");
   let builtinConflictMode: "warn" | "overwrite" | undefined;
   if (builtinConflictIndex !== -1) {
@@ -5221,6 +5240,7 @@ Options:
     await syncManagedTools({
       tool,
       dryRun,
+      adoptLive,
       builtinConflictMode,
       rootDir: resolveCliContextRoot({
         rootArg: parsed.rootArg,

package/src/paths.ts

@@ -238,7 +238,7 @@ export function facultStateDir(
   return join(resolvedRoot, ".facult");
 }
 
-function machineStateProjectKey(
+export function machineStateProjectKey(
   rootDir: string,
   home: string = defaultHomeDir()
 ): string {
@@ -413,6 +413,37 @@ export function facultAiDraftDir(
   return join(facultAiRuntimeScopeDir(home, rootDir), "evolution", "drafts");
 }
 
+export function facultAiReviewScopeDir(
+  artifactDir: "writebacks" | "evolution",
+  home: string = defaultHomeDir(),
+  rootDir?: string
+): string {
+  const resolvedRoot = rootDir ?? facultRootDir(home);
+  const projectRoot = projectRootFromAiRoot(resolvedRoot, home);
+  return projectRoot
+    ? join(
+        preferredGlobalAiRoot(home),
+        artifactDir,
+        "projects",
+        machineStateProjectKey(resolvedRoot, home)
+      )
+    : join(preferredGlobalAiRoot(home), artifactDir, "global");
+}
+
+export function facultAiWritebackReviewDir(
+  home: string = defaultHomeDir(),
+  rootDir?: string
+): string {
+  return facultAiReviewScopeDir("writebacks", home, rootDir);
+}
+
+export function facultAiEvolutionReviewDir(
+  home: string = defaultHomeDir(),
+  rootDir?: string
+): string {
+  return facultAiReviewScopeDir("evolution", home, rootDir);
+}
+
 export function facultConfigPath(home: string = defaultHomeDir()): string {
   return join(preferredGlobalFacultStateDir(home), "config.json");
 }

package/src/remote.ts

@@ -383,7 +383,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 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.
+- Scope: default to project writeback only when the repo has a project-local \`.ai\` root for capability context. If a local writable repo is missing one, bootstrap baseline project AI state with \`fclt templates init project-ai\` before retrying project-scoped writeback. Writeback/evolution review artifacts still belong under global \`~/.ai/writebacks/projects/...\` and \`~/.ai/evolution/projects/...\`, not inside the repo-local \`.ai\`. 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.
@@ -409,7 +409,7 @@ 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 attempting project-scoped writeback, verify the cwd has a repo-local \`.ai\` root for capability context. If it does not and the cwd is a local writable repo, run \`fclt templates init project-ai\` from that repo root, then continue. Do not write writeback/evolution review artifacts into the repo-local \`.ai\`; fclt mirrors them under global \`~/.ai/writebacks/projects/...\` and \`~/.ai/evolution/projects/...\` with cwd/project metadata. 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.

package/src/status.ts

@@ -3,10 +3,12 @@ import { dirname, join } from "node:path";
 import { parseCliContextArgs, resolveCliContextRoot } from "./cli-context";
 import { loadManagedState } from "./manage";
 import {
+  facultAiEvolutionReviewDir,
   facultAiGraphPath,
   facultAiIndexPath,
   facultAiProposalDir,
   facultAiWritebackQueuePath,
+  facultAiWritebackReviewDir,
   facultMachineStateDir,
   facultRootDir,
   projectRootFromAiRoot,
@@ -41,8 +43,10 @@ export interface FacultStatus {
   };
   writeback: {
     queuePath: string;
+    reviewDir: string;
     pendingCount: number;
     proposalDir: string;
+    evolutionReviewDir: string;
     proposalCount: number;
   };
   issues: StatusIssue[];
@@ -175,6 +179,8 @@ export async function buildStatus(opts?: {
   const graphPath = facultAiGraphPath(homeDir, contextRoot);
   const queuePath = facultAiWritebackQueuePath(homeDir, contextRoot);
   const proposalDir = facultAiProposalDir(homeDir, contextRoot);
+  const reviewDir = facultAiWritebackReviewDir(homeDir, contextRoot);
+  const evolutionReviewDir = facultAiEvolutionReviewDir(homeDir, contextRoot);
   const managed = await loadManagedState(homeDir, contextRoot);
 
   const issues: StatusIssue[] = [];
@@ -222,8 +228,10 @@ export async function buildStatus(opts?: {
     },
     writeback: {
       queuePath,
+      reviewDir,
       pendingCount: await countPendingWritebacks(homeDir, contextRoot),
       proposalDir,
+      evolutionReviewDir,
       proposalCount: await countActiveProposals(homeDir, contextRoot),
     },
     issues,
@@ -247,6 +255,8 @@ function printStatus(status: FacultStatus) {
   console.log(
     `writeback: ${status.writeback.pendingCount} queued, ${status.writeback.proposalCount} proposals`
   );
+  console.log(`writeback review: ${status.writeback.reviewDir}`);
+  console.log(`evolution review: ${status.writeback.evolutionReviewDir}`);
   if (status.issues.length > 0) {
     console.log("issues:");
     for (const issue of status.issues) {