facult 2.13.5 → 2.14.0

package/README.md

@@ -31,6 +31,8 @@ Use it when AI setup has become scattered across dotfiles, tool homes, repos, pr
 
 Most usage should be agent-led after setup. Humans install, inspect, audit, and approve broad changes. Agents use `fclt` to find the right capability, preserve friction as writeback, and turn repeated signal into reviewed improvements.
 
+The basic operating unit is the work unit: a piece of agent work with a goal, context, constraints, evidence, an output artifact, verification, and a writeback target when the work teaches something reusable. That frame applies to normal coding, research, docs, setup, operations, and debugging work, not only to skill updates.
+
 ## What it does
 
 `fclt` helps you:
@@ -39,6 +41,7 @@ Most usage should be agent-led after setup. Humans install, inspect, audit, and
 - keep repo-specific capability in `<repo>/.ai`
 - inspect skills, instructions, MCP servers, agents, automations, and rendered outputs
 - compose guidance from smaller units with refs and snippets
+- give agents a reusable work-unit frame for normal work
 - optionally render approved capability into Codex, Claude, Cursor, and similar tools
 - record writebacks when an agent finds missing context, weak verification, stale guidance, or tool friction
 - turn repeated writeback into reviewable evolution proposals
@@ -89,9 +92,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:
 
@@ -138,6 +143,13 @@ fclt templates init operating-model --global
 fclt index --global
 ```
 
+Refresh an existing operating-model pack without overwriting local edits:
+
+```bash
+fclt templates init operating-model --global --update --dry-run
+fclt templates init operating-model --global --update
+```
+
 Create a repo-local `.ai` root:
 
 ```bash
@@ -149,8 +161,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 +224,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,12 +232,14 @@ 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.
 
+Work units give those assets a practical operating frame. They keep intent, evidence, verification, output, and learning attached to a task so repeated friction can become writeback and evolution instead of disappearing into chat history.
+
 ## Writeback and evolution
 
 Writeback is preserved signal from real work. Evolution turns repeated signal into reviewed changes.
@@ -276,6 +290,7 @@ Install it without managing any tool:
 fclt templates init operating-model --global
 fclt templates init operating-model --project
 fclt templates init operating-model --root /path/to/.ai
+fclt templates init operating-model --global --update
 ```
 
 The pack is also available as built-in refs under:
@@ -350,8 +365,8 @@ Canonical store:
 
 ```bash
 fclt templates list
-fclt templates init operating-model [--global|--project|--root PATH]
-fclt templates init project-ai
+fclt templates init operating-model [--global|--project|--root PATH] [--update]
+fclt templates init project-ai [--update]
 fclt templates init instruction <name>
 fclt templates init snippet <marker>
 fclt templates init skill <name>
@@ -398,9 +413,11 @@ Use `fclt --help` and `fclt <command> --help` for exact flags.
 Start with:
 
 - [Concepts](./docs/concepts.md): roots, scopes, state layers, and asset types
+- [Work Units](./docs/work-units.md): general-purpose agent work framing
 - [Composable Capability](./docs/composable-capability.md): refs, snippets, instruction templates, and evolvable units
 - [Project `.ai`](./docs/project-ai.md): repo-owned capability and project sync policy
 - [Built-in pack](./docs/built-in-pack.md): packaged work-unit, writeback, and evolution defaults
+- [Built-in pack upgrades](./docs/pack-upgrades.md): non-destructive refresh behavior for existing `.ai` roots
 - [Writeback and evolution](./docs/writeback-evolution.md): the feedback-loop workflow and review surfaces
 - [Managed mode](./docs/managed-mode.md): when to let `fclt` write tool files
 - [Roadmap](./docs/roadmap.md): current gaps and planned work
