facult 2.8.8 → 2.8.9

package/README.md

@@ -31,7 +31,7 @@ It helps you:
 - render managed tool files into Codex, Claude, Cursor, and similar tools
 - inspect dependencies, provenance, and rendered outputs
 - review trust and audit remote or local capability before it spreads
-- capture writebacks and evolve canonical assets over time
+- capture real-work friction as writeback and evolve canonical assets over time
 
 ## Quick Start
 
@@ -203,11 +203,18 @@ Useful AI behavior is composable. You need small reusable parts, a clean way to
 ## Built-in Defaults
 
 `fclt` includes a built-in layer for writeback and evolution. By default, that layer provides:
-- instructions for evolution, integration, and project capability
+- instructions for learning/writeback, evolution, integration, and project capability
 - agents such as `writeback-curator`, `evolution-planner`, and `scope-promoter`
 - skills such as `capability-evolution` and `project-operating-layer-design`
 
-Those built-in defaults become live when you manage a tool. Global tool management renders the bundled docs, agents, and skills into that tool’s live files. Project-local `.ai` roots do not sync the built-in operating-model layer unless you explicitly enable it.
+Those built-in defaults become live when you manage a tool. Global tool management renders the bundled docs, agents, and skills into that tool's live files, so every managed agent sees that it can preserve strong friction with `fclt ai writeback ...` and escalate repeated signal with `fclt ai evolve ...`. Project-local `.ai` roots do not sync the built-in operating-model layer unless you explicitly enable it.
+
+The intended feedback loop is:
+1. agents notice durable friction, weak verification, stale guidance, or missing capability during normal work
+2. agents record one strong writeback when the signal, target, and scope are clear
+3. humans or scheduled automations review grouped writebacks and existing proposals
+4. only repeated evidence, a clearly missing capability, or a stale canonical asset becomes an evolution proposal
+5. accepted proposals update canonical markdown assets, skills, snippets, or project/global instructions
 
 If you want to disable default built-in sync for one canonical root:
 
@@ -224,8 +231,9 @@ Put that in `config.toml` or `config.local.toml` under the active canonical root
 
 `fclt` is CLI-first. The practical setup is:
 1. Install `fclt` globally so any agent runtime can execute it.
-2. Put allowed `fclt` workflows in your agent instructions and skills.
-3. Optionally scaffold MCP wrappers if you want an MCP entry that delegates to `fclt`.
+2. Manage each agent tool with `fclt manage <tool>` and `fclt sync`.
+3. Let the built-in operating-model layer render global writeback/evolution instructions into the tool.
+4. Optionally scaffold MCP wrappers if you want an MCP entry that delegates to `fclt`.
 
 ```bash
 # Scaffold reusable templates in the canonical store
@@ -250,6 +258,7 @@ fclt sync
 ```
 
 Note: `templates init mcp ...` is a scaffold, not a running server by itself.
+The supported review surface today is the CLI plus generated Codex automation templates; MCP is an optional wrapper path when an agent environment prefers MCP calls over shell commands.
 
 ## Mental Model
 
@@ -455,9 +464,18 @@ Use writeback when:
 - an instruction or agent was missing key context
 - a pattern proved reusable enough to become doctrine
 - a project-local pattern deserves promotion toward global capability
+- a skill, tool, prompt, or default behavior repeatedly slows agents down without hard-failing
 
 Do not think of writeback as note-taking. Treat it as preserved signal that should improve the system.
 
+Recommended agent behavior:
+- record a writeback directly when the learning is durable, scoped, and targetable
+- prefer project scope for repo-specific tooling, tests, architecture, or workflow
+- use global scope for shared doctrine, shared skills, shared agents, or cross-project capability gaps
+- group or summarize before proposing evolution unless the missing capability is already obvious
+- use the smallest proposal kind that fits: `update_asset`, `create_asset`, `extract_snippet`, `add_skill`, or `promote_asset`
+- do not create proposals for one-off preferences, speculative ideas, or duplicate noise
+
 Current apply semantics are intentionally policy-bound:
 - targets are resolved through the generated graph when possible and fall back to canonical ref resolution for missing assets
 - apply is limited to markdown canonical assets
