facult 2.13.9 → 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
@@ -140,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
@@ -228,6 +238,8 @@ Snippet markers let repeated blocks stay independently editable:
 
 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.
@@ -278,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:
@@ -352,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>
@@ -400,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
@@ -428,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,5 +1,10 @@
 # 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 -->
@@ -22,6 +27,7 @@
 - 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}.

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/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/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/core/feedback-loops.md

@@ -6,5 +6,6 @@
 - 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/work-units.md

@@ -1,6 +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, and a verification path.
+- 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}.

package/docs/README.md

@@ -9,9 +9,11 @@ The concepts guide includes the [feedback-loop diagram](./assets/fclt-capability
 ## Guides
 
 - [Concepts](./concepts.md): canonical roots, generated state, rendered outputs, scopes, and asset types.
+- [Work Units](./work-units.md): a general frame for agent work, evidence, verification, and writeback.
 - [Composable Capability](./composable-capability.md): refs, snippets, instruction templates, and evolvable units.
 - [Project `.ai`](./project-ai.md): how repo-local capability works without leaking project review state into the repo.
 - [Built-in pack](./built-in-pack.md): the packaged operating-model layer for writeback and evolution.
+- [Built-in pack upgrades](./pack-upgrades.md): non-destructive refresh behavior for existing `.ai` roots.
 - [Writeback and evolution](./writeback-evolution.md): how real-work friction becomes reviewable capability changes.
 - [Managed mode](./managed-mode.md): when to let `fclt` write tool files, and how adoption works.
 - [Security and trust](./security-trust.md): source trust, audit, secrets, and commit hygiene.
@@ -24,6 +26,7 @@ The concepts guide includes the [feedback-loop diagram](./assets/fclt-capability
 New users should read:
 
 - [Concepts](./concepts.md)
+- [Work Units](./work-units.md)
 - [Project `.ai`](./project-ai.md) if working in a repo
 - [Managed mode](./managed-mode.md) only before allowing `fclt` to write tool files
 - [Writeback and evolution](./writeback-evolution.md) before setting up feedback loops

package/docs/built-in-pack.md

@@ -35,6 +35,8 @@ Global doc:
 
 - `AGENTS.global.md`
 
+`AGENTS.global.md` is the composed entry template for global agent guidance. It should stay small and point to snippets and instructions rather than becoming the only place where guidance lives.
+
 ## When It Becomes Active
 
 The built-in pack is always available as a built-in source:
@@ -53,6 +55,15 @@ fclt templates init operating-model --root /path/to/.ai
 
 That writes the pack into the selected `.ai` root and rebuilds its index. It does not render files into Codex, Claude, or any other tool home.
 
+Refresh an existing root non-destructively:
+
+```bash
+fclt templates init operating-model --global --update --dry-run
+fclt templates init operating-model --global --update
+```
+
+`--update` refreshes only files that still match the last installed pack manifest and skips local edits. See [Built-in pack upgrades](./pack-upgrades.md).
+
 Use `project-ai` when the target is the current repo:
 
 ```bash
@@ -95,5 +106,7 @@ Keep project-specific behavior in project `.ai`. Promote it only when repeated e
 ## Next
 
 - Read [Composable Capability](./composable-capability.md) for refs, snippets, and instruction templates.
+- Read [Work Units](./work-units.md) for the general work-unit model.
+- Read [Built-in pack upgrades](./pack-upgrades.md) before refreshing an existing root.
 - Read [Writeback and evolution](./writeback-evolution.md) for the feedback loop.
 - Read [Managed mode](./managed-mode.md) before rendering the pack into a tool home.

package/docs/concepts.md

@@ -48,7 +48,9 @@ Use these as installable catalog sources. Review and trust source policy before
 
 A work unit is a scoped agent task with a goal, acceptance criteria, required context, constraints, evidence, output artifact, verification path, and writeback target.
 
-Agents should keep this implicit for simple work and make it explicit when the task is ambiguous, risky, or multi-step. The built-in operating-model pack includes `WORK_UNITS.md` so managed agents and canonical `.ai` roots can share the same framing.
+This applies to ordinary coding, research, docs, operations, setup, and debugging work, not only to skill or instruction updates. Agents should keep this implicit for simple work and make it explicit when the task is ambiguous, risky, stateful, or multi-step. The built-in operating-model pack includes `WORK_UNITS.md` so managed agents and canonical `.ai` roots can share the same framing.
+
+See [Work Units](./work-units.md) for the detailed model.
 
 ## State Layers
 
@@ -133,3 +135,4 @@ The durable loop is:
 - Read [Project `.ai`](./project-ai.md) before adding repo-local capability.
 - Read [Managed mode](./managed-mode.md) before allowing `fclt` to write tool files.
 - Read [Composable Capability](./composable-capability.md) to split guidance into instructions, snippets, skills, agents, MCP, and automations.
+- Read [Work Units](./work-units.md) to understand the general task frame behind writeback and evolution.

package/docs/pack-upgrades.md

@@ -0,0 +1,67 @@
+# Built-in Pack Upgrades
+
+The built-in operating-model pack is a starting point, not a source of destructive ownership over your `.ai` root.
+
+Use normal install for a new root:
+
+```bash
+fclt templates init operating-model --global
+fclt templates init operating-model --project
+fclt templates init operating-model --root /path/to/.ai
+```
+
+By default, existing files are skipped. This is safe for first install and for adding newly introduced pack files.
+
+## Non-Destructive Update
+
+Use `--update` to refresh only files that still match the previously installed pack copy:
+
+```bash
+fclt templates init operating-model --global --update --dry-run
+fclt templates init operating-model --global --update
+```
+
+`fclt` records a pack manifest under:
+
+```text
+.ai/.facult/packs/facult-operating-model.json
+```
+
+During `--update`, files are overwritten only when their current hash matches the last installed pack hash. If a user or agent edited a file locally, `fclt` skips it and reports it as a local edit.
+
+Use `--force` only when you intentionally want to replace the selected root's pack files:
+
+```bash
+fclt templates init operating-model --global --force
+```
+
+## Legacy Installs
+
+Older installs may not have a pack manifest. In that case, `--update` stays conservative:
+
+- files that already match the current pack are recorded in the manifest
+- missing files are added
+- edited or unknown existing files are skipped
+
+For a legacy root with many local changes, use an agent-assisted review:
+
+```bash
+fclt templates init operating-model --global --update --dry-run --json
+fclt doctor --json --global
+```
+
+Review skipped files before deciding whether to merge changes manually, keep the local version, or replace with `--force`.
+
+## AGENTS.global.md
+
+The pack includes `AGENTS.global.md` as a composed entry template. It is not meant to hold every rule.
+
+Use:
+
+- snippets for injected baseline blocks
+- instructions for detailed doctrine
+- skills for workflow execution
+- agents for delegated review roles
+- local/global config for private user-owned refs
+
+This keeps global agent guidance small while still making the full operating model discoverable.

package/docs/reference.md

@@ -48,8 +48,8 @@ The graph explains how instructions, snippets, config refs, and rendered targets
 
 ```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] [--force]
+fclt templates init project-ai [--update] [--force]
 fclt templates init instruction <name>
 fclt templates init snippet <marker>
 fclt templates init skill <name>

package/docs/work-units.md

@@ -0,0 +1,96 @@
+# Work Units
+
+A work unit is a governed unit of agent work. It gives a task enough shape to be executed, checked, integrated, and learned from.
+
+This is broader than capability evolution. Use work-unit framing for coding, research, docs, operations, setup, debugging, product work, and AI capability updates whenever the task has meaningful ambiguity or risk.
+
+## Minimum Shape
+
+A useful work unit names:
+
+- goal: the outcome needed
+- acceptance criteria: what must be true at the end
+- context: source files, systems, docs, messages, or decisions needed for correctness
+- constraints: privacy, permissions, compatibility, deadlines, ownership, and scope limits
+- evidence: checks that confirm progress or falsify assumptions
+- artifact: code, docs, issue, note, draft, proposal, report, or rendered output
+- verification: command, review surface, manual check, or source-of-truth read
+- writeback target: where durable learning belongs if the work teaches something reusable
+
+Keep this implicit for trivial work. Make it explicit when the task is ambiguous, stateful, high-impact, cross-tool, or likely to create reusable learning.
+
+## Why It Matters
+
+Machine execution makes output cheaper. That does not remove the governance problem. It moves pressure into intent, context, review, integration, memory, and feedback.
+
+Work units are the object that keeps those pieces attached. Without them, agents can produce more output while leaving humans to reconstruct what changed, why it changed, what evidence exists, and what should improve next time.
+
+With them:
+
+- the agent knows what done means
+- verification is chosen before the final claim
+- integration risk is visible
+- writeback has evidence and a target
+- repeated friction can become evolution instead of folklore
+
+## How It Connects To fclt
+
+`fclt` ships work-unit guidance in the built-in operating-model pack:
+
+```text
+@builtin/facult-operating-model/instructions/WORK_UNITS.md
+@builtin/facult-operating-model/snippets/global/core/work-units.md
+```
+
+Install it into a canonical root:
+
+```bash
+fclt templates init operating-model --global
+```
+
+Then agents can read the same guidance from `~/.ai/instructions/WORK_UNITS.md`, and rendered global agent files can include the work-unit snippet.
+
+## Examples
+
+Coding work:
+
+```text
+Goal: fix a failing checkout test
+Acceptance: the focused test and relevant integration path pass
+Context: failing output, checkout code, recent commits
+Constraints: preserve public API and user data behavior
+Evidence: test output plus inspected changed path
+Artifact: code diff and summary
+Verification: command output and integration check
+Writeback: only if the failure exposes reusable stale guidance
+```
+
+Research work:
+
+```text
+Goal: answer a product or technical question
+Acceptance: answer is current, source-backed, and separates facts from inference
+Context: user question, relevant docs, date sensitivity
+Constraints: use primary sources when accuracy depends on them
+Evidence: source links and consistency check
+Artifact: concise answer or research note
+Verification: source freshness and source agreement
+Writeback: durable note if the answer will recur
+```
+
+Capability evolution:
+
+```text
+Goal: decide whether writebacks justify changing capability
+Acceptance: proposal exists only when repeated evidence or a clear gap supports it
+Context: grouped writebacks, current target asset, project/global scope
+Constraints: avoid proposal noise and private leakage
+Evidence: writeback ids and affected work units
+Artifact: proposal, applied change, rejection, or no-op note
+Verification: target, scope, proposal kind, and rendered/review artifact
+Writeback: only for new meta-learning about the evolution loop
+```
+
+## Background
+
+The framing is related to the production-model argument in [Governing the Machine](https://www.hack.dance/writing/governing-the-machine): as more work becomes machine-mediated, the hard problem shifts from producing output to governing work, evidence, memory, and improvement.

package/package.json

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

package/src/agents.ts

@@ -150,6 +150,7 @@ export async function loadRenderContext(
     refs: {
       evolution: join(rootDir, "instructions", "EVOLUTION.md"),
       feedback_loops: join(rootDir, "instructions", "FEEDBACK_LOOPS.md"),
+      integration: join(rootDir, "instructions", "INTEGRATION.md"),
       learning_writeback: join(
         rootDir,
         "instructions",

package/src/builtin-assets.ts

@@ -2,5 +2,5 @@
 
 export const BUILTIN_OPERATING_MODEL_FILES = JSON.parse(
   // 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"}'
+  '{"AGENTS.global.md":"# Global Agent Instructions\\n\\nThis file is the global entry template for the operating-model pack. It should\\nstay small and composed from snippets. Put detailed doctrine in instructions,\\nworkflow execution in skills, and local/private preferences in user-owned or\\nproject-owned assets outside the public pack.\\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 checking integration boundaries, read ${refs.integration}.\\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- source writeback ids or evidence summary\\n- approval risk and verification path\\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.\\nDo not globalize private, repo-specific, or speculative guidance.\\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- packaged, installed, rendered, or synced paths that differ from source behavior\\n- parallel execution and state-location risks\\n- privacy boundaries between global, project, generated, and machine-local state\\n\\nReturn concise findings ordered by impact. For each finding include:\\n- boundary at risk\\n- why the current evidence is or is not enough\\n- strongest next verification step\\n- whether the fix belongs in code, docs, a task, or capability evolution\\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- private or repo-specific details that must not move into global capability\\n- whether a smaller snippet, instruction, skill, or agent should be promoted instead of a broad doc\\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:\\n- recommended scope\\n- target asset or smallest unit\\n- evidence for reuse\\n- privacy/pollution risk\\n- promotion path or no-op 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- whether the signal is enough for writeback only, task tracking, or evolution\\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.\\nWhen the issue contains private project details, preserve the general learning without copying private details into a global asset.\\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\\n## When To Use\\n\\nUse this when a local green signal may still fail at a boundary:\\n\\n- code passes focused tests but has not been checked against the real workflow\\n- docs are correct in isolation but may send agents to a stale command or path\\n- a tool command works locally but may fail under packaged, sandboxed, or parallel execution\\n- a capability change renders into one agent tool but not another\\n- a project-local improvement may collide with global defaults or managed output\\n- a migration, release, or rollout has ordering constraints\\n\\n## Integration Questions\\n\\nAsk the smallest set that matches the risk:\\n\\n- What consumes this output?\\n- What state does this depend on?\\n- What happens if two agents or commands run this at the same time?\\n- Does the packaged/released path behave like the source checkout?\\n- Does the project-scoped path avoid leaking into global or public surfaces?\\n- Does the global path avoid overwriting tool-native or user-edited state?\\n- Is rollback or recovery clear if the integration fails?\\n\\n## Evidence\\n\\nPrefer evidence that crosses the boundary that could fail:\\n\\n- run the installed CLI, packaged binary, or generated artifact when source tests are not enough\\n- inspect rendered output when changing snippets, refs, or agent docs\\n- use temp roots and clean homes for setup, upgrade, and sync behavior\\n- verify review artifacts land in global `~/.ai/writebacks` or `~/.ai/evolution`, not repo-local private state\\n- check release, package, or plugin surfaces when the change affects users outside the repo\\n\\n## Output\\n\\nReturn concise findings ordered by risk:\\n\\n- boundary checked\\n- evidence used\\n- remaining assumption\\n- fix or follow-up if local correctness does not prove system correctness\\n\\nRecord 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.\\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- product, customer, deployment, or operational context tied to one repo\\n- examples that would leak private or irrelevant detail if copied globally\\n\\nProject 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.\\n\\n## Global Scope\\n\\nUse `~/.ai` when the capability should follow the user across projects:\\n\\n- general verification standards\\n- reusable work-unit, feedback-loop, or writeback doctrine\\n- user-owned language/tool preferences that are safe to share across repos\\n- cross-project skills or agents\\n- MCP/tool integration patterns that are not tied to one repo\\n\\nGlobal capability should be broadly useful and low-noise. A global rule that only helps one project is usually a project rule.\\n\\n## Review Artifacts\\n\\nProject-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>/`.\\n\\nDo 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.\\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- private examples can be removed or generalized without losing the rule\\n- the target global unit is smaller than a broad rewrite\\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\\n## Decision Checklist\\n\\nChoose project when the answer depends on \\"this repo\\". Choose global when the answer would still be correct after removing the repo name.\\n\\nIf unsure:\\n\\n1. keep the asset project-scoped\\n2. record writeback with the reason it might generalize\\n3. wait for another project or repeated evidence\\n4. promote through a reviewable proposal, not by copying files by hand\\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\\nUse 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.\\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\\nFor 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.\\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- producing output faster than the system can review, integrate, or learn from it\\n\\nThe 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.\\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## Examples\\n\\nCoding:\\n\\n```text\\nGoal: fix the failing login test\\nAcceptance: test passes and no auth regression is introduced\\nContext: failing test output, auth middleware, recent commits\\nConstraints: preserve public API\\nEvidence: focused test, relevant integration test\\nArtifact: code diff and concise summary\\nVerification: command output and changed behavior\\nWriteback: only if the failure exposes stale test or auth guidance\\n```\\n\\nResearch:\\n\\n```text\\nGoal: answer a source-backed product question\\nAcceptance: answer cites current primary sources\\nContext: user question, relevant docs, dates\\nConstraints: distinguish verified facts from inference\\nEvidence: source links and quotes within fair-use limits\\nArtifact: answer or research note\\nVerification: source freshness and consistency check\\nWriteback: durable note if the finding will recur\\n```\\n\\nCapability evolution:\\n\\n```text\\nGoal: decide whether repeated writebacks justify a proposal\\nAcceptance: proposal exists only if evidence repeats or a capability is clearly missing\\nContext: grouped writebacks, target asset, current canonical guidance\\nConstraints: avoid global noise and private leakage\\nEvidence: writeback IDs and affected work units\\nArtifact: accepted proposal, rejected proposal, or no-op note\\nVerification: proposal kind, scope, target, and review artifact\\nWriteback: only for new meta-learning about the evolution process\\n```\\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\\nThe 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.\\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\\nReject 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.\\n\\n## Working Flow\\n\\n1. Read current writebacks and existing proposals.\\n2. Group or summarize repeated signal by asset, kind, and scope.\\n3. Check the current target asset before proposing a change.\\n4. Choose the smallest valid proposal kind.\\n5. Draft the proposal with evidence and intended target.\\n6. Accept only after the target and scope are correct.\\n7. 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\\nDo 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.\\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## Review Criteria\\n\\nBefore accept/apply, verify:\\n\\n- evidence is repeated or the missing capability is obvious\\n- the proposal targets the smallest affected unit\\n- project/global scope is correct\\n- private or project-specific examples are not leaking into global assets\\n- the patch changes canonical markdown assets, not generated runtime state\\n- the resulting behavior can be verified by reading, rendering, indexing, or running the relevant command\\n\\n## Output Contract\\n- repeated signal\\n- proposed asset change\\n- target scope\\n- evidence\\n- smallest useful next step\\n- approval or no-op rationale\\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\\nUse it when:\\n\\n- a repo has recurring agent friction that should not become global doctrine\\n- setup or verification steps are repeatedly rediscovered\\n- project skills, agents, MCP definitions, or snippets need a stable source of truth\\n- a repo needs policy for what may be rendered into tool homes\\n- a project should contribute writeback/evolution evidence without committing private review artifacts\\n\\nDo not use it to copy a user\'s private global preferences into a public repo.\\n\\n## Design Rules\\n\\n- Start from the repo\'s real workflows, commands, and risk boundaries.\\n- Keep project-specific guidance in `<repo>/.ai`.\\n- Keep generated state, queues, review artifacts, and local machine config out of the repo.\\n- Prefer a few high-leverage instructions or skills over a large generic dump.\\n- Use snippets only for blocks that are reused or independently evolvable.\\n- Make verification and integration paths explicit enough for future agents to run.\\n- Add sync policy only for assets that should render into repo-local tool outputs.\\n\\n## Working Flow\\n\\n1. Inventory existing repo guidance and tool files.\\n2. Identify repeated friction from recent work, issues, reviews, or writebacks.\\n3. Separate project-specific behavior from global/user-owned behavior.\\n4. Propose a minimal `.ai` layout.\\n5. Add or update the smallest useful assets.\\n6. Verify the graph/index and any rendered output.\\n7. Record writeback for reusable learnings that should evolve later.\\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- sync/rendering policy\\n- verification path\\n- privacy or commit-safety risks\\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 integration risk, read ${refs.integration}.\\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, a verification path, and a writeback target when the work teaches something reusable.\\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- Treat work-unit framing as generally applicable to coding, research, writing, operations, setup, debugging, and capability evolution.\\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

@@ -669,6 +669,7 @@ function canonicalRefValues(rootDir: string): Record<string, string> {
   return {
     evolution: join(rootDir, "instructions", "EVOLUTION.md"),
     feedback_loops: join(rootDir, "instructions", "FEEDBACK_LOOPS.md"),
+    integration: join(rootDir, "instructions", "INTEGRATION.md"),
     learning_writeback: join(
       rootDir,
       "instructions",

package/src/remote.ts

@@ -1,4 +1,5 @@
 import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import { mkdir, readdir, readFile, rm } from "node:fs/promises";
 import { homedir } from "node:os";
 import {
@@ -130,6 +131,7 @@ interface InstallResult {
   sourceTrustLevel: SourceTrustLevel;
   dryRun: boolean;
   changedPaths: string[];
+  skippedPaths?: string[];
 }
 
 interface UpdateCheckResult {
@@ -1298,17 +1300,64 @@ async function listFilesRecursive(rootDir: string): Promise<string[]> {
   return out.sort();
 }
 
+interface BuiltinPackManifest {
+  version: 1;
+  pack: string;
+  updatedAt: string;
+  files: Record<string, { sha256: string }>;
+}
+
+function sha256Text(value: string): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function builtinPackManifestPath(rootDir: string): string {
+  return join(rootDir, ".facult", "packs", "facult-operating-model.json");
+}
+
+async function readBuiltinPackManifest(
+  rootDir: string
+): Promise<BuiltinPackManifest | null> {
+  const pathValue = builtinPackManifestPath(rootDir);
+  if (!(await pathExists(pathValue))) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(await Bun.file(pathValue).text());
+    if (
+      parsed?.version === 1 &&
+      parsed.pack === "facult-operating-model" &&
+      isPlainObject(parsed.files)
+    ) {
+      return parsed as BuiltinPackManifest;
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+
+function serializeBuiltinPackManifest(manifest: BuiltinPackManifest): string {
+  return `${JSON.stringify(manifest, null, 2)}\n`;
+}
+
 async function scaffoldBuiltinOperatingModelPack(args: {
   rootDir: string;
   homeDir?: string;
   dryRun?: boolean;
   force?: boolean;
+  update?: boolean;
   installedAs?: string;
 }): Promise<InstallResult> {
   const rootDir = resolve(args.rootDir);
   const packRoot = facultBuiltinPackRoot("facult-operating-model");
   const files = await listFilesRecursive(packRoot);
   const changedPaths: string[] = [];
+  const skippedPaths: string[] = [];
+  const existingManifest = await readBuiltinPackManifest(rootDir);
+  const manifestFiles: BuiltinPackManifest["files"] = {
+    ...(existingManifest?.files ?? {}),
+  };
 
   for (const sourcePath of files) {
     const relPath = relative(packRoot, sourcePath);
@@ -1316,23 +1365,90 @@ async function scaffoldBuiltinOperatingModelPack(args: {
       continue;
     }
     const targetPath = join(rootDir, relPath);
+    const sourceText = await Bun.file(sourcePath).text();
+    const sourceHash = sha256Text(sourceText);
     const exists = await pathExists(targetPath);
-    if (exists && !args.force) {
+    let shouldWrite = !exists || Boolean(args.force);
+
+    if (exists && !shouldWrite) {
+      const targetText = await Bun.file(targetPath).text();
+      const targetHash = sha256Text(targetText);
+      if (targetHash === sourceHash) {
+        manifestFiles[relPath] = { sha256: sourceHash };
+      } else if (
+        args.update &&
+        existingManifest?.files[relPath]?.sha256 === targetHash
+      ) {
+        shouldWrite = true;
+      } else if (args.update) {
+        skippedPaths.push(targetPath);
+      }
+    }
+
+    if (!shouldWrite) {
       continue;
     }
     changedPaths.push(targetPath);
+    manifestFiles[relPath] = { sha256: sourceHash };
     if (!args.dryRun) {
       await mkdir(dirname(targetPath), { recursive: true });
-      await Bun.write(targetPath, await Bun.file(sourcePath).text());
+      await Bun.write(targetPath, sourceText);
     }
   }
 
   const configPath = join(rootDir, "config.toml");
-  if (!(await pathExists(configPath)) || args.force) {
+  const configRelPath = "config.toml";
+  const configText = "version = 1\n";
+  const configHash = sha256Text(configText);
+  const configExists = await pathExists(configPath);
+  let shouldWriteConfig = !configExists || Boolean(args.force);
+  if (configExists && !shouldWriteConfig) {
+    const targetText = await Bun.file(configPath).text();
+    const targetHash = sha256Text(targetText);
+    if (targetHash === configHash) {
+      manifestFiles[configRelPath] = { sha256: configHash };
+    } else if (
+      args.update &&
+      existingManifest?.files[configRelPath]?.sha256 === targetHash
+    ) {
+      shouldWriteConfig = true;
+    } else if (args.update) {
+      skippedPaths.push(configPath);
+    }
+  }
+  if (shouldWriteConfig) {
     changedPaths.push(configPath);
+    manifestFiles[configRelPath] = { sha256: configHash };
     if (!args.dryRun) {
       await mkdir(dirname(configPath), { recursive: true });
-      await Bun.write(configPath, "version = 1\n");
+      await Bun.write(configPath, configText);
+    }
+  }
+
+  const manifestPath = builtinPackManifestPath(rootDir);
+  const sortedManifestFiles = Object.fromEntries(
+    Object.entries(manifestFiles).sort(([a], [b]) => a.localeCompare(b))
+  );
+  const stableManifest = serializeBuiltinPackManifest({
+    version: 1,
+    pack: "facult-operating-model",
+    updatedAt: existingManifest?.updatedAt ?? "",
+    files: sortedManifestFiles,
+  });
+  const existingManifestText = (await pathExists(manifestPath))
+    ? await Bun.file(manifestPath).text()
+    : null;
+  if (existingManifestText !== stableManifest) {
+    const nextManifest = serializeBuiltinPackManifest({
+      version: 1,
+      pack: "facult-operating-model",
+      updatedAt: new Date().toISOString(),
+      files: sortedManifestFiles,
+    });
+    changedPaths.push(manifestPath);
+    if (!args.dryRun) {
+      await mkdir(dirname(manifestPath), { recursive: true });
+      await Bun.write(manifestPath, nextManifest);
     }
   }
 
@@ -1352,6 +1468,7 @@ async function scaffoldBuiltinOperatingModelPack(args: {
     sourceTrustLevel: "trusted",
     dryRun: Boolean(args.dryRun),
     changedPaths: uniqueSorted(changedPaths),
+    skippedPaths: uniqueSorted(skippedPaths),
   };
 }
 
@@ -1360,6 +1477,7 @@ async function scaffoldBuiltinProjectAiPack(args: {
   homeDir?: string;
   dryRun?: boolean;
   force?: boolean;
+  update?: boolean;
 }): Promise<InstallResult> {
   const cwd = resolve(args.cwd ?? process.cwd());
   return await scaffoldBuiltinOperatingModelPack({
@@ -1367,6 +1485,7 @@ async function scaffoldBuiltinProjectAiPack(args: {
     homeDir: args.homeDir,
     dryRun: args.dryRun,
     force: args.force,
+    update: args.update,
     installedAs: "project-ai",
   });
 }
@@ -2815,9 +2934,11 @@ function printTemplatesHelp() {
             ),
             renderCode("fclt templates init agents [--force] [--dry-run]"),
             renderCode(
-              "fclt templates init operating-model [--global|--project|--root PATH] [--force] [--dry-run]"
+              "fclt templates init operating-model [--global|--project|--root PATH] [--update] [--force] [--dry-run]"
+            ),
+            renderCode(
+              "fclt templates init project-ai [--update] [--force] [--dry-run]"
             ),
-            renderCode("fclt templates init project-ai [--force] [--dry-run]"),
             renderCode(
               "fclt templates init automation <template-id> [--scope global|project|wide] [--name <name>] [--project-root <path>] [--cwds <path1,path2>] [--rrule <RRULE>] [--status PAUSED|ACTIVE] [--yes] [--dry-run]"
             ),
@@ -3322,6 +3443,7 @@ export async function templatesCommand(
   }
   const dryRun = args.includes("--dry-run");
   const force = args.includes("--force");
+  const update = args.includes("--update");
   const json = args.includes("--json");
   const parsedArgs = parseTemplateInitArgs(args);
   const positional = parsedArgs.positional;
@@ -3333,6 +3455,7 @@ export async function templatesCommand(
         homeDir: ctx.homeDir,
         dryRun,
         force,
+        update,
       });
       if (json) {
         console.log(JSON.stringify(result, null, 2));
@@ -3348,6 +3471,14 @@ export async function templatesCommand(
               title: "Changed Paths",
               lines: renderBullets(result.changedPaths),
             },
+            ...(result.skippedPaths?.length
+              ? [
+                  {
+                    title: "Skipped Local Edits",
+                    lines: renderBullets(result.skippedPaths),
+                  },
+                ]
+              : []),
           ],
         })
       );
@@ -3378,6 +3509,7 @@ export async function templatesCommand(
         homeDir: ctx.homeDir,
         dryRun,
         force,
+        update,
       });
       if (json) {
         console.log(JSON.stringify(result, null, 2));
@@ -3393,6 +3525,14 @@ export async function templatesCommand(
               title: "Changed Paths",
               lines: renderBullets(result.changedPaths),
             },
+            ...(result.skippedPaths?.length
+              ? [
+                  {
+                    title: "Skipped Local Edits",
+                    lines: renderBullets(result.skippedPaths),
+                  },
+                ]
+              : []),
           ],
         })
       );