@@ -426,3 +443,7 @@ Commit canonical project assets that belong to the repo: instructions, snippets,
 ## Contributing
 
 Contributor and release workflow details live in [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## Background
+
+The operating model behind `fclt` is related to the argument in [Governing the Machine](https://www.hack.dance/writing/governing-the-machine): as machine execution gets cheaper, the hard problem becomes governing work, evidence, memory, integration, and improvement.

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

@@ -1,41 +1,41 @@
-# 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
+
+This file is the global entry template for the operating-model pack. It should
+stay small and composed from snippets. Put detailed doctrine in instructions,
+workflow execution in skills, and local/private preferences in user-owned or
+project-owned assets outside the public pack.
+
+## 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 checking integration boundaries, read ${refs.integration}.
+- 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/agents/evolution-planner/agent.toml

@@ -26,7 +26,10 @@ Return concise proposals ordered by expected leverage, including:
 - target asset
 - target scope
 - why this is the smallest durable change
+- source writeback ids or evidence summary
+- approval risk and verification path
 
 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.
+Do not globalize private, repo-specific, or speculative guidance.
 """

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

@@ -9,6 +9,13 @@ Prioritize:
 - rollout hazards
 - operational constraints
 - gaps between local verification and real system behavior
+- packaged, installed, rendered, or synced paths that differ from source behavior
+- parallel execution and state-location risks
+- privacy boundaries between global, project, generated, and machine-local state
 
-Return concise findings ordered by impact.
+Return concise findings ordered by impact. For each finding include:
+- boundary at risk
+- why the current evidence is or is not enough
+- strongest next verification step
+- whether the fix belongs in code, docs, a task, or capability evolution
 """

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

@@ -8,11 +8,18 @@ Prioritize:
 - project specificity
 - cross-project reuse potential
 - pollution risk from globalizing too early
+- private or repo-specific details that must not move into global capability
+- whether a smaller snippet, instruction, skill, or agent should be promoted instead of a broad doc
 
 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.
+Return concise decisions with:
+- recommended scope
+- target asset or smallest unit
+- evidence for reuse
+- privacy/pollution risk
+- promotion path or no-op rationale
 """

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

@@ -16,9 +16,11 @@ For each recommendation, prefer returning:
 - best target asset or destination
 - best scope (`project` or `global`)
 - the evidence that justifies recording it
+- whether the signal is enough for writeback only, task tracking, or evolution
 
 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.
+When the issue contains private project details, preserve the general learning without copying private details into a global asset.
 """

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/INTEGRATION.md

@@ -6,3 +6,47 @@ tags: [facult, integration, verification]
 # Integration
 
 Distinguish local correctness from system correctness. Check hidden dependencies, rollout order, and operational constraints before calling work done.
+
+## When To Use
+
+Use this when a local green signal may still fail at a boundary:
+
+- code passes focused tests but has not been checked against the real workflow
+- docs are correct in isolation but may send agents to a stale command or path
+- a tool command works locally but may fail under packaged, sandboxed, or parallel execution
+- a capability change renders into one agent tool but not another
+- a project-local improvement may collide with global defaults or managed output
+- a migration, release, or rollout has ordering constraints
+
+## Integration Questions
+
+Ask the smallest set that matches the risk:
+
+- What consumes this output?
+- What state does this depend on?
+- What happens if two agents or commands run this at the same time?
+- Does the packaged/released path behave like the source checkout?
+- Does the project-scoped path avoid leaking into global or public surfaces?
+- Does the global path avoid overwriting tool-native or user-edited state?
+- Is rollback or recovery clear if the integration fails?
+
+## Evidence
+
+Prefer evidence that crosses the boundary that could fail:
+
+- run the installed CLI, packaged binary, or generated artifact when source tests are not enough
+- inspect rendered output when changing snippets, refs, or agent docs
+- use temp roots and clean homes for setup, upgrade, and sync behavior
+- verify review artifacts land in global `~/.ai/writebacks` or `~/.ai/evolution`, not repo-local private state
+- check release, package, or plugin surfaces when the change affects users outside the repo
+
+## Output
+
+Return concise findings ordered by risk:
+
+- boundary checked
+- evidence used
+- remaining assumption
+- fix or follow-up if local correctness does not prove system correctness
+
+Record writeback when the same integration boundary repeatedly fails, the verification loop is too weak, or a missing skill/tool would make the boundary easier to check next time.

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/instructions/PROJECT_CAPABILITY.md

@@ -15,6 +15,28 @@ Default to `<repo>/.ai` when the capability is about:
 - repo-specific testing or verification
 - team conventions
 - project tools and workflows
+- product, customer, deployment, or operational context tied to one repo
+- examples that would leak private or irrelevant detail if copied globally
+
+Project capability should travel with the repo when it is safe to commit. Generated state, machine-local runtime state, secrets, and review queues should not travel with it.
+
+## Global Scope
+
+Use `~/.ai` when the capability should follow the user across projects:
+
+- general verification standards
+- reusable work-unit, feedback-loop, or writeback doctrine
+- user-owned language/tool preferences that are safe to share across repos
+- cross-project skills or agents
+- MCP/tool integration patterns that are not tied to one repo
+
+Global capability should be broadly useful and low-noise. A global rule that only helps one project is usually a project rule.
+
+## Review Artifacts
+
+Project-scoped writebacks and evolution proposals use the project as evidence, but their Markdown review artifacts are mirrored under global `~/.ai/writebacks/projects/<slug-hash>/` and `~/.ai/evolution/projects/<slug-hash>/`.
+
+Do not create repo-local `writebacks/` or `evolution/` review trees inside `<repo>/.ai`. Keep private review state out of the repo while preserving project metadata in the global review artifact frontmatter.
 
 ## Promote Carefully
 
@@ -23,6 +45,8 @@ 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
+- private examples can be removed or generalized without losing the rule
+- the target global unit is smaller than a broad rewrite
 
 Use:
 
@@ -31,3 +55,14 @@ fclt ai evolve promote EV-00001 --to global --project
 ```
 
 That creates a new global proposal for review. It does not auto-apply the promotion.
+
+## Decision Checklist
+
+Choose project when the answer depends on "this repo". Choose global when the answer would still be correct after removing the repo name.
+
+If unsure:
+
+1. keep the asset project-scoped
+2. record writeback with the reason it might generalize
+3. wait for another project or repeated evidence
+4. promote through a reviewable proposal, not by copying files by hand

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

@@ -9,6 +9,8 @@ A work unit is the smallest coherent unit of agent work that can be understood,
 
 It 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.
 
+Use work units for ordinary work, not only for capability updates. Coding changes, research answers, documentation edits, operational triage, setup repair, design reviews, and capability evolution all benefit from the same shape when the task has real uncertainty or risk.
+
 ## Minimum Contract
 
 A well-formed work unit names:
@@ -24,6 +26,8 @@ A well-formed work unit names:
 
 If one of these is missing and the gap blocks correctness, surface the gap early and recover it before moving faster.
 
+For low-risk one-step work, keep the contract implicit. For ambiguous, high-impact, cross-tool, stateful, or multi-step work, make the contract explicit before executing.
+
 ## Why It Exists
 
 Work-unit framing prevents shallow completion. It helps agents avoid:
@@ -34,6 +38,9 @@ Work-unit framing prevents shallow completion. It helps agents avoid:
 - creating duplicate tasks or proposals
 - turning one-off preferences into global rules
 - pushing project-specific details into global capability
+- producing output faster than the system can review, integrate, or learn from it
+
+The point is not paperwork. The point is to attach machine work to intent, context, evidence, and memory so that useful learning can change future work instead of disappearing into chat history.
 
 ## How To Use It
 
@@ -54,6 +61,47 @@ Writeback:
 
 Use the smallest framing that makes the task correct. Do not turn every request into paperwork.
 
+## Examples
+
+Coding:
+
+```text
+Goal: fix the failing login test
+Acceptance: test passes and no auth regression is introduced
+Context: failing test output, auth middleware, recent commits
+Constraints: preserve public API
+Evidence: focused test, relevant integration test
+Artifact: code diff and concise summary
+Verification: command output and changed behavior
+Writeback: only if the failure exposes stale test or auth guidance
+```
+
+Research:
+
+```text
+Goal: answer a source-backed product question
+Acceptance: answer cites current primary sources
+Context: user question, relevant docs, dates
+Constraints: distinguish verified facts from inference
+Evidence: source links and quotes within fair-use limits
+Artifact: answer or research note
+Verification: source freshness and consistency check
+Writeback: durable note if the finding will recur
+```
+
+Capability evolution:
+
+```text
+Goal: decide whether repeated writebacks justify a proposal
+Acceptance: proposal exists only if evidence repeats or a capability is clearly missing
+Context: grouped writebacks, target asset, current canonical guidance
+Constraints: avoid global noise and private leakage
+Evidence: writeback IDs and affected work units
+Artifact: accepted proposal, rejected proposal, or no-op note
+Verification: proposal kind, scope, target, and review artifact
+Writeback: only for new meta-learning about the evolution process
+```
+
 ## Writeback
 
 When the work reveals durable friction, missing capability, stale guidance, or a repeatable workflow, prefer one strong writeback over many weak ones.

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

@@ -12,6 +12,8 @@ Do not wait for a human operator by default if the signal is already clear and t
 
 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.
 
+The goal is a governed feedback loop: work creates evidence, evidence produces writeback, repeated writeback becomes a small reviewed proposal, and accepted proposals change future agent behavior.
+
 ## Scope Decision
 
 Choose `project` when the behavior depends on repo-local architecture or workflow.
@@ -20,14 +22,17 @@ Choose `global` when the behavior is broadly reusable.
 
 If unsure, start at project scope and promote later with evidence.
 
+Reject global scope when the proposal depends on private examples, one repo's architecture, a single user's temporary preference, or a workflow that has not repeated.
+
 ## 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
+1. Read current writebacks and existing proposals.
+2. Group or summarize repeated signal by asset, kind, and scope.
+3. Check the current target asset before proposing a change.
+4. Choose the smallest valid proposal kind.
+5. Draft the proposal with evidence and intended target.
+6. Accept only after the target and scope are correct.
+7. Apply only when the markdown target is the intended canonical asset.
 
 Use:
 
@@ -52,6 +57,8 @@ fclt templates init automation tool-call-audit
 
 If there is not yet enough repeated signal for evolution, record the writeback and stop there.
 
+Do not create a proposal only to preserve an idea. Preserve the idea as writeback, notes, or task tracking unless it has enough evidence to change capability.
+
 ## Proposal Kind Selection
 
 - `update_asset` for tightening existing guidance
@@ -62,9 +69,21 @@ If there is not yet enough repeated signal for evolution, record the writeback a
 
 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.
 
+## Review Criteria
+
+Before accept/apply, verify:
+
+- evidence is repeated or the missing capability is obvious
+- the proposal targets the smallest affected unit
+- project/global scope is correct
+- private or project-specific examples are not leaking into global assets
+- the patch changes canonical markdown assets, not generated runtime state
+- the resulting behavior can be verified by reading, rendering, indexing, or running the relevant command
+
 ## Output Contract
 - repeated signal
 - proposed asset change
 - target scope
 - evidence
 - smallest useful next step
+- approval or no-op rationale

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

@@ -8,8 +8,41 @@ tags: [facult, project, design]
 ## When To Use
 Use this skill when a project needs its own `.ai/` structure, repo-specific instructions, or local bootstrap guidance.
 
+Use it when:
+
+- a repo has recurring agent friction that should not become global doctrine
+- setup or verification steps are repeatedly rediscovered
+- project skills, agents, MCP definitions, or snippets need a stable source of truth
+- a repo needs policy for what may be rendered into tool homes
+- a project should contribute writeback/evolution evidence without committing private review artifacts
+
+Do not use it to copy a user's private global preferences into a public repo.
+
+## Design Rules
+
+- Start from the repo's real workflows, commands, and risk boundaries.
+- Keep project-specific guidance in `<repo>/.ai`.
+- Keep generated state, queues, review artifacts, and local machine config out of the repo.
+- Prefer a few high-leverage instructions or skills over a large generic dump.
+- Use snippets only for blocks that are reused or independently evolvable.
+- Make verification and integration paths explicit enough for future agents to run.
+- Add sync policy only for assets that should render into repo-local tool outputs.
+
+## Working Flow
+
+1. Inventory existing repo guidance and tool files.
+2. Identify repeated friction from recent work, issues, reviews, or writebacks.
+3. Separate project-specific behavior from global/user-owned behavior.
+4. Propose a minimal `.ai` layout.
+5. Add or update the smallest useful assets.
+6. Verify the graph/index and any rendered output.
+7. Record writeback for reusable learnings that should evolve later.
+
 ## Output Contract
 - recommended `.ai/` layout
 - what stays project-local
 - what stays global
 - what should remain generated runtime output only
+- sync/rendering policy
+- verification path
+- privacy or commit-safety risks

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,11 @@
+- 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 integration risk, read ${refs.integration}.
+- 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,7 @@
+- 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, a verification path, and a writeback target when the work teaches something reusable.
+- 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.
+- Treat work-unit framing as generally applicable to coding, research, writing, operations, setup, debugging, and capability evolution.
+- For deeper guidance, read ${refs.work_units}.