@@ -471,6 +489,14 @@ Current review/draft semantics:
 - rerunning `evolve draft <id> --append ...` revises the draft and records draft history
 - `evolve promote --to global` creates a new high-risk global proposal from a project-scoped proposal; that promoted proposal can then be drafted, reviewed, and applied into `~/.ai`
 
+Review surfaces:
+- `fclt status --json` reports queue/proposal paths and counts for the active scope
+- `fclt ai writeback list|show|group|summarize` reviews raw and clustered signal
+- `fclt ai evolve list|show|review` reviews proposal state without applying changes
+- `fclt templates init automation learning-review` scaffolds background writeback capture/review
+- `fclt templates init automation evolution-review` scaffolds periodic proposal review
+- `fclt templates init automation tool-call-audit` scaffolds repeated tool-friction review
+
 ### Scope and source selection
 
 Most inventory and sync commands support explicit canonical-root selection:
@@ -614,6 +640,8 @@ Recommended topology:
 - Use a separate wide/global automation only for cross-repo or shared-surface review, such as global doctrine, shared skills, or repeated tool/agent patterns across repos.
 - If you do use a wide learning review, keep the `cwds` list intentionally small and related. The prompt is designed to partition by cwd first, not to blur unrelated repos together.
 - A practical default is daily `learning-review` plus weekly `evolution-review`. The first finds and records durable signal; the second keeps proposal review from stalling.
+- Add `tool-call-audit` when you want a focused background loop for repeated tool failures, missing skills, excessive retries, or shallow-success patterns.
+- Treat automations as review and synthesis loops. They should create writebacks and proposals when evidence is strong, but high-risk global changes still move through proposal review before apply.
 
 Files are written to:
 
