facult 2.13.4 → 2.13.9

package/README.md

@@ -89,9 +89,11 @@ fclt doctor --repair
 ```
 
 `doctor --json` is read-only. `doctor --repair` is the self-heal path for legacy
-state, broken canonical global guidance, missing review artifacts, and stale
-local integration layout. Canonical repairs keep a backup under
-`.ai/.facult/backups/doctor/`.
+state, broken rendered global guidance, missing review artifacts, and stale
+local integration layout. It validates the rendered form of `AGENTS.global.md`
+while preserving that file as a composable source template, and it repairs
+leaked `${refs.*}` placeholders in direct-readable instruction files. Canonical
+repairs keep a backup under `.ai/.facult/backups/doctor/`.
 
 Update an installed binary:
 
@@ -149,8 +151,8 @@ fclt status --project
 Create individual capability units:
 
 ```bash
-fclt templates init instruction BUN
-fclt templates init snippet global/lang/bun
+fclt templates init instruction LANGUAGE
+fclt templates init snippet global/policy/review
 fclt templates init skill project-review
 fclt templates init agent review-operator
 ```
@@ -212,7 +214,7 @@ Canonical capability can include:
 Refs let markdown point at canonical assets without hard-coding paths:
 
 ```text
-@ai/instructions/BUN.md
+@ai/instructions/LANGUAGE.md
 @project/instructions/TESTING.md
 @builtin/facult-operating-model/instructions/WORK_UNITS.md
 ```
@@ -220,8 +222,8 @@ Refs let markdown point at canonical assets without hard-coding paths:
 Snippet markers let repeated blocks stay independently editable:
 
 ```md
-<!-- fclty:global/lang/bun -->
-<!-- /fclty:global/lang/bun -->
+<!-- fclty:global/policy/review -->
+<!-- /fclty:global/policy/review -->
 ```
 
 The rule is simple: target the smallest unit that needs to change. Use instructions for doctrine, snippets for repeated blocks, skills for workflows, agents for roles, MCP/tool config for interfaces, and automations for scheduled loops.

package/assets/packs/facult-operating-model/AGENTS.global.md

@@ -1,41 +1,35 @@
-# Facult Operating Defaults
-
-This machine has a default Facult operating-model layer available.
-
-Default behavior:
-
-- Treat meaningful work as a work unit: know the goal, acceptance criteria, required context, constraints, evidence, output artifact, verification path, and likely writeback target.
-- Use the strongest practical feedback loop for the risk. Do not treat shallow success as proof when a better check is available.
-- When 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.
-- Use `fclt ai evolve ...` or the `capability-evolution` skill only when repeated writebacks, a clearly missing capability, or a stale canonical asset point at a concrete improvement.
-- Keep one-off preferences and speculative ideas out of evolution. Use writeback, notes, or task tracking instead.
-- Use project scope for repo-specific workflow and global scope for reusable cross-project doctrine. Promote project capability only after evidence shows reuse.
-- Use Linear or another task system for executable product/tooling work that needs ownership, priority, state, or delivery follow-through.
-- Keep writeback/evolution runtime and review artifacts in the global `.ai` review tree; do not commit generated writeback queues or private review artifacts into project repos.
-
-For work-unit framing, read `@builtin/facult-operating-model/instructions/WORK_UNITS.md`.
-For composing refs, snippets, instructions, skills, agents, MCP, and automations as evolvable units, read `@builtin/facult-operating-model/instructions/CAPABILITY_COMPOSITION.md`.
-For writeback and evolution, read `@builtin/facult-operating-model/instructions/EVOLUTION.md`.
-For learning and writeback defaults, read `@builtin/facult-operating-model/instructions/LEARNING_AND_WRITEBACK.md`.
-For deciding whether capability belongs in global or project scope, read `@builtin/facult-operating-model/instructions/PROJECT_CAPABILITY.md`.
-For project operating-layer design, read `@builtin/facult-operating-model/instructions/INTEGRATION.md`.
-
-Builtin specialist agents are available for:
-- writeback curation
-- evolution planning
-- scope promotion
-- integration auditing
-
-Builtin skills are available for:
-- capability evolution
-- project operating-layer design
-
-Useful health and review commands:
-
-```bash
-fclt doctor --json
-fclt status --json
-fclt ai writeback list
-fclt ai writeback group --by asset
-fclt ai evolve list
-```
+# Global Agent Instructions
+
+## Working mode
+
+<!-- fclty:global/baseline -->
+<!-- /fclty:global/baseline -->
+
+<!-- fclty:global/core/work-units -->
+<!-- /fclty:global/core/work-units -->
+
+<!-- fclty:global/core/feedback-loops -->
+<!-- /fclty:global/core/feedback-loops -->
+
+<!-- fclty:global/core/verification -->
+<!-- /fclty:global/core/verification -->
+
+<!-- fclty:global/core/writeback -->
+<!-- /fclty:global/core/writeback -->
+
+## Shared instruction sources
+
+- For work-unit definition and scope clarification, read ${refs.work_units}.
+- For identifying, improving, and validating feedback loops, read ${refs.feedback_loops}.
+- For verification and anti-false-positive checks, read ${refs.verification}.
+- For learning, decisions, and writeback, read ${refs.learning_writeback}.
+- For capability evolution, proposal kinds, and `facult ai` workflow, read ${refs.evolution}.
+- For deciding whether something belongs in global or project scope, read ${refs.project_capability}.
+- Add private language, coding, or writing refs in local config only when they belong to the user's own operating layer.
+
+## Layering
+
+- Treat this file as the global baseline.
+- Treat repo-level `AGENTS.md` files as more specific additions layered after this file.
+- Repo-level files may add or refine project-specific behavior, but they should not weaken global defaults for rigor, verification, or writeback discipline.
+- If a closer `AGENTS.override.md` exists, follow it as the most specific instructions file in that directory while still preserving the global baseline unless the closer file explicitly tightens it.

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

@@ -29,8 +29,8 @@ The main units are:
 
 Examples:
 
-- `@ai/instructions/BUN.md` for shared Bun preferences.
-- `@ai/instructions/RUST.md` for shared Rust preferences.
+- `@ai/instructions/LANGUAGE.md` for a user-owned language/tooling preference.
+- `@ai/instructions/REVIEW.md` for a user-owned review standard.
 - `@project/instructions/TESTING.md` for repo-specific test policy.
 - `<!-- fclty:global/codex/baseline -->` for a shared rendered block.
 
@@ -56,7 +56,7 @@ Target the smallest affected unit.
 Good writeback targets are graph-backed selectors when possible:
 
 ```bash
-fclt ai writeback add --kind missing_context --summary "Bun guidance did not cover test runner selection." --asset instruction:BUN
+fclt ai writeback add --kind missing_context --summary "Language guidance did not cover test runner selection." --asset instruction:LANGUAGE
 fclt ai writeback add --kind reusable_pattern --summary "Project test policy should become a shared verification snippet." --asset @project/instructions/TESTING.md
 fclt ai writeback add --kind bad_default --summary "The review automation escalated one-off preferences." --asset automation:evolution-review
 ```
@@ -65,7 +65,7 @@ Use `fclt ai evolve ...` only after repeated signal, a clearly missing capabilit
 
 ## Agent Defaults
 
-When an agent sees a repeated preference like "use Bun for JS projects" or "prefer Cargo nextest for Rust tests", it should not bury that in chat. It should identify whether the durable unit is:
+When an agent sees a repeated language, framework, or test preference, it should not bury that in chat. It should identify whether the durable unit is:
 
 - a global instruction
 - a project instruction

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

@@ -64,9 +64,9 @@ Every good writeback should try to include:
 
 Good target examples:
 
-- `instruction:BUN` when shared Bun guidance is stale or missing
+- `instruction:LANGUAGE` when shared language/tooling guidance is stale or missing
 - `@project/instructions/TESTING.md` when repo test policy needs project-scoped evolution
-- `snippet:global/lang/bun` when a repeated rendered block should be fixed or extracted
+- `snippet:global/policy/review` when a repeated rendered block should be fixed or extracted
 - `skill:capability-evolution` when a workflow skill is missing steps or examples
 - `automation:evolution-review` when the scheduled review loop is noisy or incomplete
 
@@ -135,7 +135,7 @@ Use the smallest durable change that fits the evidence.
 Examples:
 
 - `update_asset`: fix a stale instruction, snippet, agent, or automation markdown asset.
-- `create_asset`: add a missing instruction such as `BUN.md` or `RUST.md`.
+- `create_asset`: add a missing instruction such as `LANGUAGE.md` or `REVIEW.md`.
 - `extract_snippet`: move repeated guidance out of several docs into one snippet.
 - `add_skill`: create a workflow when instructions are not enough.
 - `promote_asset`: move a proven project instruction/snippet/skill toward global reuse.

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

@@ -63,7 +63,7 @@ Target the smallest composable unit that explains the friction:
 - a cross-project behavior probably belongs in global capability
 - a skill, tool, MCP, plugin, automation, or instruction gap repeatedly slows work down
 - an agent has to restate the same workaround, verification rule, or review rule
-- a repeated preference should become an atomic instruction such as `BUN.md`, `RUST.md`, or a project-specific testing policy
+- a repeated preference should become an atomic user-owned instruction or project-specific testing policy
 
 ## Do Not Record Writeback For
 

package/assets/packs/facult-operating-model/snippets/global/baseline.md

@@ -0,0 +1,3 @@
+- Preserve existing user changes unless asked to rewrite them.
+- Prefer small, reviewable diffs and verify meaningful changes before claiming success.
+- State constraints, risks, and follow-up steps directly.

package/assets/packs/facult-operating-model/snippets/global/core/feedback-loops.md

@@ -0,0 +1,10 @@
+- For any task, identify the highest-signal feedback loops available.
+- Prefer loops that can verify progress, falsify weak assumptions, and expose failure early.
+- Do not rely on a single shallow positive signal if stronger verification exists.
+- If the available loop is stale, weak, noisy, or easy to game, improve it or say what is missing.
+- When useful, leave behind a stronger loop than the one you started with.
+- Treat verification, evaluation, and writeback as part of the work, not cleanup after it.
+- For work-unit clarification, read ${refs.work_units}.
+- For verification guidance, read ${refs.verification}.
+- For learning and writeback, read ${refs.learning_writeback}.
+- For deeper guidance, read ${refs.feedback_loops}.

package/assets/packs/facult-operating-model/snippets/global/core/verification.md

@@ -0,0 +1,6 @@
+- Treat verification as part of the work, not a final checkbox.
+- Prefer the strongest available proof that matches the real risk.
+- Make clear what has actually been verified and what remains assumed.
+- Distrust shallow green signals when stronger checks are available.
+- If the current harness is stale, weak, or misleading, say so and improve it where possible.
+- For deeper guidance, read ${refs.verification}.

package/assets/packs/facult-operating-model/snippets/global/core/work-units.md

@@ -0,0 +1,6 @@
+- Treat every task as a work unit, not just a request.
+- A work unit should have a goal, acceptance criteria, required context, constraints, signals or evidence, an output artifact, and a verification path.
+- If any of those are missing and the gap blocks correctness, surface it early and try to recover it.
+- Prefer making the work unit more explicit before increasing execution speed.
+- If the task is vague, ambiguous, or overloaded, narrow it before acting.
+- For deeper guidance, read ${refs.work_units}.

package/assets/packs/facult-operating-model/snippets/global/core/writeback.md

@@ -0,0 +1,9 @@
+- Do not end at output if something important was learned.
+- Preserve decisions, failures, successes, and reusable signal when they will improve future work.
+- Prefer writing to a real destination over leaving knowledge in chat.
+- When useful, leave behind better docs, tests, evals, prompts, notes, or follow-up tasks.
+- When a high-signal learning clearly points at a canonical asset or durable destination, record a writeback before ending the task.
+- Prefer one strong writeback over many weak ones.
+- If you can name the target asset, the expected scope, and the actual signal, use `fclt ai writeback add ...` instead of merely mentioning that writeback would be useful.
+- If repeated signal is already accumulating, use the `capability-evolution` skill or `fclt ai evolve ...` flow to turn it into a reviewable proposal.
+- For deeper guidance, read ${refs.learning_writeback}.

package/docs/composable-capability.md

@@ -18,8 +18,8 @@ Use `instructions/` for reusable markdown doctrine.
 Examples:
 
 ```text
-~/.ai/instructions/BUN.md
-~/.ai/instructions/RUST.md
+~/.ai/instructions/LANGUAGE.md
+~/.ai/instructions/REVIEW.md
 <repo>/.ai/instructions/TESTING.md
 ```
 
@@ -29,7 +29,7 @@ Examples:
 
 ```text
 ~/.ai/snippets/global/codex/baseline.md
-~/.ai/snippets/global/lang/bun.md
+~/.ai/snippets/global/policy/review.md
 <repo>/.ai/snippets/global/project/testing.md
 ```
 
@@ -40,7 +40,7 @@ Use `skills/` for executable workflows, `agents/` for delegated roles, `mcp/` fo
 Canonical refs let a markdown asset point at another asset without hard-coding machine paths:
 
 ```text
-@ai/instructions/BUN.md
+@ai/instructions/LANGUAGE.md
 @project/instructions/TESTING.md
 @builtin/facult-operating-model/instructions/WORK_UNITS.md
 ```
@@ -53,7 +53,7 @@ Config-backed refs are useful when the concrete path should be named in `config.
 version = 1
 
 [refs]
-language_defaults = "@ai/instructions/BUN.md"
+language_defaults = "@ai/instructions/LANGUAGE.md"
 project_testing = "@project/instructions/TESTING.md"
 ```
 
@@ -64,22 +64,22 @@ Rendered markdown can use those refs through the render context when a tool adap
 Snippets use paired HTML markers:
 
 ```md
-<!-- fclty:global/lang/bun -->
-<!-- /fclty:global/lang/bun -->
+<!-- fclty:global/policy/review -->
+<!-- /fclty:global/policy/review -->
 ```
 
 The marker above resolves to:
 
 ```text
-snippets/global/lang/bun.md
+snippets/global/policy/review.md
 ```
 
 Create and inspect snippets with:
 
 ```bash
-fclt templates init snippet global/lang/bun
+fclt templates init snippet global/policy/review
 fclt snippets list
-fclt snippets show global/lang/bun
+fclt snippets show global/policy/review
 fclt snippets sync --dry-run AGENTS.global.md
 ```
 
@@ -90,22 +90,21 @@ Use snippets when the same block appears in more than one rendered doc, or when
 Create a new instruction scaffold with:
 
 ```bash
-fclt templates init instruction BUN
-fclt templates init instruction lang/RUST
+fclt templates init instruction LANGUAGE
+fclt templates init instruction REVIEW
 ```
 
 That writes:
 
 ```text