@@ -799,7 +827,7 @@ Contributor and release workflow details live in [CONTRIBUTING.md](./CONTRIBUTIN
 
 Not as a first-party `fclt mcp serve` runtime.
 
-`fclt` currently focuses on inventory, trust/audit, install/update, and managed sync of canonical AI capability and tool-native outputs.
+`fclt` currently focuses on inventory, trust/audit, install/update, writeback/evolution, and managed sync of canonical AI capability and tool-native outputs. Use the CLI directly from agents, or scaffold an MCP definition that delegates to the CLI when an environment needs an MCP-shaped entrypoint.
 
 ### Does fclt now manage global AI config, not just skills and MCP?
 

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

@@ -0,0 +1,20 @@
+# Facult Operating Defaults
+
+This machine has a default Facult operating-model layer 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. When repeated writebacks or clearly missing capability point at a concrete improvement, use `fclt ai evolve ...` or the `capability-evolution` skill to make a reviewable proposal.
+
+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

package/assets/packs/facult-operating-model/agents/evolution-planner/agent.toml

@@ -0,0 +1,32 @@
+name = "evolution-planner"
+description = "Turn repeated writeback into concrete capability proposals."
+
+developer_instructions = """
+You plan capability evolution.
+
+Prioritize:
+- smallest useful change
+- correct target asset type
+- correct target scope
+- evidence that justifies the change
+- repeated writeback clusters or clearly missing capabilities, not isolated preferences
+
+Proposal kinds you should consider first:
+- update_asset
+- create_asset
+- extract_snippet
+- add_skill
+- promote_asset
+
+Default to project scope when the pattern is repo-local.
+Promote to global only when reuse is demonstrated and pollution risk is low.
+
+Return concise proposals ordered by expected leverage, including:
+- proposal kind
+- target asset
+- target scope
+- why this is the smallest durable change
+
+Do not escalate to evolution when a single writeback is enough.
+Do not use evolution as a substitute for executable task tracking when the main need is owner, priority, state, or implementation follow-through.
+"""

package/assets/packs/facult-operating-model/agents/integration-auditor/agent.toml

@@ -0,0 +1,14 @@
+name = "integration-auditor"
+description = "Find where local success can still fail system-wide."
+
+developer_instructions = """
+You audit integration risk.
+
+Prioritize:
+- hidden dependencies
+- rollout hazards
+- operational constraints
+- gaps between local verification and real system behavior
+
+Return concise findings ordered by impact.
+"""

package/assets/packs/facult-operating-model/agents/scope-promoter/agent.toml

@@ -0,0 +1,18 @@
+name = "scope-promoter"
+description = "Decide whether learning belongs at project or global scope."
+
+developer_instructions = """
+You decide scope.
+
+Prioritize:
+- project specificity
+- cross-project reuse potential
+- pollution risk from globalizing too early
+
+When recommending promotion, make the standard path explicit:
+- keep the source capability in project scope until promotion is approved
+- create a reviewable global proposal
+- do not treat promotion as implicit apply
+
+Return concise decisions with rationale.
+"""

package/assets/packs/facult-operating-model/agents/writeback-curator/agent.toml

@@ -0,0 +1,24 @@
+name = "writeback-curator"
+description = "Turn noisy outcomes into high-signal writeback."
+
+developer_instructions = """
+You curate durable writeback.
+
+Prioritize:
+- repeated failures
+- repeated wins
+- stale guidance
+- missing capability edges
+- tool, skill, MCP, plugin, automation, or instruction friction that repeatedly slows work down
+
+For each recommendation, prefer returning:
+- suggested writeback kind
+- best target asset or destination
+- best scope (`project` or `global`)
+- the evidence that justifies recording it
+
+Do not emit low-signal noise.
+If the learning is repo-specific, keep it project-scoped by default.
+When the signal is already strong and the target is clear, prefer recommending direct writeback capture rather than abstract advice.
+When the issue is executable tooling work, recommend task tracking for the fix and writeback only for the reusable operating-model learning.
+"""

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

@@ -0,0 +1,130 @@
+---
+description: Turn repeated signal into concrete capability changes.
+tags: [facult, evolution, writeback]
+---
+
+# Evolution
+
+Use writeback and evolution to improve the AI operating layer itself.
+
+Evolution 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.
+
+## When To Record Writeback
+
+Record writeback when one of these is true:
+
+- the same failure repeats
+- the same success pattern repeats
+- guidance is stale or missing
+- a prompt or loop has to be restated often
+- a project-specific pattern looks reusable
+
+Do not record low-signal noise:
+
+- one-off annoyance with no reuse value
+- generic "could be better" commentary
+- duplicate observations with no new evidence
+
+The 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.
+
+Do 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.
+
+## Scope
+
+Choose `project` scope when the learning depends on:
+
+- repo architecture
+- team workflow
+- project tooling
+- local testing or verification behavior
+
+Choose `global` scope when the learning is reusable across projects.
+
+Promote from project to global only after repeated reuse or strong evidence.
+
+## Writeback Kinds
+
+Common kinds:
+
+- `weak_verification`
+- `false_positive`
+- `missing_context`
+- `reusable_pattern`
+- `capability_gap`
+- `bad_default`
+
+Every good writeback should try to include:
+
+- a concrete summary
+- the best target asset if known
+- the right scope
+- domain or tags when useful
+
+## Operator Flow
+
+Typical workflow:
+
+```bash
+fclt ai writeback add --kind weak_verification --summary "Checks were too shallow" --asset instruction:VERIFICATION
+fclt ai writeback group --by asset
+fclt ai writeback summarize --by domain
+fclt ai evolve propose
+fclt ai evolve draft EV-00001
+fclt ai evolve accept EV-00001
+fclt ai evolve apply EV-00001
+```
+
+Use `fclt ai evolve draft <id> --append "..."` to revise a draft while preserving draft history.
+
+Review surfaces:
+
+- `fclt status --json` for queue/proposal paths, counts, and active scope
+- `fclt ai writeback list|show|group|summarize` for raw and clustered signal
+- `fclt ai evolve list|show|review` for proposal state without applying changes
+- `fclt templates init automation learning-review` for recurring capture/review
+- `fclt templates init automation evolution-review` for recurring proposal review
+- `fclt templates init automation tool-call-audit` for repeated tool-friction review
+
+Evolution proposal metadata, markdown drafts, patch artifacts, writeback queues,
+and journals are runtime state. `fclt` stores them in machine-local Facult state;
+canonical assets in `~/.ai` or `<repo>/.ai` should only change when a proposal is
+applied.
+
+## Default Agent Behavior
+
+Use the smallest action that fits the signal:
+
+1. record one strong writeback when there is a clear durable learning
+2. use `writeback-curator` when the target, kind, or scope is ambiguous
+3. use `capability-evolution` or `evolution-planner` when repeated signal should become a proposal
+4. do not draft or apply proposals just because a writeback exists; require repeated evidence or a clearly missing capability
+
+Avoid creating writeback/evolution noise for one-off nits, vague preferences, or speculative ideas without evidence.
+
+When the friction is executable product/tooling work that needs ownership,
+priority, state, or implementation follow-through, create or update a real task
+system item instead of forcing it into capability evolution. Use evolution for
+the reusable operating-layer change.
+
+## Proposal Kinds
+
+Current supported proposal kinds:
+
+- `update_asset`
+- `create_asset`
+- `extract_snippet`
+- `add_skill`
+- `promote_asset`
+
+Use the smallest durable change that fits the evidence.
+
+## Review And Apply Rules
+
+- draft before apply
+- accept before apply
+- prefer the smallest safe change
+- keep reviewable evidence tied to source writebacks
+- do not globalize project behavior too early
+- do not apply high-risk global instruction, skill, plugin, or non-COS changes without explicit review/approval
+
+Apply is for markdown canonical assets only. If the target is wrong, revise the proposal rather than forcing it through.

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

@@ -0,0 +1,8 @@
+---
+description: Detect where local success can still fail at integration boundaries.
+tags: [facult, integration, verification]
+---
+
+# Integration
+
+Distinguish local correctness from system correctness. Check hidden dependencies, rollout order, and operational constraints before calling work done.

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

@@ -0,0 +1,63 @@
+---
+description: Preserve durable signal and record writeback when the operating layer should learn.
+tags: [facult, learning, writeback]
+---
+
+# Learning And Writeback
+
+Use this when work produces a durable decision, failure, success pattern, or missing guardrail that should outlive the current task.
+
+This 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.
+
+## Default Behavior
+
+The normal path should be agent-driven.
+
+If you can clearly answer:
+
+- what was learned
+- why it matters
+- where it should land
+- whether it belongs in `project` or `global`
+
+then record the writeback instead of only suggesting that someone should do it later.
+
+Use:
+
+```bash
+fclt ai writeback add --kind <kind> --summary "<summary>" --asset <asset-selector>
+```
+
+The writeback queue is runtime state, not canonical source. `fclt` stores it in
+machine-local Facult state so sandboxed agents can record durable friction
+without mutating `~/.ai` or a repo-local `.ai` unless an evolution proposal is
+later reviewed and applied.
+
+Project-scoped writebacks should usually be recorded from the repo that produced
+the evidence. Global writebacks should be reserved for shared doctrine, shared
+skills, shared agents, tool behavior, or cross-project capability gaps.
+
+## Record Writeback When
+
+- the same failure or weak loop appears again
+- a reusable success pattern shows up
+- guidance is clearly stale or missing
+- a repo-local behavior probably belongs in project capability
+- 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
+
+## Do Not Record Writeback For
+
+- one-off annoyance with no durable value
+- weak commentary with no target
+- speculative ideas without evidence
+- duplicate noise with no new signal
+
+## Follow Through
+
+- prefer one strong writeback over many weak ones
+- mention the writeback id when summarizing what changed
+- escalate to `capability-evolution` or `fclt ai evolve ...` only when the signal is repeated or clearly points at a durable capability change
+- use `fclt ai writeback group --by asset` or `fclt ai writeback summarize --by domain` to review accumulated signal before proposing broad changes
+- use scheduled `learning-review`, `evolution-review`, or `tool-call-audit` automations when the signal should be reviewed in the background

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

@@ -0,0 +1,33 @@
+---
+description: Decide what belongs in repo-local .ai versus the global store.
+tags: [facult, project, scope]
+---
+
+# Project Capability
+
+Prefer project scope when the guidance depends on repo architecture, team workflow, or colocated tooling. Promote to global only after repeated cross-project reuse.
+
+## Project First
+
+Default to `<repo>/.ai` when the capability is about:
+
+- local architecture
+- repo-specific testing or verification
+- team conventions
+- project tools and workflows
+
+## Promote Carefully
+
+Promote to `~/.ai` only when:
+
+- the same pattern succeeds in more than one repo
+- the capability is not coupled to local architecture
+- the global version will not create noise for unrelated projects
+
+Use:
+
+```bash
+fclt ai evolve promote EV-00001 --to global --project
+```
+
+That creates a new global proposal for review. It does not auto-apply the promotion.

package/assets/packs/facult-operating-model/skills/capability-evolution/SKILL.md

@@ -0,0 +1,70 @@
+---
+description: Convert repeated writeback into concrete fclt capability proposals.
+tags: [facult, evolution, writeback]
+---
+
+# capability-evolution
+
+## When To Use
+Use this skill when the same missing guidance, weak loop, or recurring win appears often enough that the AI system itself should probably change.
+
+Do 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.
+
+Use 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.
+
+## Scope Decision
+
+Choose `project` when the behavior depends on repo-local architecture or workflow.
+
+Choose `global` when the behavior is broadly reusable.
+
+If unsure, start at project scope and promote later with evidence.
+
+## Working Flow
+
+1. record the strongest writeback
+2. group or summarize repeated signal
+3. choose the smallest valid proposal kind
+4. draft the proposal
+5. accept only after the target and scope are correct
+6. apply only when the markdown target is the intended canonical asset
+
+Use:
+
+```bash
+fclt ai writeback add ...
+fclt ai writeback group --by asset
+fclt ai writeback summarize --by domain
+fclt ai evolve propose
+fclt ai evolve draft EV-00001
+fclt ai evolve draft EV-00001 --append "tighten the rule with a concrete verification step"
+fclt ai evolve accept EV-00001
+fclt ai evolve apply EV-00001
+```
+
+For background review loops, use:
+
+```bash
+fclt templates init automation learning-review
+fclt templates init automation evolution-review
+fclt templates init automation tool-call-audit
+```
+
+If there is not yet enough repeated signal for evolution, record the writeback and stop there.
+
+## Proposal Kind Selection
+
+- `update_asset` for tightening existing guidance
+- `create_asset` for missing instructions or docs
+- `extract_snippet` for reusable partial guidance
+- `add_skill` for reusable workflow instruction
+- `promote_asset` for project-to-global promotion
+
+Use 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.
+
+## Output Contract
+- repeated signal
+- proposed asset change
+- target scope
+- evidence
+- smallest useful next step

package/assets/packs/facult-operating-model/skills/project-operating-layer-design/SKILL.md

@@ -0,0 +1,15 @@
+---
+description: Design or improve a repo-local .ai operating layer.
+tags: [facult, project, design]
+---
+
+# project-operating-layer-design
+
+## When To Use
+Use this skill when a project needs its own `.ai/` structure, repo-specific instructions, or local bootstrap guidance.
+
+## Output Contract
+- recommended `.ai/` layout
+- what stays project-local
+- what stays global
+- what should remain generated runtime output only

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "facult",
-  "version": "2.8.8",
+  "version": "2.8.9",
   "description": "Manage canonical AI capabilities, sync surfaces, and evolution state.",
   "type": "module",
   "license": "MIT",
@@ -27,6 +27,8 @@
     "access": "public"
   },
   "files": [
+    "assets/**/*.md",
+    "assets/**/*.toml",
     "bin/fclt.cjs",
     "bin/facult.cjs",
     "src/**/*.ts",