-instructions/BUN.md
-instructions/lang/RUST.md
+instructions/LANGUAGE.md
+instructions/REVIEW.md
 ```
 
 An instruction can include refs, snippet markers, examples, and writeback targeting guidance. Keep one instruction focused on one reusable domain. For example:
 
-- `BUN.md`: JavaScript runtime/package/test preferences.
-- `RUST.md`: Rust formatting, linting, and test preferences.
-- `WRITING.md`: voice and editorial rules.
+- `LANGUAGE.md`: user-owned language or tooling preferences.
+- `REVIEW.md`: user-owned review standards.
 - `VERIFICATION.md`: proof standards.
 
 ## Composition Pattern
@@ -116,8 +115,8 @@ A global `AGENTS.global.md` can stay short and compose units:
 # Global Agent Instructions
 
 For work-unit framing, read `@ai/instructions/WORK_UNITS.md`.
-For JS/Bun projects, read `@ai/instructions/BUN.md`.
-For Rust projects, read `@ai/instructions/RUST.md`.
+For language/tooling preferences, read `@ai/instructions/LANGUAGE.md`.
+For review standards, read `@ai/instructions/REVIEW.md`.
 
 <!-- fclty:global/codex/baseline -->
 <!-- /fclty:global/codex/baseline -->
@@ -148,7 +147,7 @@ Target the smallest unit that actually needs to change:
 Examples:
 
 ```bash
-fclt ai writeback add --kind missing_context --summary "Bun guidance did not cover test runner selection." --asset instruction:BUN
+fclt ai writeback add --kind missing_context --summary "Language guidance did not cover test runner selection." --asset instruction:LANGUAGE
 fclt ai writeback add --kind reusable_pattern --summary "Project testing policy should become a shared verification snippet." --asset @project/instructions/TESTING.md
 fclt ai evolve propose
 ```
@@ -162,9 +161,9 @@ Use these surfaces:
 ```bash
 fclt list instructions --global
 fclt list snippets --global
-fclt show instruction:BUN
+fclt show instruction:LANGUAGE
 fclt graph deps AGENTS.global.md
-fclt graph dependents @ai/instructions/BUN.md
+fclt graph dependents @ai/instructions/LANGUAGE.md
 fclt ai writeback group --by asset
 fclt ai evolve list
 ```

package/docs/reference.md

@@ -26,6 +26,14 @@ sync policy, invalid canonical global guidance, and missing Markdown review
 artifacts. Destructive-looking canonical repairs keep a backup under
 `.ai/.facult/backups/doctor/`.
 
+`doctor` renders `AGENTS.global.md` in memory before judging it. That file is a
+source template, so empty `fclty` blocks and `${refs.work_units}` placeholders
+are valid when they render into filled, concrete tool guidance. `doctor` flags
+the global docs only when the rendered output still has empty managed sections,
+unresolved placeholders, or marker errors. It also checks direct-readable
+instruction files for leaked `${refs.*}` placeholders and can repair known refs
+there with backups.
+
 ## Graph
 
 ```bash

package/package.json

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

package/src/agents.ts

@@ -147,6 +147,22 @@ export async function loadRenderContext(
     PROJECT_SLUG: projectSlug ?? "",
     TARGET_PATH: targetPath ?? "",
     TARGET_TOOL: targetTool ?? "",
+    refs: {
+      evolution: join(rootDir, "instructions", "EVOLUTION.md"),
+      feedback_loops: join(rootDir, "instructions", "FEEDBACK_LOOPS.md"),
+      learning_writeback: join(
+        rootDir,
+        "instructions",
+        "LEARNING_AND_WRITEBACK.md"
+      ),
+      project_capability: join(
+        rootDir,
+        "instructions",
+        "PROJECT_CAPABILITY.md"
+      ),
+      verification: join(rootDir, "instructions", "VERIFICATION.md"),
+      work_units: join(rootDir, "instructions", "WORK_UNITS.md"),
+    },
   };
 
   let context = contextBase;

package/src/builtin-assets.ts

@@ -1,5 +1,6 @@
 // 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\\nDefault behavior:\\n\\n- Treat meaningful work as a work unit: know the goal, acceptance criteria, required context, constraints, evidence, output artifact, verification path, and likely writeback target.\\n- Use the strongest practical feedback loop for the risk. Do not treat shallow success as proof when a better check is available.\\n- When 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.\\n- Use `fclt ai evolve ...` or the `capability-evolution` skill only when repeated writebacks, a clearly missing capability, or a stale canonical asset point at a concrete improvement.\\n- Keep one-off preferences and speculative ideas out of evolution. Use writeback, notes, or task tracking instead.\\n- Use project scope for repo-specific workflow and global scope for reusable cross-project doctrine. Promote project capability only after evidence shows reuse.\\n- Use Linear or another task system for executable product/tooling work that needs ownership, priority, state, or delivery follow-through.\\n- Keep writeback/evolution runtime and review artifacts in the global `.ai` review tree; do not commit generated writeback queues or private review artifacts into project repos.\\n\\nFor work-unit framing, read `@builtin/facult-operating-model/instructions/WORK_UNITS.md`.\\nFor composing refs, snippets, instructions, skills, agents, MCP, and automations as evolvable units, read `@builtin/facult-operating-model/instructions/CAPABILITY_COMPOSITION.md`.\\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\\nUseful health and review commands:\\n\\n```bash\\nfclt doctor --json\\nfclt status --json\\nfclt ai writeback list\\nfclt ai writeback group --by asset\\nfclt ai evolve list\\n```\\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/CAPABILITY_COMPOSITION.md":"---\\ndescription: \\"Compose small capability units across global and project roots, then evolve the smallest affected unit.\\"\\ntags: [\\"facult\\", \\"composition\\", \\"refs\\", \\"snippets\\", \\"instructions\\"]\\n---\\n\\n# Capability Composition\\n\\nUse `fclt` capability as small units that can be composed, inspected, rendered, and evolved independently.\\n\\nThe main units are:\\n\\n- instructions: standalone markdown doctrine such as language preferences, verification rules, or review standards\\n- snippets: small markdown partials inserted into one or more rendered docs\\n- skills: task-specific workflows with `SKILL.md`\\n- agents: focused role manifests\\n- MCP definitions: tool interfaces and their safe auth shape\\n- automations: scheduled review or maintenance loops\\n- tool rules/config: tool-specific defaults and policy\\n\\n## Composition Rules\\n\\n- Keep reusable doctrine in `instructions/`.\\n- Keep repeated paragraphs or policy blocks in `snippets/`.\\n- Keep workflow execution in `skills/`.\\n- Keep persona or delegation behavior in `agents/`.\\n- Keep tool wiring in `mcp/` and `tools/<tool>/`.\\n- Compose broad agent docs from refs and snippets instead of copying text by hand.\\n- Prefer one narrow reusable unit over one large instruction file that mixes unrelated domains.\\n\\nExamples:\\n\\n- `@ai/instructions/BUN.md` for shared Bun preferences.\\n- `@ai/instructions/RUST.md` for shared Rust preferences.\\n- `@project/instructions/TESTING.md` for repo-specific test policy.\\n- `<!-- fclty:global/codex/baseline -->` for a shared rendered block.\\n\\n## Scope\\n\\nUse global scope for capability that should follow the user across projects.\\n\\nUse project scope for capability that belongs to a repo, team workflow, architecture, or local test harness.\\n\\nPromote project capability to global only when repeated evidence shows reuse across projects. Do not globalize a project quirk just because it worked once.\\n\\n## Writeback and Evolution\\n\\nTarget the smallest affected unit.\\n\\n- If a paragraph is reused in several rendered docs, target the snippet.\\n- If a domain rule is wrong, target the instruction.\\n- If a workflow is incomplete, target the skill.\\n- If a delegated role is unclear, target the agent.\\n- If a tool interface is missing or unsafe, target the MCP or tool config.\\n- If a scheduled review loop is noisy or missing context, target the automation.\\n\\nGood writeback targets are graph-backed selectors when possible:\\n\\n```bash\\nfclt ai writeback add --kind missing_context --summary \\"Bun guidance did not cover test runner selection.\\" --asset instruction:BUN\\nfclt ai writeback add --kind reusable_pattern --summary \\"Project test policy should become a shared verification snippet.\\" --asset @project/instructions/TESTING.md\\nfclt ai writeback add --kind bad_default --summary \\"The review automation escalated one-off preferences.\\" --asset automation:evolution-review\\n```\\n\\nUse `fclt ai evolve ...` only after repeated signal, a clearly missing capability, or a stale canonical asset points at a concrete change. Prefer the smallest valid proposal kind: `update_asset`, `create_asset`, `extract_snippet`, `add_skill`, or `promote_asset`.\\n\\n## Agent Defaults\\n\\nWhen an agent sees a repeated preference like \\"use Bun for JS projects\\" or \\"prefer Cargo nextest for Rust tests\\", it should not bury that in chat. It should identify whether the durable unit is:\\n\\n- a global instruction\\n- a project instruction\\n- a snippet reused by rendered docs\\n- a skill workflow\\n- a project-to-global promotion candidate\\n\\nThen it should record writeback against that unit, or draft a proposal when the evidence is already strong enough.\\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\\nUse capability composition when choosing the target. Instructions, snippets, skills, agents, MCP/tool config, and automations are separate units. Target the smallest unit that actually needs to change instead of rewriting a broad agent doc.\\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\\nGood target examples:\\n\\n- `instruction:BUN` when shared Bun guidance is stale or missing\\n- `@project/instructions/TESTING.md` when repo test policy needs project-scoped evolution\\n- `snippet:global/lang/bun` when a repeated rendered block should be fixed or extracted\\n- `skill:capability-evolution` when a workflow skill is missing steps or examples\\n- `automation:evolution-review` when the scheduled review loop is noisy or incomplete\\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 `fclt` 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\\nExamples:\\n\\n- `update_asset`: fix a stale instruction, snippet, agent, or automation markdown asset.\\n- `create_asset`: add a missing instruction such as `BUN.md` or `RUST.md`.\\n- `extract_snippet`: move repeated guidance out of several docs into one snippet.\\n- `add_skill`: create a workflow when instructions are not enough.\\n- `promote_asset`: move a proven project instruction/snippet/skill toward global reuse.\\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 shared-tool 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 `fclt` 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\\nTarget the smallest composable unit that explains the friction:\\n\\n- instruction: domain guidance, preferences, verification rules, or review doctrine\\n- snippet: repeated markdown block used by more than one rendered doc\\n- skill: workflow execution steps or examples\\n- agent: delegated role behavior\\n- MCP/tool config: tool interface, auth shape, or rendered integration\\n- automation: scheduled review loop, cadence, prompt, or memory\\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- a repeated preference should become an atomic instruction such as `BUN.md`, `RUST.md`, or a project-specific testing policy\\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","instructions/WORK_UNITS.md":"---\\ndescription: \\"Define work units so agent tasks have a clear goal, evidence path, artifact, and writeback target.\\"\\ntags: [\\"work-units\\", \\"planning\\", \\"verification\\", \\"writeback\\"]\\n---\\n\\n# Work Units\\n\\nA work unit is the smallest coherent unit of agent work that can be understood, verified, and preserved.\\n\\nIt is not just the user\'s latest sentence. It is the operational shape around that sentence: what is being changed, why it matters, what evidence is needed, what artifact should remain, and how future agents should benefit from the result.\\n\\n## Minimum Contract\\n\\nA well-formed work unit names:\\n\\n- goal: the outcome the user needs\\n- acceptance criteria: what must be true when the work is done\\n- required context: source files, docs, systems, messages, or prior decisions needed for correctness\\n- constraints: permissions, privacy, compatibility, deadlines, ownership, or scope limits\\n- signals or evidence: checks that can confirm progress or falsify assumptions\\n- output artifact: code, docs, proposal, issue, note, draft, or report\\n- verification path: commands, review surfaces, manual checks, or source-of-truth reads\\n- writeback target: where durable learning belongs if the work teaches something reusable\\n\\nIf one of these is missing and the gap blocks correctness, surface the gap early and recover it before moving faster.\\n\\n## Why It Exists\\n\\nWork-unit framing prevents shallow completion. It helps agents avoid:\\n\\n- changing files before understanding the target\\n- treating a weak green signal as proof\\n- losing reusable learning in chat\\n- creating duplicate tasks or proposals\\n- turning one-off preferences into global rules\\n- pushing project-specific details into global capability\\n\\n## How To Use It\\n\\nFor simple tasks, keep the work unit implicit but still verify the result.\\n\\nFor ambiguous, high-impact, or multi-step tasks, make the work unit explicit before executing. A compact form is enough:\\n\\n```text\\nGoal:\\nAcceptance:\\nContext:\\nConstraints:\\nEvidence:\\nArtifact:\\nVerification:\\nWriteback:\\n```\\n\\nUse the smallest framing that makes the task correct. Do not turn every request into paperwork.\\n\\n## Writeback\\n\\nWhen the work reveals durable friction, missing capability, stale guidance, or a repeatable workflow, prefer one strong writeback over many weak ones.\\n\\nUse `fclt ai writeback add ...` when the target asset, scope, and evidence are clear. Use `fclt ai evolve ...` only when repeated signal supports a concrete proposal.\\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"}'
+  // biome-ignore lint/suspicious/noTemplateCurlyInString: Built-in templates intentionally contain literal render placeholders.
+  '{"AGENTS.global.md":"# Global Agent Instructions\\n\\n## Working mode\\n\\n<!-- fclty:global/baseline -->\\n<!-- /fclty:global/baseline -->\\n\\n<!-- fclty:global/core/work-units -->\\n<!-- /fclty:global/core/work-units -->\\n\\n<!-- fclty:global/core/feedback-loops -->\\n<!-- /fclty:global/core/feedback-loops -->\\n\\n<!-- fclty:global/core/verification -->\\n<!-- /fclty:global/core/verification -->\\n\\n<!-- fclty:global/core/writeback -->\\n<!-- /fclty:global/core/writeback -->\\n\\n## Shared instruction sources\\n\\n- For work-unit definition and scope clarification, read ${refs.work_units}.\\n- For identifying, improving, and validating feedback loops, read ${refs.feedback_loops}.\\n- For verification and anti-false-positive checks, read ${refs.verification}.\\n- For learning, decisions, and writeback, read ${refs.learning_writeback}.\\n- For capability evolution, proposal kinds, and `facult ai` workflow, read ${refs.evolution}.\\n- For deciding whether something belongs in global or project scope, read ${refs.project_capability}.\\n- Add private language, coding, or writing refs in local config only when they belong to the user\'s own operating layer.\\n\\n## Layering\\n\\n- Treat this file as the global baseline.\\n- Treat repo-level `AGENTS.md` files as more specific additions layered after this file.\\n- Repo-level files may add or refine project-specific behavior, but they should not weaken global defaults for rigor, verification, or writeback discipline.\\n- If a closer `AGENTS.override.md` exists, follow it as the most specific instructions file in that directory while still preserving the global baseline unless the closer file explicitly tightens it.\\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/CAPABILITY_COMPOSITION.md":"---\\ndescription: \\"Compose small capability units across global and project roots, then evolve the smallest affected unit.\\"\\ntags: [\\"facult\\", \\"composition\\", \\"refs\\", \\"snippets\\", \\"instructions\\"]\\n---\\n\\n# Capability Composition\\n\\nUse `fclt` capability as small units that can be composed, inspected, rendered, and evolved independently.\\n\\nThe main units are:\\n\\n- instructions: standalone markdown doctrine such as language preferences, verification rules, or review standards\\n- snippets: small markdown partials inserted into one or more rendered docs\\n- skills: task-specific workflows with `SKILL.md`\\n- agents: focused role manifests\\n- MCP definitions: tool interfaces and their safe auth shape\\n- automations: scheduled review or maintenance loops\\n- tool rules/config: tool-specific defaults and policy\\n\\n## Composition Rules\\n\\n- Keep reusable doctrine in `instructions/`.\\n- Keep repeated paragraphs or policy blocks in `snippets/`.\\n- Keep workflow execution in `skills/`.\\n- Keep persona or delegation behavior in `agents/`.\\n- Keep tool wiring in `mcp/` and `tools/<tool>/`.\\n- Compose broad agent docs from refs and snippets instead of copying text by hand.\\n- Prefer one narrow reusable unit over one large instruction file that mixes unrelated domains.\\n\\nExamples:\\n\\n- `@ai/instructions/LANGUAGE.md` for a user-owned language/tooling preference.\\n- `@ai/instructions/REVIEW.md` for a user-owned review standard.\\n- `@project/instructions/TESTING.md` for repo-specific test policy.\\n- `<!-- fclty:global/codex/baseline -->` for a shared rendered block.\\n\\n## Scope\\n\\nUse global scope for capability that should follow the user across projects.\\n\\nUse project scope for capability that belongs to a repo, team workflow, architecture, or local test harness.\\n\\nPromote project capability to global only when repeated evidence shows reuse across projects. Do not globalize a project quirk just because it worked once.\\n\\n## Writeback and Evolution\\n\\nTarget the smallest affected unit.\\n\\n- If a paragraph is reused in several rendered docs, target the snippet.\\n- If a domain rule is wrong, target the instruction.\\n- If a workflow is incomplete, target the skill.\\n- If a delegated role is unclear, target the agent.\\n- If a tool interface is missing or unsafe, target the MCP or tool config.\\n- If a scheduled review loop is noisy or missing context, target the automation.\\n\\nGood writeback targets are graph-backed selectors when possible:\\n\\n```bash\\nfclt ai writeback add --kind missing_context --summary \\"Language guidance did not cover test runner selection.\\" --asset instruction:LANGUAGE\\nfclt ai writeback add --kind reusable_pattern --summary \\"Project test policy should become a shared verification snippet.\\" --asset @project/instructions/TESTING.md\\nfclt ai writeback add --kind bad_default --summary \\"The review automation escalated one-off preferences.\\" --asset automation:evolution-review\\n```\\n\\nUse `fclt ai evolve ...` only after repeated signal, a clearly missing capability, or a stale canonical asset points at a concrete change. Prefer the smallest valid proposal kind: `update_asset`, `create_asset`, `extract_snippet`, `add_skill`, or `promote_asset`.\\n\\n## Agent Defaults\\n\\nWhen an agent sees a repeated language, framework, or test preference, it should not bury that in chat. It should identify whether the durable unit is:\\n\\n- a global instruction\\n- a project instruction\\n- a snippet reused by rendered docs\\n- a skill workflow\\n- a project-to-global promotion candidate\\n\\nThen it should record writeback against that unit, or draft a proposal when the evidence is already strong enough.\\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\\nUse capability composition when choosing the target. Instructions, snippets, skills, agents, MCP/tool config, and automations are separate units. Target the smallest unit that actually needs to change instead of rewriting a broad agent doc.\\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\\nGood target examples:\\n\\n- `instruction:LANGUAGE` when shared language/tooling guidance is stale or missing\\n- `@project/instructions/TESTING.md` when repo test policy needs project-scoped evolution\\n- `snippet:global/policy/review` when a repeated rendered block should be fixed or extracted\\n- `skill:capability-evolution` when a workflow skill is missing steps or examples\\n- `automation:evolution-review` when the scheduled review loop is noisy or incomplete\\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 `fclt` 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\\nExamples:\\n\\n- `update_asset`: fix a stale instruction, snippet, agent, or automation markdown asset.\\n- `create_asset`: add a missing instruction such as `LANGUAGE.md` or `REVIEW.md`.\\n- `extract_snippet`: move repeated guidance out of several docs into one snippet.\\n- `add_skill`: create a workflow when instructions are not enough.\\n- `promote_asset`: move a proven project instruction/snippet/skill toward global reuse.\\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 shared-tool 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 `fclt` 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\\nTarget the smallest composable unit that explains the friction:\\n\\n- instruction: domain guidance, preferences, verification rules, or review doctrine\\n- snippet: repeated markdown block used by more than one rendered doc\\n- skill: workflow execution steps or examples\\n- agent: delegated role behavior\\n- MCP/tool config: tool interface, auth shape, or rendered integration\\n- automation: scheduled review loop, cadence, prompt, or memory\\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- a repeated preference should become an atomic user-owned instruction or project-specific testing policy\\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","instructions/WORK_UNITS.md":"---\\ndescription: \\"Define work units so agent tasks have a clear goal, evidence path, artifact, and writeback target.\\"\\ntags: [\\"work-units\\", \\"planning\\", \\"verification\\", \\"writeback\\"]\\n---\\n\\n# Work Units\\n\\nA work unit is the smallest coherent unit of agent work that can be understood, verified, and preserved.\\n\\nIt is not just the user\'s latest sentence. It is the operational shape around that sentence: what is being changed, why it matters, what evidence is needed, what artifact should remain, and how future agents should benefit from the result.\\n\\n## Minimum Contract\\n\\nA well-formed work unit names:\\n\\n- goal: the outcome the user needs\\n- acceptance criteria: what must be true when the work is done\\n- required context: source files, docs, systems, messages, or prior decisions needed for correctness\\n- constraints: permissions, privacy, compatibility, deadlines, ownership, or scope limits\\n- signals or evidence: checks that can confirm progress or falsify assumptions\\n- output artifact: code, docs, proposal, issue, note, draft, or report\\n- verification path: commands, review surfaces, manual checks, or source-of-truth reads\\n- writeback target: where durable learning belongs if the work teaches something reusable\\n\\nIf one of these is missing and the gap blocks correctness, surface the gap early and recover it before moving faster.\\n\\n## Why It Exists\\n\\nWork-unit framing prevents shallow completion. It helps agents avoid:\\n\\n- changing files before understanding the target\\n- treating a weak green signal as proof\\n- losing reusable learning in chat\\n- creating duplicate tasks or proposals\\n- turning one-off preferences into global rules\\n- pushing project-specific details into global capability\\n\\n## How To Use It\\n\\nFor simple tasks, keep the work unit implicit but still verify the result.\\n\\nFor ambiguous, high-impact, or multi-step tasks, make the work unit explicit before executing. A compact form is enough:\\n\\n```text\\nGoal:\\nAcceptance:\\nContext:\\nConstraints:\\nEvidence:\\nArtifact:\\nVerification:\\nWriteback:\\n```\\n\\nUse the smallest framing that makes the task correct. Do not turn every request into paperwork.\\n\\n## Writeback\\n\\nWhen the work reveals durable friction, missing capability, stale guidance, or a repeatable workflow, prefer one strong writeback over many weak ones.\\n\\nUse `fclt ai writeback add ...` when the target asset, scope, and evidence are clear. Use `fclt ai evolve ...` only when repeated signal supports a concrete proposal.\\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","snippets/global/baseline.md":"- Preserve existing user changes unless asked to rewrite them.\\n- Prefer small, reviewable diffs and verify meaningful changes before claiming success.\\n- State constraints, risks, and follow-up steps directly.\\n","snippets/global/core/feedback-loops.md":"- For any task, identify the highest-signal feedback loops available.\\n- Prefer loops that can verify progress, falsify weak assumptions, and expose failure early.\\n- Do not rely on a single shallow positive signal if stronger verification exists.\\n- If the available loop is stale, weak, noisy, or easy to game, improve it or say what is missing.\\n- When useful, leave behind a stronger loop than the one you started with.\\n- Treat verification, evaluation, and writeback as part of the work, not cleanup after it.\\n- For work-unit clarification, read ${refs.work_units}.\\n- For verification guidance, read ${refs.verification}.\\n- For learning and writeback, read ${refs.learning_writeback}.\\n- For deeper guidance, read ${refs.feedback_loops}.\\n","snippets/global/core/verification.md":"- Treat verification as part of the work, not a final checkbox.\\n- Prefer the strongest available proof that matches the real risk.\\n- Make clear what has actually been verified and what remains assumed.\\n- Distrust shallow green signals when stronger checks are available.\\n- If the current harness is stale, weak, or misleading, say so and improve it where possible.\\n- For deeper guidance, read ${refs.verification}.\\n","snippets/global/core/work-units.md":"- Treat every task as a work unit, not just a request.\\n- A work unit should have a goal, acceptance criteria, required context, constraints, signals or evidence, an output artifact, and a verification path.\\n- If any of those are missing and the gap blocks correctness, surface it early and try to recover it.\\n- Prefer making the work unit more explicit before increasing execution speed.\\n- If the task is vague, ambiguous, or overloaded, narrow it before acting.\\n- For deeper guidance, read ${refs.work_units}.\\n","snippets/global/core/writeback.md":"- Do not end at output if something important was learned.\\n- Preserve decisions, failures, successes, and reusable signal when they will improve future work.\\n- Prefer writing to a real destination over leaving knowledge in chat.\\n- When useful, leave behind better docs, tests, evals, prompts, notes, or follow-up tasks.\\n- When a high-signal learning clearly points at a canonical asset or durable destination, record a writeback before ending the task.\\n- Prefer one strong writeback over many weak ones.\\n- If you can name the target asset, the expected scope, and the actual signal, use `fclt ai writeback add ...` instead of merely mentioning that writeback would be useful.\\n- If repeated signal is already accumulating, use the `capability-evolution` skill or `fclt ai evolve ...` flow to turn it into a reviewable proposal.\\n- For deeper guidance, read ${refs.learning_writeback}.\\n"}'
 ) as Record<string, string>;

package/src/doctor.ts

@@ -15,6 +15,7 @@ import {
 } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
+import { renderCanonicalText } from "./agents";
 import {
   ensureAiGraphPath,
   ensureAiIndexPath,
@@ -41,6 +42,7 @@ import {
   loadConfiguredProjectSyncTools,
   writeProjectSyncPolicy,
 } from "./project-sync";
+import { renderSnippetText } from "./snippets";
 import { packageVersion } from "./status";
 
 const TOML_FILE_SUFFIX_RE = /\.toml$/;
@@ -104,6 +106,9 @@ export interface DoctorReport {
     evolutionReviewDirExists: boolean;
     canonicalGlobalDocsValid: boolean;
     canonicalGlobalDocsIssueCodes: string[];
+    canonicalTemplateRefsValid: boolean;
+    canonicalTemplateRefsIssueCodes: string[];
+    canonicalTemplateRefsIssuePaths: string[];
     projectSyncRepairNeeded: boolean;
     projectSyncRepairTools: string[];
   };
@@ -446,6 +451,24 @@ async function repairLegacyCodexAuthoringLayout(args: {
   return { changed, conflicts };
 }
 
+interface CanonicalTemplateIssue {
+  path: string;
+  relPath: string;
+  code: string;
+  message: string;
+}
+
+interface CanonicalTemplateRefsInspection {
+  valid: boolean;
+  issues: CanonicalTemplateIssue[];
+}
+
+interface CanonicalTemplateRefsRepair {
+  changed: boolean;
+  repairedPaths: string[];
+  backupPaths: string[];
+}
+
 async function repairCanonicalGlobalDocs(args: {
   home: string;
   rootDir: string;
@@ -468,11 +491,35 @@ 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 ensureAiIndexPath({ homeDir: args.home, rootDir: args.rootDir });
   await ensureAiGraphPath({ homeDir: args.home, rootDir: args.rootDir });
   return { changed: true, backupPath };
 }
 
+async function copyMissingBuiltinOperatingModelSnippets(
+  rootDir: string
+): Promise<void> {
+  const relPaths = [
+    "snippets/global/baseline.md",
+    "snippets/global/core/work-units.md",
+    "snippets/global/core/feedback-loops.md",
+    "snippets/global/core/verification.md",
+    "snippets/global/core/writeback.md",
+  ];
+  const sourceRoot = facultBuiltinPackRoot();
+
+  for (const relPath of relPaths) {
+    const sourcePath = join(sourceRoot, relPath);
+    const targetPath = join(rootDir, relPath);
+    if (await pathExists(targetPath)) {
+      continue;
+    }
+    await mkdir(dirname(targetPath), { recursive: true });
+    await copyFile(sourcePath, targetPath);
+  }
+}
+
 async function listProjectSkillNames(rootDir: string): Promise<string[]> {
   const skillsDir = join(rootDir, "skills");
   const entries = await readdir(skillsDir, { withFileTypes: true }).catch(
@@ -547,6 +594,7 @@ async function hasProjectGlobalDocs(rootDir: string): Promise<boolean> {
 }
 
 const UNRESOLVED_TEMPLATE_REF_RE = /\$\{[^}\n]+\}/g;
+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;
 
@@ -562,19 +610,37 @@ async function inspectCanonicalGlobalDocs(rootDir: string): Promise<{
 
   const text = await readFile(pathValue, "utf8");
   const issues: DoctorIssue[] = [];
-  const unresolvedRefs = new Set(text.match(UNRESOLVED_TEMPLATE_REF_RE) ?? []);
+  const withSnippets = await renderSnippetText({
+    text,
+    filePath: pathValue,
+    rootDir,
+  });
+  for (const error of withSnippets.errors) {
+    issues.push({
+      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`.",
+    });
+  }
+  const rendered = await renderCanonicalText(withSnippets.text, {
+    rootDir,
+  });
+  const unresolvedRefs = new Set(
+    rendered.match(UNRESOLVED_TEMPLATE_REF_RE) ?? []
+  );
   if (unresolvedRefs.size > 0) {
     issues.push({
       severity: "warning",
       code: "canonical-global-docs-unresolved-template",
       message:
-        "Canonical AGENTS.global.md contains unresolved template references.",
-      fix: "Review the file or refresh the built-in operating model with `fclt templates init operating-model --global --force`.",
+        "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`.",
     });
   }
 
   const emptySections: string[] = [];
-  for (const match of text.matchAll(FCLTY_BLOCK_RE)) {
+  for (const match of rendered.matchAll(FCLTY_BLOCK_RE)) {
     const key = match[1]?.trim();
     const body = match[2]?.trim();
     if (key && !body) {
@@ -585,8 +651,8 @@ async function inspectCanonicalGlobalDocs(rootDir: string): Promise<{
     issues.push({
       severity: "warning",
       code: "canonical-global-docs-empty-managed-sections",
-      message: `Canonical AGENTS.global.md has empty fclty managed sections: ${emptySections.join(", ")}.`,
-      fix: "Review the file or refresh the built-in operating model with `fclt templates init operating-model --global --force`.",
+      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`.",
     });
   }
 
@@ -597,6 +663,124 @@ async function inspectCanonicalGlobalDocs(rootDir: string): Promise<{
   };
 }
 
+const CANONICAL_TEMPLATE_REF_DIRS = ["instructions"] as const;
+
+function canonicalRefValues(rootDir: string): Record<string, string> {
+  return {
+    evolution: join(rootDir, "instructions", "EVOLUTION.md"),
+    feedback_loops: join(rootDir, "instructions", "FEEDBACK_LOOPS.md"),
+    learning_writeback: join(
+      rootDir,
+      "instructions",
+      "LEARNING_AND_WRITEBACK.md"
+    ),
+    project_capability: join(rootDir, "instructions", "PROJECT_CAPABILITY.md"),
+    verification: join(rootDir, "instructions", "VERIFICATION.md"),
+    work_units: join(rootDir, "instructions", "WORK_UNITS.md"),
+  };
+}
+
+function resolveKnownCanonicalRefs(text: string, rootDir: string): string {
+  const refs = canonicalRefValues(rootDir);
+  return text.replace(UNRESOLVED_REFS_TEMPLATE_RE, (match, key: string) => {
+    return refs[key] ?? match;
+  });
+}
+
+async function listCanonicalMarkdownFiles(rootDir: string): Promise<string[]> {
+  const out: string[] = [];
+
+  async function visit(dir: string): Promise<void> {
+    const entries = await readdir(dir, { withFileTypes: true }).catch(
+      () => [] as import("node:fs").Dirent[]
+    );
+    for (const entry of entries) {
+      if (entry.name.startsWith(".")) {
+        continue;
+      }
+      const pathValue = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await visit(pathValue);
+      } else if (entry.isFile() && entry.name.endsWith(".md")) {
+        out.push(pathValue);
+      }
+    }
+  }
+
+  for (const relDir of CANONICAL_TEMPLATE_REF_DIRS) {
+    await visit(join(rootDir, relDir));
+  }
+  return out.sort((a, b) => a.localeCompare(b));
+}
+
+function relPathFromRoot(rootDir: string, pathValue: string): string {
+  return pathValue.startsWith(`${rootDir}/`)
+    ? pathValue.slice(rootDir.length + 1)
+    : pathValue;
+}
+
+async function inspectCanonicalTemplateRefs(
+  rootDir: string
+): Promise<CanonicalTemplateRefsInspection> {
+  const files = await listCanonicalMarkdownFiles(rootDir);
+  const issues: CanonicalTemplateIssue[] = [];
+
+  for (const pathValue of files) {
+    const text = await readFile(pathValue, "utf8");
+    const refs = new Set(text.match(UNRESOLVED_REFS_TEMPLATE_RE) ?? []);
+    if (refs.size === 0) {
+      continue;
+    }
+    const relPath = relPathFromRoot(rootDir, pathValue);
+    issues.push({
+      path: pathValue,
+      relPath,
+      code: "canonical-source-unresolved-template-ref",
+      message: `${relPath} contains unresolved template refs: ${[...refs].join(", ")}.`,
+    });
+  }
+
+  return {
+    valid: issues.length === 0,
+    issues,
+  };
+}
+
+async function repairCanonicalTemplateRefs(
+  rootDir: string
+): Promise<CanonicalTemplateRefsRepair> {
+  const files = await listCanonicalMarkdownFiles(rootDir);
+  const repairedPaths: string[] = [];
+  const backupPaths: string[] = [];
+
+  for (const pathValue of files) {
+    const before = await readFile(pathValue, "utf8");
+    const after = resolveKnownCanonicalRefs(before, rootDir);
+    if (after === before) {
+      continue;
+    }
+    const relPath = relPathFromRoot(rootDir, pathValue);
+    const backupPath = join(
+      rootDir,
+      ".facult",
+      "backups",
+      "doctor",
+      `${relPath.replaceAll("/", "__")}.${timestampForBackup()}`
+    );
+    await mkdir(dirname(backupPath), { recursive: true });
+    await copyFile(pathValue, backupPath);
+    await writeFile(pathValue, after, "utf8");
+    repairedPaths.push(relPath);
+    backupPaths.push(backupPath);
+  }
+
+  return {
+    changed: repairedPaths.length > 0,
+    repairedPaths,
+    backupPaths,
+  };
+}
+
 async function hasProjectToolRules(
   rootDir: string,
   tool: string
@@ -778,6 +962,7 @@ export async function buildDoctorReport(opts?: {
     writebackReviewDirExists,
     evolutionReviewDirExists,
     canonicalGlobalDocs,
+    canonicalTemplateRefs,
     projectSyncPlan,
   ] = await Promise.all([
     pathExists(rootDir),
@@ -788,6 +973,7 @@ export async function buildDoctorReport(opts?: {
     pathExists(writebackReviewDir),
     pathExists(evolutionReviewDir),
     inspectCanonicalGlobalDocs(rootDir),
+    inspectCanonicalTemplateRefs(rootDir),
     planProjectSyncPolicyRepair({ home, rootDir }),
   ]);
 
@@ -836,6 +1022,23 @@ export async function buildDoctorReport(opts?: {
     });
   }
 
+  for (const issue of canonicalTemplateRefs.issues) {
+    issues.push({
+      severity: "warning",
+      code: issue.code,
+      message: issue.message,
+      fix: "Run fclt doctor --repair to resolve known refs into concrete paths, then review any remaining placeholders.",
+    });
+  }
+  if (!canonicalTemplateRefs.valid) {
+    actions.push({
+      id: "repair-canonical-template-refs",
+      label: "Repair unresolved canonical template refs",
+      command: "fclt doctor --repair",
+      risk: "canonical_write",
+    });
+  }
+
   if (generatedOnlyProjectRoot) {
     issues.push({
       severity: "error",
@@ -927,7 +1130,7 @@ export async function buildDoctorReport(opts?: {
     state = "project_generated_only";
   } else if (!(rootExists && canonicalSourceExists)) {
     state = "uninitialized";
-  } else if (!canonicalGlobalDocs.valid) {
+  } else if (!(canonicalGlobalDocs.valid && canonicalTemplateRefs.valid)) {
     state = "canonical_source_attention";
   } else if (!(writebackReviewDirExists && evolutionReviewDirExists)) {
     state = "partial_global_config";
@@ -971,6 +1174,13 @@ export async function buildDoctorReport(opts?: {
       canonicalGlobalDocsIssueCodes: canonicalGlobalDocs.issues.map(
         (issue) => issue.code
       ),
+      canonicalTemplateRefsValid: canonicalTemplateRefs.valid,
+      canonicalTemplateRefsIssueCodes: canonicalTemplateRefs.issues.map(
+        (issue) => issue.code
+      ),
+      canonicalTemplateRefsIssuePaths: canonicalTemplateRefs.issues.map(
+        (issue) => issue.relPath
+      ),
       projectSyncRepairNeeded: projectSyncPlan.needed,
       projectSyncRepairTools,
     },
@@ -1029,6 +1239,7 @@ export async function doctorCommand(argv: string[]) {
     let codexAuthoringConflicts: string[] = [];
     let canonicalGlobalDocsRepaired = false;
     let canonicalGlobalDocsBackupPath: string | undefined;
+    let canonicalTemplateRefsRepair: CanonicalTemplateRefsRepair | undefined;
     let reviewArtifactsRefreshed:
       | {
           writebackCount: number;
@@ -1061,6 +1272,7 @@ export async function doctorCommand(argv: string[]) {
       });
       canonicalGlobalDocsRepaired = globalDocsRepair.changed;
       canonicalGlobalDocsBackupPath = globalDocsRepair.backupPath;
+      canonicalTemplateRefsRepair = await repairCanonicalTemplateRefs(rootDir);
       const { refreshAiReviewArtifacts } = await import("./ai");
       reviewArtifactsRefreshed = await refreshAiReviewArtifacts({
         homeDir: home,
@@ -1132,6 +1344,12 @@ export async function doctorCommand(argv: string[]) {
         `Repaired canonical AGENTS.global.md from the built-in operating model. Backup: ${canonicalGlobalDocsBackupPath}`
       );
     }
+    if (canonicalTemplateRefsRepair?.changed) {
+      console.log("Resolved canonical template refs in:");
+      for (const repairedPath of canonicalTemplateRefsRepair.repairedPaths) {
+        console.log(`- ${repairedPath}`);
+      }
+    }
     if (reviewArtifactsRefreshed) {
       console.log(
         `Refreshed AI review artifacts: ${reviewArtifactsRefreshed.writebackCount} writebacks in ${reviewArtifactsRefreshed.writebackReviewDir}, ${reviewArtifactsRefreshed.proposalCount} proposals in ${reviewArtifactsRefreshed.evolutionReviewDir}.`
@@ -1157,6 +1375,18 @@ export async function doctorCommand(argv: string[]) {
         return;
       }
     }
+    const canonicalTemplateRefs = await inspectCanonicalTemplateRefs(rootDir);
+    if (!canonicalTemplateRefs.valid) {
+      for (const issue of canonicalTemplateRefs.issues) {
+        console.log(
+          `${issue.message} Run \`fclt doctor --repair\` to resolve known refs into concrete paths, then review any remaining placeholders.`
+        );
+      }
+      if (!repair) {
+        process.exitCode = 1;
+        return;
+      }
+    }
     if (await isGeneratedOnlyProjectRoot({ home, rootDir })) {
       console.log(
         "Project .ai root contains generated state only. Canonical project source is missing, so managed project sync should be treated as unsafe until source is initialized, restored, or management is detached."

package/src/global-docs.ts

@@ -228,18 +228,25 @@ async function renderSourceTarget(args: {
   tool: string;
 }): Promise<string> {
   const raw = await Bun.file(args.sourcePath).text();
+  const builtinRoot = facultBuiltinPackRoot();
+  const sourceRoot = args.sourcePath.startsWith(`${builtinRoot}/`)
+    ? builtinRoot
+    : args.rootDir;
   const withSnippets = await renderSnippetText({
     text: raw,
     filePath: args.sourcePath,
-    rootDir: args.rootDir,
+    rootDir: sourceRoot,
   });
   if (withSnippets.errors.length) {
     throw new Error(withSnippets.errors.join("\n"));
   }
   return await renderCanonicalText(withSnippets.text, {
     homeDir: args.homeDir,
-    rootDir: args.rootDir,
-    projectRoot: projectRootFromAiRoot(args.rootDir, args.homeDir) ?? undefined,
+    rootDir: sourceRoot,
+    projectRoot:
+      sourceRoot === args.rootDir
+        ? (projectRootFromAiRoot(args.rootDir, args.homeDir) ?? undefined)
+        : undefined,
     targetTool: args.tool,
     targetPath: args.targetPath,
   });

package/src/remote.ts

@@ -394,17 +394,12 @@ Ship reliable changes quickly while keeping behavior predictable.
       type: "snippet",
       title: "Snippet Template",
       description:
-        "Reusable snippet block template for coding standards and communication style.",
+        "Reusable snippet block template for a compact quality checklist.",
       version: "1.0.0",
       tags: ["template", "dx", "snippet"],
       snippet: {
-        marker: "team/codingstyle",
-        content: `## Coding Style
-- Prefer explicit, descriptive names over abbreviations.
-- Keep functions focused and side-effect boundaries obvious.
-- Add tests when behavior changes.
-
-## Review Checklist
+        marker: "team/quality-checklist",
+        content: `## Quality Checklist
 - Is behavior correct for edge cases?
 - Are failure modes clear and actionable?
 - Is the change minimal for the goal?

package/src/self-update.ts

@@ -187,10 +187,11 @@ export function looksLikeMiseShim(
 }
 
 async function activeFcltUsesMiseNpmFacult(): Promise<boolean> {
-  if (!Bun.which("mise")) {
+  const misePath = Bun.which("mise") ?? (await resolveCommandPath("mise"));
+  if (!misePath) {
     return false;
   }
-  const fcltPath = Bun.which("fclt");
+  const fcltPath = Bun.which("fclt") ?? (await resolveCommandPath("fclt"));
   if (looksLikeMiseNpmFacultExecutable(fcltPath ?? "")) {
     return true;
   }
@@ -228,6 +229,24 @@ async function miseHasCurrentFacultTool(): Promise<boolean> {
   return (await proc.exited) === 0;
 }
 
+async function resolveCommandPath(command: string): Promise<string | null> {
+  const proc = Bun.spawn({
+    cmd: ["sh", "-lc", `command -v ${command}`],
+    stdin: "ignore",
+    stdout: "pipe",
+    stderr: "ignore",
+    env: process.env,
+  });
+  const [stdout, code] = await Promise.all([
+    new Response(proc.stdout).text(),
+    proc.exited,
+  ]);
+  if (code !== 0) {
+    return null;
+  }
+  return stdout.trim() || null;
+}
+
 function resolvePlatformTarget(): {
   platform: string;
   arch: string;
@@ -292,6 +311,7 @@ async function writeInstallState(args: {
   method: InstallMethod;
   packageVersion?: string;
   binaryPath?: string;
+  packageManager?: string;
 }) {
   const dir = dirname(facultInstallStatePath(args.home));
   await mkdir(dir, { recursive: true });
@@ -300,7 +320,11 @@ async function writeInstallState(args: {
     method: args.method,
     packageVersion: args.packageVersion,
     binaryPath: args.binaryPath,
-    source: args.method === "npm-binary-cache" ? "npm" : "direct",
+    packageManager: args.packageManager,
+    source:
+      args.method === "npm-binary-cache" || args.method === "mise-npm"
+        ? "npm"
+        : "direct",
     installedAt: new Date().toISOString(),
   };
   await Bun.write(
@@ -426,6 +450,7 @@ async function resolvePackageTargetVersion(requestedVersion?: string): Promise<{
 }
 
 async function selfUpdateViaPackageManager(args: {
+  home: string;
   requestedVersion?: string;
   dryRun: boolean;
   preferredPackageManager?: string;
@@ -464,6 +489,12 @@ async function selfUpdateViaPackageManager(args: {
     await runBestEffort(["mise", "reshim", `npm:${PACKAGE_NAME}`]);
   }
   await assertActiveFcltVersion(target.version, pm);
+  await writeInstallState({
+    home: args.home,
+    method: pm === "mise" ? "mise-npm" : "npm-binary-cache",
+    packageVersion: target.version,
+    packageManager: pm,
+  });
   console.log(`Updated fclt via ${pm}: ${PACKAGE_NAME}@${target.version}`);
   if (target.resolvedFromLatest) {
     console.log(`Resolved latest release to ${target.version}`);
@@ -617,6 +648,7 @@ export async function selfUpdateCommand(argv: string[]) {
     if (method === "npm-binary-cache" || method === "mise-npm") {
       await selfUpdateViaPackageManager({
         ...parsed,
+        home,
         method,
         preferredPackageManager:
           process.env.FACULT_INSTALL_PM?.trim() || state?.packageManager,

package/src/snippets-cli.ts

@@ -20,8 +20,8 @@ Usage:
   fclt snippets sync [--dry-run] [file...]
 
 Notes:
-  - <name> is the snippet marker name (e.g. codingstyle, global/codingstyle, myproject/context)
-  - Unscoped names (e.g. codingstyle) resolve to project snippet first (if in a git repo), then global.
+  - <name> is the snippet marker name (e.g. qualitychecklist, global/qualitychecklist, myproject/context)
+  - Unscoped names (e.g. qualitychecklist) resolve to project snippet first (if in a git repo), then global.
 `);
 }
 

package/src/snippets.ts

@@ -202,7 +202,7 @@ export function formatSnippetInjection(snippet: string): string {
 }
 
 export interface SnippetResolution {
-  /** The marker name requested (e.g. "codingstyle", "global/codingstyle", "myproj/context"). */
+  /** The marker name requested (e.g. "qualitychecklist", "global/qualitychecklist", "myproj/context"). */
   marker: string;
   /** The snippet file path used for injection. */
   path: string;